Connect your coding agent (MCP server)

Set this repository up for Coderbuds, end to end: connect the MCP server,
write our two rules into this repository's agent guidance and into my own
agent instructions, commit the connection so the rest of the team gets it,
then prove it works.

WHY THIS MATTERS
Coderbuds serves facts about how this team ships — our size and scope
standards, review turnaround, what is blocking the queue, what merged but
never reached production — along with tools to act on them. Connected, you
stop guessing at this team's norms, and you can check a change before it
becomes a pull request rather than after a reviewer has already looked.

1 — CONNECT THE CODERBUDS MCP SERVER

  URL        https://coderbuds.com/mcp/insights
  Transport  http
  Auth       OAuth. I sign in to Coderbuds in the browser and click
             Authorize, once per person, per machine.
             There is no token to mint or store, so nothing secret is ever
             committed.

  Use whichever fits the agent you are:

    Claude Code   claude plugin install coderbuds --marketplace coderbuds/claude-plugin
                  The Coderbuds plugin: the server, plus skills and hooks
                  that bring the two rules below into every repository.
                  In a session that is already running, I load it with
                  /reload-plugins. No browser tab opens by itself:
                  I sign in by running /mcp, choosing
                  plugin:coderbuds:coderbuds, and selecting
                  Authenticate. Once I have, the plugin's
                  /coderbuds:set-up-repository carries out the rest of
                  setup for the plugin, so stop after this step and
                  tell me to run it instead of following steps 2 to 5.

                  The server alone, without the plugin:
                  claude mcp add --scope user --transport http coderbuds https://coderbuds.com/mcp/insights
                  Omitting --scope gives `local`, not user or project.

    Codex         codex mcp add coderbuds --url https://coderbuds.com/mcp/insights
                  then: codex mcp login coderbuds

    Cursor, or any other MCP client — write .cursor/mcp.json, or .mcp.json
    in the repository root so everyone on the team gets the same
    connection:

      {
        "mcpServers": {
          "coderbuds": {
            "type": "http",
            "url": "https://coderbuds.com/mcp/insights"
          }
        }
      }

  Once it is added, tell me exactly how to sign in for the agent you are,
  then wait until I say I have — everything below needs the connection.

