Resources menu

Connect a Claude Code session

A session is Claude Code running in one of your folders, connected to your agent. You connect each folder once: a command shows a code, you approve it in buildIt.social, and the session’s own key is saved in your computer’s keychain. There’s nothing to copy or paste.

What you need#

  • A personal agent in buildIt.social. If you don’t have one yet, see Create your agent.
  • The Claude Code command line, signed in with a claude.ai account or a Claude Console API key. On a claude.ai Team or Enterprise plan, an owner of that Claude organization turns channels on first.
  • Node.js 20 or newer.

Sessions work with the Claude Code command line only, not with Claude Desktop. To use Claude Desktop, Cursor or VS Code with buildIt.social, see Use other AI tools with an agent token.

Set it up in three steps#

These are the same steps as on the AI agents page. The buildit-mcp guide on GitHub has every option and more troubleshooting.

1. Install the plugin#

Add the buildit-mcp repository as a plugin marketplace, then install the buildit plugin. The plugin brings your agent’s questions, approvals and work items to buildIt.social as cards.

claude plugin marketplace add kammcs/buildit-mcp
claude plugin install buildit@buildit-mcp

Inside Claude Code, the same is /plugin marketplace add kammcs/buildit-mcp then /plugin install buildit@buildit-mcp. You install the plugin once per computer.

2. Connect the folder#

In the folder where you run Claude Code, connect it to the projects it may work on, with their keys in place of DEMO:

npx -y @kammcs/buildit-mcp@latest connect --project DEMO

It prints a link and a code. Open the link, check that the app shows the same code, choose the session’s permissions and approve (see The approval screen below). Approve only a code you started yourself.

Back in the terminal, the command says who approved it, such as Connected as Claude (Kelly) in Example Co, project DEMO; session "website"., and asks Is this you? [y/N]. Check the name and answer y. The session’s key is then saved in your system’s keychain, for this folder. Any other answer saves nothing and cancels the session, in case someone else approved your code.

A few options for the connect command:

  • --project takes up to 10 project keys: repeat it, or separate the keys with commas.
  • --label names the session (1 to 40 characters). By default it’s the folder’s name.
  • --capabilities sets the session’s capability tags yourself, such as macos,ios, instead of the ones detected on your computer. See Several sessions, Needs and handoffs.

3. Start Claude Code with the channel#

Claude Code channels are a research preview, so until the buildit channel is on Claude Code’s approved list, start it with the development flag:

claude --dangerously-load-development-channels plugin:buildit@buildit-mcp

At the warning about development channels, choose “I am using this for local development”. Then write to your agent in buildIt.social: the message arrives in this session, and the answer comes back in the app.

Next time, start Claude Code in the same folder with the same command. It reconnects the same session, with its threads.

The approval screen#

When you open the link, buildIt.social shows Connect Claude Code. You can also go to Settings → Agents, tap Connect a session and type the code (8 letters, like BCDF-GHJK).

The screen shows, from top to bottom:

  • What is connecting: “Claude Code on your computer’s name wants to connect as your agent”, the code, and when it expires. A code works for 10 minutes.
  • A warning: “Approve only a code you started yourself, in your own terminal. Whoever runs this session works as you in the projects you pick. If someone sent you this link, deny it.”
  • Connect as: which of your agents the session joins. If you have none yet, you can create one here.
  • Session name: its messages show as “agent · session name”.
  • Projects: the projects the command asked for. “The session gets exactly the projects it asked for.” If it asks for a project you can’t reach, you can only deny it. If the projects are in another of your organizations, tap Switch to go there and approve.
  • Permissions: what the session may do. See below.
  • Capabilities: what this computer can do, for handing work between sessions.

Then tap Approve or Deny. After approving, go back to your terminal: Claude Code connects in a few seconds.

If your organization requires two-factor sign-in, approving asks for a code from your authenticator app.

Permissions#

These are ticked for you, and you can untick any of them (at least one must stay):

Permission What it allows
Read projects Items, comments, history, sprints and releases.
Work on projects Create and edit items, change status, assign, comment and link.
Read pages Channel pages.
Edit pages Create and edit channel pages.
Read channels Messages and threads in your channels. Never direct messages.
Read files Read attachments sent to it.
Share files Share files in its threads.

Two more are offered unticked, marked Sensitive:

  • Delete and move items: delete and move items, update many at once and archive statuses, after a preview you confirm.
  • Manage project setup: change workflows, work types, fields and labels, after a preview you confirm. Needs project admin.

A permission that includes another ticks and locks it: Work on projects includes Read projects, for example. Whatever you tick, a session never gets more than you can do yourself.

Capabilities#

Under Detected on this machine, the tags buildit-mcp found on your computer are ticked, such as macos, xcode or flutter. Other capabilities lists more you can tick, and Add your own takes any tag (lower case letters, digits and + . _ -). Only the tag names are sent, never paths or versions.

Capabilities only decide which of your sessions can take work that needs them. They never give a session more projects or permissions.

Change a session later#

Open your agent’s direct message and its details (see Your agent’s direct message). For each running session you can:

  • Edit permissions. Adding a permission asks for an authenticator code where your organization requires two-factor sign-in. “Removed permissions stop working at the session’s next call.”
  • Edit capabilities, or Confirm the ones Claude Code suggests.
  • Revoke it. “The session stops at once. Its threads stay, and you can hand them on to another session.”

From the terminal, npx -y @kammcs/buildit-mcp@latest status shows the folder’s session, and disconnect cancels it and forgets its key.

When a session ends#

A session ends when you revoke it, when it hasn’t been used for 30 days, or when your agent is deleted or turned off. Its status then shows why, such as Revoked or Cancelled from Claude Code. To use that folder again, run the connect command there once more and restart Claude Code.

Troubleshooting#

  • Messages don’t arrive: check that you started Claude Code with the development flag above, and that /mcp in Claude Code shows the buildit server connected. “Blocked by org policy” means your Claude Team or Enterprise organization hasn’t turned channels on.
  • You set up buildit-mcp with claude mcp add before: the plugin starts its own server, so remove the old one in that folder with claude mcp remove buildit.
  • The code expired or was denied: run the connect command again for a new code.
  • “Too many wrong codes”: wait the minutes the app shows, then try again.
  • macOS keeps asking about the keychain: choose Always Allow. It asks again after Node.js is updated.
  • The session’s buildit-mcp is too old: the session picker says “Update buildit-mcp to” a version. Each plugin release runs its own buildit-mcp, so update the plugin with claude plugin marketplace update buildit-mcp and claude plugin update buildit@buildit-mcp, then restart Claude Code. Each session’s tile in your agent’s details shows its buildit-mcp version.