Belay Docs

Install

You need an Apple Silicon Mac and at least one of Claude Code or Codex with some session history on disk.

curl -fsSL https://getbelay.vercel.app/install | bash

This downloads the alpha release, checks its checksum, installs belay for your user account, and runs belay quickstart. Quickstart sets up monitor-only hooks and the Belay skill for the agents it finds, scans your existing sessions, and opens your report in the browser.

Codex is a little different. Belay won't add itself to Codex's MCP list unless you ask, because Codex can end up with duplicate entries. If you want it there, install with the extra flag:

curl -fsSL https://getbelay.vercel.app/install | \
  bash -s -- --allow-codex-mcp-add

Your first five minutes

Run the install command and let quickstart scan your history. The first scan is the slow one.
Open the report. It lists the mistakes that repeat, most expensive first.
Pick the top one and read the evidence. It's the actual session content, not a summary.
Click Copy for Claude Code or Copy for Codex.
Paste the command into that agent. It reads the evidence and proposes a fix. Nothing changes until you say yes.

You're done when you have one specific repeated mistake, the evidence for it, a proposed rule, and a command to check it on the next run.

Commands

Command	What it does
`belay quickstart`	Full setup: hooks, skills, MCP where allowed, history scan, analysis, and open the report.
`belay local`	Scan and open the report without touching hooks or MCP config.
`belay doctor`	Check that storage, hooks, config, and the underlying engine are healthy.
`belay agents`	List the agents Belay found on this machine.
`belay scan`	Rescan past Claude Code and Codex sessions.
`belay analyze --agent auto`	Use your installed agent to refine what the scan found.
`belay hooks status`	Show which monitor hooks are installed.
`belay hooks install`	Install the monitor hooks.
`belay hooks uninstall`	Remove Belay's hooks. Nothing else is touched.
`belay mcp-config status`	Show whether Belay is registered as an MCP server, without changing anything.
`belay mcp-config install --allow-codex-mcp-add`	Register Belay with Codex, only if it isn't already there.
`belay mcp-config uninstall`	Remove Belay's MCP registration. Other servers are left alone.
`belay version`	Print the installed version.

Claude Code and Codex

Quickstart installs a small Belay skill into each agent it finds. Start it like this:

Claude Code

/belay start

To work on one specific issue from the report, use the command copied from that issue's card. It includes the issue id.

Codex

$belay start

If you change Belay's MCP registration, restart Codex so it picks up the new server.

Belay gives the agent the evidence over MCP as data, not as instructions. The agent still has to ask you before it acts on anything Belay proposes.

Options

Don't open the browser

belay quickstart --no-open
belay local --no-open

Skip the agent-assisted analysis

belay quickstart --no-analyze

Choose which agent does the analysis

belay analyze --agent claude
belay analyze --agent codex

Keep Belay's data somewhere else

BELAY_HOME=/absolute/path/to/belay-home belay local

Belay also respects CLAUDE_CONFIG_DIR and CODEX_HOME when looking for session history. Useful on managed work laptops and for test setups.

Never touch MCP config

belay quickstart --no-mcp

Privacy and cost

Belay stores session history in an encrypted local database, does not upload it to Doplex Labs, and requires no Belay account.
Session content is scrubbed of secrets, then encrypted on your Mac with a key kept in the macOS Keychain.
A few index fields stay unencrypted in the local database so the report can be built: timestamps, roles, token counts, and which project a session belongs to.
If you run belay analyze, selected excerpts go through your configured Claude Code or Codex provider under the account and policy you already use. The local Belay database is not sent.
Dollar figures in the report are estimates from public list prices, not invoices. If Belay doesn't know a model's price it says so instead of guessing.
Token counts include input, output, and cache reads and writes, without double counting.
Time on an issue is active time. Gaps longer than 30 minutes aren't counted.

Read the complete trust and privacy details →

Troubleshooting

`/belay` or `$belay` isn't recognized

Run belay quickstart again, check belay mcp-config status, then restart the agent.

The report is empty or missing sessions

belay agents
belay scan
belay doctor

Belay can only read session files that still exist in Claude Code's or Codex's folders. If they've been cleaned up, those sessions are gone.

Codex was found but Belay isn't in its MCP list

That's on purpose. Run belay mcp-config status to confirm nothing named belay is there, then install with --allow-codex-mcp-add.

Work laptop with custom paths or someone else's config

Set CLAUDE_CONFIG_DIR or CODEX_HOME, run belay doctor, and leave anything it reports as not Belay's alone. Belay never overwrites config it doesn't own.

macOS blocks the binary

The alpha isn't signed yet, so this can happen once. Open System Settings, then Privacy & Security, and approve the Belay binary. Approve just that one. Don't turn Gatekeeper off.

What the alpha doesn't do

Run anywhere except Apple Silicon Macs.
Support Cursor. Claude Code and Codex only for now.
Prove a fix worked. Belay proposes fixes and shows evidence. Counting whether a mistake comes back is next.
Change your files, run commands on its own, or fix anything without you approving it first.
Anything team-wide. Belay for Teams is separate and not out yet.

Uninstall

curl -fsSL https://getbelay.vercel.app/install | \
  bash -s -- --uninstall

This removes the program, Belay's hooks, and Belay's MCP registration. Your encrypted history and its Keychain key are kept, so an accidental uninstall doesn't lose your evidence.