Belay docs.

Install Belay, see what keeps repeating, inspect the evidence, and carry approved lessons into future Claude Code, Codex, or Cursor sessions.

Alpha. macOS (Apple Silicon) and Windows 10 (1809+) or Windows 11 on x64. Works with Claude Code, Codex, and Cursor. Both packages are checksum-verified but unsigned: macOS may ask you to approve the binary once, and Windows SmartScreen may warn once.

Install

You need an Apple Silicon Mac, or Windows 10 (1809 or later) or Windows 11 on x64, and at least one of Claude Code, Codex, or Cursor with some session history on disk. Windows on arm64 is not published yet.

Cursor support is new in this alpha. Cursor Agent cannot run Belay's analysis, so debriefs and lesson proposals require Claude Code or Codex installed on the same machine. A Cursor-only machine gets sessions, evidence, and recurring-issue detection, but no debriefs and no semantic lessons. See Using Belay with Cursor.

On macOS, in Terminal (Windows is just below):

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 — Claude Code, Codex, and Cursor — 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

Install on Windows

Open Windows PowerShell 5.1 or PowerShell 7 and run:

irm https://getbelay.vercel.app/install.ps1 | iex

This downloads the alpha release, checks its checksum, installs Belay under %LOCALAPPDATA%\Belay for your user account, puts a belay shim in %LOCALAPPDATA%\Belay\bin and adds that folder to your user PATH, then runs belay quickstart. Open a new terminal afterwards so the new PATH is picked up.

Nothing is installed for other users and nothing needs an administrator. Codex MCP registration is opt-in here too; pass the flag through and quickstart still runs:

& ([scriptblock]::Create((irm https://getbelay.vercel.app/install.ps1))) `
  -Quickstart -AllowCodexMcpAdd

Your first five minutes

  1. Run the install command and let quickstart scan your history. The first scan is the slow one.
  2. Open the report. Your last few sessions are there, each with a debrief written by your own Claude Code or Codex. The first ones are written in the background; each takes one to three minutes.
  3. Open Habits and read one debrief. It shows where your prompting, scoping, or checks cost time or money, what an expert would have done at that moment, and the exact message to send instead. Copy the Next time opener for your next session in that project.
  4. For the mistakes that repeat, start your agent with /belay start in Claude Code or $belay start in Codex. It reads Belay's evidence over MCP and proposes a fix. Nothing changes until you say yes.

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

Commands

CommandWhat it does
belay quickstartFull setup: hooks, skills, MCP where allowed, history scan, analysis, and open the report.
belay localScan and open the report without touching hooks or MCP config.
belay doctorCheck that storage, hooks, config, and the underlying engine are healthy.
belay agentsList the agents Belay found on this machine.
belay scanRescan past Claude Code, Codex, and Cursor sessions.
belay analyze --agent autoUse your installed agent to refine what the scan found and to write debriefs for recent sessions. Each debrief takes one to three minutes and runs under that agent's account.
belay hooks statusShow which monitor hooks are installed.
belay hooks installInstall the monitor hooks.
belay hooks uninstallRemove Belay's hooks. Nothing else is touched.
belay mcp-config statusShow whether Belay is registered as an MCP server, without changing anything.
belay mcp-config install --allow-codex-mcp-addRegister Belay with Codex, only if it isn't already there.
belay mcp-config uninstallRemove Belay's MCP registration. Other servers are left alone.
belay versionPrint the installed version.

Claude Code, Codex, and Cursor

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.

Cursor

/belay start

Type it in Cursor's Agent chat. New in this alpha — see Using Belay with Cursor for what it can and cannot do.

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.

Using Belay with Cursor

Cursor support is new in this alpha and has not had a clean-machine validation run yet. Treat it as newer than the Claude Code and Codex paths.

On a machine with Cursor, belay quickstart does four things:

  • Reads Cursor's local agent transcripts from ~/.cursor/projects/*/agent-transcripts.
  • Installs monitor-only hooks into ~/.cursor/hooks.json.
  • Installs the /belay skill into ~/.cursor/skills/belay.
  • Registers Belay's local MCP server in ~/.cursor/mcp.json, leaving any other servers in that file alone.

To use it, open Cursor's Agent chat and type:

/belay start

Belay answers with a Mission Pack: the relevant evidence, where it applies, and a check to run. Nothing changes until you say yes.

Cursor limitation. Cursor Agent cannot run Belay's analysis, so debriefs and lesson proposals require Claude Code or Codex installed on the same machine. A Cursor-only machine gets sessions, evidence, and recurring-issue detection, but no debriefs and no semantic lessons.

Registering the MCP server by hand. If you installed with --no-mcp, or you want to add the server yourself, put this in ~/.cursor/mcp.json and restart Cursor:

{"mcpServers": {"belay": {"command": "/absolute/path/to/belay", "args": ["mcp"]}}}

Use the absolute path that which belay prints. If ~/.cursor/mcp.json already exists, add the belay entry to the existing mcpServers object rather than replacing the file.

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. Cursor history is read from ~/.cursor/projects/*/agent-transcripts.

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 own machine with a key kept in the macOS Keychain, or, on Windows, protected for your user account by the Windows Data Protection API (DPAPI).
  • 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.
  • A debrief is written from a scrubbed excerpt of one finished session, with secrets removed and file paths reduced to file names. It is stored encrypted, shown only to you, and never given to your agent.
  • The time span a debrief flags is wall-clock time between transcript entries. It can include breaks, so read it as context rather than as time you would have saved.
  • 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. In Cursor, check that ~/.cursor/mcp.json has a belay entry and that the skill is present in ~/.cursor/skills/belay.

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, Codex's, or Cursor'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.

Windows SmartScreen blocks the binary

The Windows alpha isn't signed yet either, so this can happen once. Confirm the installer reported a matching checksum, then choose More info and Run anyway for that binary. Allow just that one. Don't turn SmartScreen off.

What the alpha doesn't do

  • Run on Intel Macs, on Linux, or on Windows arm64. Apple Silicon Macs and Windows 10/11 on x64 only.
  • Write debriefs or propose lessons on a Cursor-only machine. Cursor Agent cannot run Belay's analysis, so debriefs and lesson proposals require Claude Code or Codex installed on the same machine. A Cursor-only machine gets sessions, evidence, and recurring-issue detection, but no debriefs and no semantic lessons.
  • Prove a fix worked. Belay proposes fixes and shows evidence. Counting whether a mistake comes back is next.
  • Prove a debrief changed how you work. Belay shows what a session cost and what to say next time. It does not yet measure whether the next session went better.
  • 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

On macOS:

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

On Windows, download the script and run it with -Uninstall:

irm https://getbelay.vercel.app/install.ps1 -OutFile install.ps1
.\install.ps1 -Uninstall

Or in one line:

& ([scriptblock]::Create((irm https://getbelay.vercel.app/install.ps1))) -Uninstall

This removes the program, Belay's hooks, and Belay's MCP registration. Your encrypted history and its key are kept, in the macOS Keychain or under %USERPROFILE%\.belay with its DPAPI-protected key on Windows, so an accidental uninstall doesn't lose your evidence.