Set up Balladeer

Connect your laptop once, then use Balladeer in checkouts of your team's connected repositories. Each teammate pairs their own machine. Repository enrollment and optional sealed CI setup are separate administrator steps.

Before you start#

You need Node 22 or newer and access to a Balladeer workspace. Automatic installation supports macOS and Linux with zsh, bash, or sh. Windows automatic installation is not qualified; follow the manual npm installation instructions and verify the command separately.

Run this in your terminal, or ask your agent to read the current setup instructions and help:

npx -y balladeer@latest setup

Setup installs the command, registers Balladeer for Claude Code and Codex at user scope, and opens browser approval. Sign in and approve the intended workspace yourself. It waits up to ten minutes at a terminal or ninety seconds from an agent shell. If that wait ends, finish approval and repeat the command to resume. --no-open prints the link instead; --json is the machine-readable path.

You can pair outside a repository. To work with a particular repository, open its checkout and finish any connection steps setup reports. Installation alone does not enroll a repository or establish that CI is working.

Agentic code review on push is included#

When setup installs the durable command, it also installs the report-mode push hooks for Claude Code and Codex at user scope. After your agent pushes in a connected repository or worktree, the code review reports on agreed promises whose code was touched. It uses your existing agent login, needs no separate model key, and does not wait for sealed CI qualification. Agreed promises are tied to their code automatically on their first push.

In Codex, type /hooks and trust Balladeer’s hooks when asked. Until trusted, configuration and MCP tool access do not prove the push check runs. If the executable could not be installed, setup reports that the push check is unavailable.

Turn the laptop-wide check off with balladeer judge --push-check off, or back on with balladeer judge --push-check on. See agentic code review on push for results, repository-specific hooks, and optional block mode.

Join an existing workspace#

Accept your invitation first. In the intended checkout, use:

npx -y balladeer@latest setup --existing

The joining path does not add a repository or change CI. It connects this machine to an enrolled repository. If the repository is not enrolled, browser onboarding can continue while an administrator connects it. Somebody else's successful setup does not put a credential on your laptop.

Existing project integrations can still select their client explicitly, for example npx -y balladeer@latest setup --client codex --existing or --client claude. The install step registers both supported coding hosts; those flags select the project integration.

To choose another workspace, use setup --existing --choose-workspace --wait and select it in the browser. Keep any explicit client choice on that command. Do not edit the credential store by hand.

Start a workspace and connect a repository#

Tell your agent the workspace name and the GitHub repositories you intend to connect. You create the workspace in your browser. An administrator can enroll repositories and prepare the CI workflow pull request using locally authenticated Git and GitHub CLI (gh). Balladeer receives no GitHub token.

Review and merge the workflow through your normal process. Adding several repositories to a workspace does not install CI in every repository: complete the reported checkout-specific steps for each one. Slack is connected separately through workspace settings.

How do I know it worked?#

Open a fresh coding-agent session in a connected checkout, then check these separately:

An empty promise list is not a connection failure. In an unrelated folder Balladeer stays quiet. Git remotes determine the connection, including an upstream remote for a fork; another checkout or worktree of a connected repository does not need its own global installation.

What changes on my machine?#

Installation registers the MCP server and guidance hooks in your user-level Claude Code and Codex configuration. Entries normally run the installed command by its absolute path. Setup may add a bounded shell PATH entry and stores private credentials outside the checkout. Existing project integrations and explicit refresh paths may also write .codex/config.toml, AGENTS.md, .mcp.json, or Claude's project configuration. Read setup's actual report for the files it changed.

Setup detects the earlier July client and removes its recognized integration, retaining copies of changed untracked files. This is installation cleanup, not conversion of earlier decisions into promises. Do not use --force as a general repair: it means setting up alongside the earlier client.

Read data and permissions for connection ownership and revocation.

Updates and recovery#

balladeer update

This updates the durable command to the latest published release. If it is missing, use npx -y balladeer@latest install to install or repair it without pairing or changing CI. Hooks can start a background update when a newer release is advertised, at most once a day; a later session uses the updated command. Centrally served guidance can change independently of the CLI.

Reopen the terminal or coding host after installation and verify again. Setup cannot change a running parent process's PATH. For an existing project integration that explicitly needs repair, follow the reported client-specific setup --refresh instruction. Refresh is not workspace pairing.

For refused writes, an unavailable connection, or an agent that stays quiet, follow troubleshoot setup and agent behavior. Keep saved credentials; do not use sudo or remove the store as a retry.

Next: Agentic code review on push.