Give an AI coding agent its own account, with guardrails

On Diffinery, an AI coding agent gets an account of its own, separate from yours: you create it under Settings → Agents, give it a token (or let Claude Code or Codex sign in as it through the browser), and its commits, pull requests and comments show as the agent's, on your behalf. The server holds it to guardrails whatever tool it uses: it can't push to or merge into the default branch or protected branches, its pull requests need a person's approval, its own approvals and check results never count, and runs of the code it writes get none of your repository or organization secrets. Repository admins relax these rules, per branch or per repository, when you're ready, for example to let its pull requests merge by themselves once CI passes and a person approves.

#Steps

1. Create the agent. Go to Settings → Agents, enter an Agent username (for example review-bot), choose the Owner (you, or an organization where you're an owner or admin) and keep the Maximum role at Write. Click Create agent. Only people can create agents, and an organization's agent can reach only that organization's repositories.
2. Create a token for it, unless the agent will sign in through the browser (step 4). In the agent's row, open Create a token for review-bot, keep the Scope at Write, choose the Days (1 to 366), and click Create token. Copy it: it's shown once. Give it to the agent as an environment variable such as DIFFINERY_TOKEN, never in a file you commit. See Tokens for agents.
3. Protect the default branch. Under the repository's Settings → Branch protection, add a rule for main with Require a pull request before merging, at least one Required approvals, and your CI checks under Required status checks. Agents can't push to the default branch either way; the rule makes sure every change is reviewed and tested. See Branch protection.
4. Connect the agent (see Connect Claude Code, Codex or another MCP client).
5. Tell it how to work, for example in your agent instructions file: work on a new branch, open a pull request with an intent that states the goal, wait for checks with diffinery pr checks --watch, and fix failures before asking for review.
6. Review and merge its pull requests, by hand or with merge on green (see Review and merge agent pull requests).

#What the server enforces

These rules hold for Git pushes, the REST API, MCP tools and sandboxes alike, whatever the agent's role:

The full table, with how to relax each rule, is in Guardrails.

#Connect Claude Code, Codex or another MCP client

Every app connects to the same MCP server, https://diffinery.com/mcp. Apps with browser sign-in need no token: on Diffinery's consent page, choose to act as your agent, and Write access.

• Claude Code: install the CLI and run diffinery setup, which adds the Diffinery plugins. Then run /mcp, select plugin:diffinery:diffinery, choose Authenticate, and pick the agent on the consent page. See Claude Code.

• Codex: run diffinery setup, add the Diffinery plugin, then run codex mcp login diffinery and pick the agent on the consent page. See Codex.

• Cursor, VS Code and other MCP apps: add https://diffinery.com/mcp as a remote HTTP server and sign in. See Other apps.

• Headless (CI, scripts, scheduled jobs): send the agent's token instead. For Claude Code:

  claude mcp add --scope user --transport http diffinery https://diffinery.com/mcp \
    --header 'Authorization: Bearer ${DIFFINERY_TOKEN}'

  diffinery mcp-config prints a snippet for other clients. See Headless use.

• Git and the CLI: with DIFFINERY_TOKEN set, diffinery auth setup-git lets Git push with it, and diffinery auth setup-gh makes gh pr create and gh pr checks work against Diffinery. See GitHub CLI.

Ask the agent "Who am I on Diffinery?" to check: the whoami tool answers with the agent's login.

Cloud environments. For a Claude Code cloud environment, or any other agent sandbox, open the repository's Settings → Agent setup and choose Generate agent token. It makes an agent that can reach only that repository and gives you the allowed domain, a one-line setup script and the environment variables to paste. A Check turns green once a session has set itself up. See Cloud agent environments.

#Review and merge agent pull requests

• Find what needs you. Today, the first page after signing in, lists Agent PR needs a person's approval for agent pull requests no person has approved at their latest commit.
• Read the intent first. Every pull request can carry an intent, one or two sentences on what the change is meant to do, shown at the top so you can check the diff against it. See Pull requests.
• Approve, then merge. You (or anyone with write access other than the agent) approve. The agent's owner can approve, because the owner is a different account from the agent.
• Let it merge on green. An admin opens the repository's Settings → Merge on green, ticks the checks that must pass and the agents, and chooses whether agents' pull requests merge Once the checks pass and a person approved or As soon as the checks pass. Each agent pull request then merges by itself when its conditions are met. See Merge on green automatically.
• Or allow auto-merge per branch. Allow agents to land pull requests through auto-merge on a branch's rule (with at least one required check) lets the agent turn on auto-merge for its own pull requests (enable_auto_merge over MCP, or diffinery pr merge --auto). Diffinery merges once every rule is met; if the agent pushes again, a person approves again. See Agents landing changes.
• Workflow changes always need a person. A pull request that adds, changes or deletes a workflow file never lands through an agent's auto-merge: CI can't vouch for a change to itself.
• Plan for deploys after agent merges. A merge that auto-merge makes for an agent is the agent's push, so later runs on that branch are runs of agent code and get no repository or organization secrets. Keep deploy credentials in an environment limited to protected branches, or have an admin turn on Give runs of agent code the repository's and organization's secrets. See Which runs receive secrets.

To have one of your agents review pull requests for bugs before you do, turn on Agent review. To give an agent a goal and get a pull request back, see Agent tasks.

#Audit what agents did

• On every item: agents have an agent badge and on behalf of <owner> next to their name on pull requests, reviews, comments and workflow runs, and the API returns "type": "Bot" for them.
• In Git: commits Diffinery writes for an agent carry the diffinery-agent ... on-behalf-of ... header, covered by the commit's SHA. See it with git cat-file -p <sha>.
• Its tokens: Settings → Agents lists each agent's tokens with their scope and last use, and a revoke link. Diffinery sends a security email when an agent or an agent token is created.
• The audit log: site administrators see every audited action under Settings → Audit log, with the agent as the actor and its owner alongside (review-bot for diffy). See Audit log.
• Cut it off: revoke one token to stop one running copy, or Disable the agent under Settings → Agents to revoke all its tokens at once.

#Frequently asked questions

#Can an AI agent push to main on Diffinery?

Not by default. Agents can't push to the default branch or to any protected branch; they push a branch and open a pull request. A repository admin can allow it on a branch's protection rule with Allow agents to push directly.

#Can an agent approve or merge its own pull request?

An agent's approval never counts toward required approvals, and agents can't merge into the default branch or protected branches. A person approves its pull request. A repository admin can let agents land approved pull requests through auto-merge, so CI and a person decide rather than the agent, or waive the approval so green required checks are enough.

#Can an agent read my repository secrets?

Agents can't create, change or delete secrets, and a workflow run of code an agent wrote gets no repository or organization secrets unless a repository admin turns that on. Environment secrets reach such a run only from environments limited to protected branches, and never on pull request refs. Agents with write access can read Actions variables, which aren't secret.

#Which AI coding agents work with Diffinery?

Any agent that uses Git, the GitHub CLI, the REST API or MCP. There are guides for Claude, Claude Code, Codex, Cursor and VS Code (Other apps).

#How do I take away an agent's access?

Revoke its token under Settings → Agents, or click Disable next to the agent to revoke all its tokens at once. An app connected through the browser is disconnected under Settings → Access tokens → Connected apps.