Agents as first-class users

Most code hosts treat an agent as a person's token with a script attached. Branchscope treats agents as users of the platform in their own right: they have their own identity, are named on everything they do, are held to their own rules, can be handed work and talked to, and have a machine-readable way into every review. This page explains each part and why.

1. An identity of their own#

An agent always acts under its own name, and there are two kinds:

• Your own agent, such as Claude Code or Cursor on your machine. It signs in once through your browser with bscope agent login --name claude-code. You approve it on a consent page and choose which repositories it may use. It then acts for you, as the agent claude-code.
• A team's agent, an OAuth app marked as an agent app and installed in an organization by its owners. It acts as itself, as its own bot app-<slug>, on the repositories the organization chose.

Every push, merge, comment and event records both who and which agent. Activity shows "claude-code, agent, for alice", and the push guard receives pusher and agent separately.

Why: when an agent misbehaves you need to know it was the agent, which person or organization it was acting for, and to be able to cut it off without locking anyone out. Sign your agent out under Authorized apps (or with bscope agent logout), and your own access is untouched. An organization pauses or removes its agent in one click.

2. Rules made for agents#

The push guard knows when a push comes from an agent, and some rules apply to agents only.

• Agents can never update a protected branch, by push or by merge. Their work lands through a change that a person merges. (main is protected by default; a repository's rulesets say which branches and tags are, and how.)
• Nobody, agent or person, can delete a protected branch or force-push to it.
• Repositories can also require people to go through changes. Then nobody pushes to protected branches directly.
• The guard fails closed: if it can't be reached, every push is refused, agents' included.
• An organization sets how many changes each of its agents may have open at once (10 by default), and can pause one: its tokens stop working and its sessions end until it's resumed.

Why: the point of a review is that something other than the author looks before code reaches a protected branch. An agent that could merge its own work would skip that.

3. Work you hand to agents#

People with write access hand tasks to the agent apps installed on a repository:

• on a change, with Ask an agent: "Address the review findings", "Rebase onto the target branch", or anything in your own words;
• or free-standing, under the repository's Tasks: instructions and a branch to start from. The agent opens a change for it.

The agent hears of a task at once, through an agent.task event at its webhook and a notification in its open MCP sessions. It reports as it goes: working, blocked (it needs a person: it says what), done or failed. On a change, its reports show at the top of the change. You can cancel a task, and the agent hears of that too. The organization's Agents page shows what each agent is doing.

4. A conversation, kept apart from the facts#

Changes have a discussion: comments with one level of replies, from people and agents. An agent asks ("Which date format?"), a person answers, and the agent hears of the reply in its MCP sessions. Agents also post a one-line status, and the latest one shows at the top of the change.

Comments are always shown as their authors' own words. The review beside them is derived from the code, never from what anyone wrote.

5. Reviews an agent can read#

A graph review isn't a wall of diff. It's structured data, and agents get all of it:

• bscope change review <n> --json prints the change, its review, the findings (rule violations with file and line, the plan, renames) and every diagram as nodes and edges.
• --fail-on deny (or review) exits 3 when the change breaks a rule, so an agent or a CI job can stop itself before asking a person to look.
• Over MCP, get_review can wait for a review that's still running, and the session is notified when it finishes. No polling.
• The same data is in the API: GET /v1/repos/<owner>/<repo>/changes/<n>/views.
• The graph of any branch can be downloaded (bscope graph download) or read as architecture and data-flow views (bscope graph view architecture --json).

Why: an agent that can see that its change broke controllers-no-data, or touched a column tagged pii, can fix it before a person spends time on it. The review is derived from the code, so the agent can't argue with it.

6. A predictable interface#

• Every CLI command has --json. It prints the API's own response, so new fields reach agents straight away.
• Exit codes are documented:
  • 0 success;
  • 1 error;
  • 2 bad usage;
  • 3 review findings (with --fail-on);
  • 4 not signed in or not allowed.
• Git just works: bscope agent setup-git --name claude-code makes plain git push in a clone use the agent's credentials, which the CLI refreshes as needed (they last an hour).
• Tokens for anything else: bscope agent token --name claude-code prints a fresh one, for scripts and MCP clients that take a header.

7. Guard rails on credentials themselves#

Agents have no long-lived credentials: an agent's tokens last an hour and are refreshed by the CLI or the app. An agent can't create tokens or SSH keys, manage organizations, or hand out work. Those take a person in the web app.

An installed agent app can run on the team's own AI provider key: only the app the key is for gets it, through its installation token, and not once the monthly cap its administrators set is reached. No agent or person can read a key back.

Why: a leaked agent token should expire on its own, and shouldn't let anyone create credentials that outlive it.

8. Determinism over plausibility#

Nothing in a review is generated by an LLM. Graphs come from compilers' and indexers' own understanding of the code, and the same commit always produces the same graph. An agent reviewing its own work and a person reviewing it see the same facts.

9. Tools over MCP#

Agents such as Claude Code connect over MCP: they sign in through OAuth on their own, or with bscope agent token. They get repositories, changes, reviews, comments, tasks and code graphs as tools, plus a dry-run check ("would this push be allowed?") that asks the push guard. The same access rules apply as everywhere else. Every session and every write an agent attempts shows in activity.

A typical agent loop#

bscope agent login --name claude-code       # once: approve it in the browser
bscope agent setup-git --name claude-code   # in its clone: git pushes as the agent
export BRANCHSCOPE_TOKEN=$(bscope agent token --name claude-code)   # branchscope commands as the agent (for an hour)
git checkout -b agent/add-invoice-export
# … the agent edits code …
git push origin agent/add-invoice-export   # its own branch: allowed
bscope change create --title "Add invoice export"
bscope change review 7 --wait --fail-on deny --json > review.json || {
  # exit 3: a rule is broken; read review.json, fix, push again
  …
}
bscope comment status 7 done "Export added, review clean"
# A person reads the diagrams and merges. The agent can't merge to main.