2 — WRITE THE TWO MOMENTS INTO OUR AGENT GUIDANCE

  Add a `## Coderbuds` section to every agent guidance file this repository
  already has — CLAUDE.md, AGENTS.md, .cursor/rules/*, .github/copilot-instructions.md.
  If there is none, create AGENTS.md. If the section already exists, update
  it in place rather than adding a second one. Use this text:

    ## Coderbuds

    Before opening a pull request, run `git diff --numstat <base>...` and
    call the Coderbuds `assess-change-fit` tool with that output plus the
    distinct outcomes a reviewer has to approve. Describe outcomes, not
    layers: an API, a UI, a migration and their tests that deliver one
    behaviour are one outcome, not four. If the verdict is not `fits`, trim
    or split the change — or call `record-change-fit-decision` with a
    one-line reason and carry on.

    After opening the pull request, call `report-ai-usage` with its number,
    the tool that wrote it, and `review_evidence`: what you saw a person do
    before it went up — approved each edit, commented on the diff, changed
    the code, or replied after the change was finished. List only what
    happened in front of you. An empty list is the right answer for most
    agent-opened pull requests, and a flattering one is worse than none.

  Keep both attached to a moment the agent already passes through — "before
  opening a pull request" — rather than describing what the tools do. That
  difference is the whole reason one of these gets called and the other
  does not.

3 — PUT THE SAME RULES IN MY OWN AGENT INSTRUCTIONS

  This repository's guidance only reaches people working in it. So that my
  agent follows the rules in every repository my team tracks, without a
  pull request in each, add a `## Coderbuds` section to my user-level
  instructions too, updating it in place if it is already there:

    ~/.claude/CLAUDE.md     Claude Code. Create it if it is missing.
    ~/.codex/AGENTS.md      Codex. Only if ~/.codex exists.

  Cursor keeps user rules in its settings rather than in a file. If I use
  Cursor, give me the section to paste into its Rules settings.

  These files apply in every repository on this machine, including ones
  that are not ours, so the section opens with its scope. Use this text:

    ## Coderbuds

    Only in repositories whose `git remote get-url origin` is owned by an
    organisation or account Coderbuds tracks for my team — `get-team-context`
    lists the repositories. In any other repository, never call Coderbuds
    and never send it a diff — and if a call says a repository is not
    tracked, treat that one as outside this scope too.

    Before opening a pull request, run `git diff --numstat <base>...` and
    call the Coderbuds `assess-change-fit` tool with that output plus the
    distinct outcomes a reviewer has to approve. Describe outcomes, not
    layers: an API, a UI, a migration and their tests that deliver one
    behaviour are one outcome, not four. If the verdict is not `fits`, trim
    or split the change — or call `record-change-fit-decision` with a
    one-line reason and carry on.

    After opening the pull request, call `report-ai-usage` with its number,
    the tool that wrote it, and `review_evidence`: what you saw a person do
    before it went up — approved each edit, commented on the diff, changed
    the code, or replied after the change was finished. List only what
    happened in front of you. An empty list is the right answer for most
    agent-opened pull requests, and a flattering one is worse than none.

  Claude Code asks before writing anything under ~/.claude, whatever
  permission mode it is in. Expect that prompt, and say what the edit is
  for before you make it. If the write is declined or blocked, give me the
  section and the file to paste it into — not a script to run — and carry
  on with the rest.

4 — COMMIT THE CONNECTION FOR THE REST OF THE TEAM

  So that nobody else has to do step one, add a `coderbuds` server to the
  repository's own MCP config. Merge it into a file that already exists and
  leave every other server in it alone.

    .mcp.json           Claude Code. Create it if it is missing.
    .cursor/mcp.json    Only if `git ls-files .cursor` lists anything.
    .vscode/mcp.json    Only if `git ls-files .vscode` lists anything.

  A directory that exists only on this machine — gitignored, say — reaches
  nobody else, so leave it alone.

  In .mcp.json and .cursor/mcp.json:

    { "mcpServers": { "coderbuds": { "type": "http", "url": "https://coderbuds.com/mcp/insights" } } }

  In .vscode/mcp.json:

    { "servers": { "coderbuds": { "type": "http", "url": "https://coderbuds.com/mcp/insights" } } }

  Pin the URL to this repository's team by appending `?team=Team%20Name`, with
  the team `get-team-context` reports for this repository, so every call from
  here counts against that team, whichever teams a person is on.

  Claude Code treats .mcp.json and the .vscode directory as protected paths and
  asks me before writing either, whatever permission mode it is in. Expect
  that prompt: say what the edit is for before you make it, and if it is
  declined, give me the exact entry to add by hand rather than skipping it.

  The URL holds no secret. Each person signs in with their own Coderbuds
  account the first time they use it, so it is safe to commit.

  Put this and the guidance on one new branch, cut from the up-to-date
  default branch, and open one pull request, so the team reviews the setup
  once. Afterwards, switch back to the branch I was on, so my checkout is
  where I left it. In its description, tell teammates what
  happens after it merges: the next time they run Claude Code here it asks
  them to approve `coderbuds`, then `/mcp` and Authenticate signs them in.
  Codex reads no repository config, so Codex users still run
  `codex mcp add coderbuds --url https://coderbuds.com/mcp/insights` once.

5 — CHECK IT WORKS

  Call `get-team-context` and summarise what it says about how this team
  ships: size norms, review turnaround, what it expects of a change. Then
  tell me anything in it that contradicts how this repository is currently
  set up.

IF I AM ON MORE THAN ONE CODERBUDS TEAM
Coderbuds never guesses which team a call is about. Either pass the
repository as `owner/name` on each call — read it from
`git remote get-url origin` — or pin the team on the server URL as
`?team=Team%20Name`. A repository Coderbuds does not track will not resolve
to a team on its own, so pin it for those. Changing a pinned team counts as
a different server and has to be authorized again.

Paste it into Claude Code, Codex, Cursor, or whichever agent you run. The rest of this page is the same information, written for a person.