Agent Keys

Integrations

A personal key that lets an AI coding agent read and write Arbtr decisions, attributed to you.

An agent key belongs to one person on one team. Your coding agent uses it to read decisions and to propose new ones. Every write it makes is attributed to you.

Agent key (new)

arbtr_ak_...

Personal: one user, one team
Read and write
Created in Team Settings → AI Settings → Agent keys
You revoke your own; owners/admins revoke any

Legacy team key

mcp_arbtr_...

Shared by the whole team, no user identity
Read-only going forward
Its two old write tools (log_choice, create_team_standard) still work for now, but are being phased out
Controlled by the existing MCP toggle — that toggle does not control agent keys

The two keys are independent. Revoking the team key does not revoke agent keys, and turning off the MCP toggle does not stop agent keys from working.

Install the Plugin and Store the Key

1. In Claude Code, install the plugin:

/plugin marketplace add arbtr-software/claude-code-plugin
/plugin install arbtr

2. Create a personal agent key in Team Settings → AI Settings → Agent keys. Choose an agent type (claude-code, etc.) and a label, such as sam-laptop. Copy the key now — it is shown once.

3. Save the key to a file:

# This repo only
mkdir -p .arbtr && printf 'ARBTR_AGENT_KEY=%s\n' 'your_key_here' > .arbtr/env && chmod 600 .arbtr/env
echo '.arbtr/' >> .gitignore

# All repos on this machine
mkdir -p ~/.config/arbtr && printf 'ARBTR_AGENT_KEY=%s\n' 'your_key_here' >> ~/.config/arbtr/env && chmod 600 ~/.config/arbtr/env

4. Run /arbtr:setup, then restart Claude Code.

5. Verify the key:

( source ~/.config/arbtr/env; curl -s -H "Authorization: Bearer $ARBTR_AGENT_KEY" https://arbtr.ai/api/cli/status )

A working key returns JSON with your team's name.

Put the key in a file, not your shell profile

Claude Code strips credential environment variables before it runs the plugin's MCP tools. A key exported only in ~/.zshrc or ~/.bashrc never reaches Arbtr's MCP tools — use one of the ARBTR_AGENT_KEY files above. (A legacy ARBTR_API_KEY exported in the shell still works, but only for reads.)

Where the plugin looks for a key

In this order — the first one found wins for that repo:

<repo root>/.arbtr/env — replaces the other two sources for that repo
Environment variables already in your shell
~/.config/arbtr/env

Creating and Revoking Keys

Anyone can create their own agent key from the Agent keys section of Team Settings → AI Settings. You see and can revoke your own keys. Team owners and admins see and can revoke any key on the team — for example, when someone leaves.

Removing someone from the team makes their keys stop working immediately, whether or not anyone revoked them: every request checks active membership.

What an Agent Can Write

v0 keeps the write surface small: two operations, so the review and the safety checks stay easy to reason about.

propose_decision

Proposes a new decision. It lands live, labeled "pending human acceptance".

title — 8 to 120 characters, a specific noun phrase (not "misc updates")
context — at least 200 characters explaining why: alternatives considered, trade-offs. A context that just repeats the title is rejected.
evidence — at least one entry, required. A durable artifact (PR number, commit SHA, file path, URL, or ticket id) grades the proposal durable. Anything else — a person's name alone, for example — grades it tribal (still saved, but marked as a hypothesis, not an instruction).
tags, repo, source — optional.
idempotency_key — optional; retrying with the same key returns the original decision instead of a duplicate.
force — optional; overrides a near-duplicate refusal, and is recorded in the audit log.

Before it saves anything, Arbtr checks for a near-duplicate decision (semantic similarity, not just matching text). If one is found, the tool refuses and lists it — comment on the existing one with add_decision_comment instead of forcing a duplicate through.

add_decision_comment

Adds an attributed comment to an existing decision.

decision — the decision's slug or id
body — the comment text
type — optional: question | context | idea | risk | data-request | clarification (default context)

Not yet supported for agents: editing, deleting, arguments, positions, relationships, and status changes. Those are planned for a later release.

The same operation over a shell hook

POST /api/cli/propose is a REST version of propose_decision, for scripts that cannot speak MCP. Same fields, same rules. It replies:

201 created, or 200 on an idempotent replay
422 the proposal failed a check — the response lists what to fix
409 a near-duplicate exists (or a similar proposal was already rejected — the reason is included)
403 no permission, or agent writes are off for the team

Turning Writes On

A team setting, agentWritesEnabled, gates every agent write. Reads always work with a valid agent key. There is no toggle for this in the UI yet — during the pilot, ask your Arbtr admin to turn it on for your team.

Without agentWritesEnabled

propose_decision and add_decision_comment fail with a permission error. Reads (search, get details, project context) are unaffected.

Proposals and the Acceptance Queue

A proposed decision is visible to the whole team right away, but it is labeled "unratified — hypothesis, not constraint" everywhere an agent reads it, until a person accepts it.

Any team member with permission to create decisions can review proposals in the queue at /<team>/decisions?filter=proposed. They can:

Accept — the decision becomes a normal, live decision
Edit, then accept — fix the title, context, or tags in the same step
Reject, with a reason — the decision is archived, and the reason is kept

A pending decision cannot be concluded, edited outside the queue, archived, deleted, or published to Git until it is accepted.

Rejecting a proposal does not erase it from Arbtr's memory: if an agent proposes something very similar again, Arbtr answers with the earlier rejection reason instead of creating a second pending proposal for the same thing.

Not the same as ratification

Arbtr already has a separate CTO sign-off step for concluding a decision, on teams that require it. The acceptance queue is different: it is peer review for a proposal entering the record at all, the way you would review a teammate's pull request. An accepted proposal still goes through normal ratification later if your team requires it.

Attribution

Every agent write shows who made it, and with which agent.

Decision cards, the detail page, and the audit timeline all show a badge like proposed by claude-code · sam-laptop · Sam. The full history — including who accepted or rejected a proposal, and why — is in the decision's audit log.

Recommended Agent Instructions

Paste this into your repo's CLAUDE.md or AGENTS.md so your agent uses Arbtr the way it is meant to be used.

## Arbtr

- Before an architectural change, check Arbtr for an existing decision
  (search_decisions, get_project_context).
- When you make or find a significant architectural choice, call
  propose_decision with a real context (the why, and the alternatives
  you considered) and at least one durable evidence item: a PR, a
  commit SHA, a file path, a URL, or a ticket.
- If propose_decision returns a near-duplicate, call
  add_decision_comment on it instead of forcing a new one.
- Treat pending/unratified decisions as hypotheses, not constraints.

Troubleshooting

Writes fail with a permission error

Agent writes need agentWritesEnabled turned on for your team, in addition to a valid agent key. Ask an Arbtr admin.

The plugin can't find my key

Env vars set only in ~/.zshrc or ~/.bashrc do not reach Claude Code's MCP tools. Put the key in .arbtr/env or ~/.config/arbtr/env instead, and run chmod 600 on the file.

propose_decision keeps refusing as a duplicate

Arbtr found an existing decision that is very similar. Comment on it with add_decision_comment, or retry with force: true and explain why this one is genuinely different.

MCP Server

Back to

All Integrations

Command Palette