docs / getting started

Getting started.

Two steps are required: create the workspace, get connected. Everything else (inviting your team, GitHub, your own model key, seeding where enabled) is optional and can happen later, in any order.

1 · Create your workspace

Sign in at app.balladeer.ai; the wizard walks you through it. Connecting GitHub lets merged PRs check off decisions automatically (it is never used to invent decisions): the connection is a read-only GitHub App that cannot read your code (its permissions cover pull requests, issues, and membership, never repository contents), and you choose which repositories it can see on GitHub's install screen. If your repositories live in an organization, pick the organization in GitHub's account chooser there; it lists your personal account first. After connecting, the card shows which account the installation landed on and how many repositories it can see, and warns if it can see none. Where it is enabled for your workspace, seeding gives the memory a head start from docs you choose.

2 · Get connected (terminal)

Paste one line into your coding agent (Claude Code, Cursor, or Codex). It installs the client, guides you through approving this machine, installs its Balladeer guidance, and then pauses for the connector sign-in only you can complete:

3 · Or run it yourself

Then wire your agents. balladeer setup is the one command that does it: it lists the coding agents it finds on this machine, you pick the ones you use, and it runs each one's setup for you. A fresh install at an interactive terminal offers it by itself. Or wire them one at a time:

• Claude Code: balladeer setup-claude-code installs the connector, status line, and guidance. On a paired machine running Claude Code 2.1.163 or newer, it also uses a thin local transport so one conversation stays distinct through resume, clear, and compact, while a fork gets its own scope. Close and reopen Claude Code so it loads that connector, open /mcp, and finish with a real Balladeer read. If setup kept the direct hosted connector instead, complete Authenticate there.
• Cursor: balladeer setup-cursor in each project. It registers the hosted connector in ~/.cursor/mcp.json, keeping any other MCP servers there, and writes Cursor's own always-apply rule at .cursor/rules/balladeer.mdc; commit that file so teammates get it when they clone. Without restarting, click Authenticate on the Balladeer server under Installed MCP Servers to sign in.
• Codex: balladeer setup-codex, then codex mcp login balladeer to authenticate; no restart is required.
• Other AGENTS.md agents: balladeer setup-agents

Or: Claude & ChatGPT, no install

Chat teammates skip the terminal install and pairing entirely:

• Add Balladeer as a connector in Claude or ChatGPT, using the URL from your setup page's "Get connected" step (chat tab).
• First use opens the browser: sign in, pick your workspace, allow it.
• Leave the connector's OAuth Client ID and Client Secret fields blank; signing in handles authentication, and there is nothing to paste.

What to ask once you're connected: Claude & ChatGPT.

4 · Check it works

Pairing and configuration are useful diagnostics, but neither proves your agent can reach Balladeer. Setup is complete only after a real Balladeer tool call succeeds.

• balladeer status says which server this machine is paired to.
• balladeer recent shows the decision feed (on day zero, it says the feed is empty).
• The status line appears at the bottom of Claude Code.
• Ask your agent to check Balladeer for context on your current task. A successful Balladeer response — including an honest empty-memory response on day zero — is the completion proof. When your team has recorded decisions, answers arrive with their standing.

Inviting your team

Each invitee gets an email and lands on a two-step setup of their own. Members join your workspace; they never create one.

Verified from live product as of 4 Aug 2026.