ashlrai/locus

Your coding agent can't act as the wrong account.
Locus is the identity plane for coding agents. You pin one client. After that, the CLI, the MCP tools, and the local dashboard act only as that client until a person pins again.
That matters on a machine with more than one client. Ambient gh auth, a shared Supabase token, or the last Vercel team can send an agent to the wrong account. A pin makes the other account unavailable.
Agents are first-class users. Start with the commands below. Machine indexes: llms.txt, llms-full.txt, and the agent contract.
For agents ·
30-second start ·
How it works ·
Install ·
FAQ ·
Star
Latest release: v0.6.2 (2026-11-01).
npm package READMEs use version-neutral installation commands to avoid stale pinned releases.
## For agents
One command installs both binaries:
bash
npm install -g locus-cli @ashlrai/locus-mcp
Homebrew and Cargo are in Install options. At the v0.6.2 release, the live Homebrew tap installs v0.6.1, so use npm for v0.6.2.
Read state as JSON. The first key is schema. Failures on stderr use locus.error.v1. No command prints a secret.
bash
locus whoami --json
locus status --json
locus doctor --json
locus version --json
locus topic agent-contract --json
locus doctor --json can exit 0 while verdict is WARN and ok is false. Exit 0 means the findings are setup advice, not that setup is finished.
Print the MCP entries without writing a client config:
bash
locus setup --client claude --print
locus setup --client cursor --print
locus setup --client codex --print
Those entries launch locus-mcp and serve control tools only. For the pinned binding's provider tools, paste the supervised server below. Launch the client from the shell that ran locus hook and locus enter. Restart the client after a re-pin. Agents cannot pin. Ask a person.
Claude Code (.mcp.json) and Cursor (~/.cursor/mcp.json):
json
{ "mcpServers": { "locus": { "command": "locus", "args": ["mcp", "--supervised"] } } }
Codex (~/.codex/config.toml):
toml
[mcpservers.locus]
command = "locus"
args = ["mcp", "--supervised"]
Same paste, by hand, if the client CLIs are installed:
bash
claude mcp add locus -- locus mcp --supervised
codex mcp add locus -- locus mcp --supervised
More copy-paste blocks: docs/copy-paste.md. Rules for agents in this repo: AGENTS.md.
## 30-second start
Run this in one shell. It creates sample bindings, pins personal, and checks that acme is refused. LOCUSHOME keeps the trial off your real ~/.locus.
bash
export LOCUSHOME="$(mktemp -d)" # omit this line to use ~/.locus
npm install -g locus-cli @ashlrai/locus-mcp # or brew or cargo; see Install options
locus quickstart # sample bindings, pin, whoami, doctor
eval "$(locus hook zsh)" # or bash; exports the control capability
locus enter personal # pin from this shell (it supervises the pin)
locus whoami # who your agents are acting as, right now
locus exec --expect personal --no-resolve -- echo ok # runs: personal is pinned
locus exec --expect acme -- echo ok # refused, exit 1, child never starts (pinmismatch)
The echo check uses --no-resolve because it needs no credentials. quickstart does not replace bindings you already have. --no-resolve refuses bindings whose upstreams resolve credentials. For real provider work, supply credentials outside the agent and replace the sample scopes. See the sample exec walkthrough.