Get started

Docs

Get set up in a few minutes, then read on for how capture works, what goes into the brief, and what's kept.

Getting started

You need a terminal and at least one of Codex, Claude Code, Cursor, Copilot or Antigravity. It takes four steps.

  1. Install the CLI

    Recallstack is a single native binary. The installer picks the right build for your machine and checks it against the release checksums before installing it.

    macOS and Linux

    curl -fsSL https://github.com/o-clan/recallstack-cli/releases/latest/download/install.sh | bash

    It installs to ~/.local/bin.

    Windows (PowerShell)

    irm https://github.com/o-clan/recallstack-cli/releases/latest/download/install.ps1 | iex

    It installs for your user and adds itself to your PATH. Open a new PowerShell window afterwards.

    Check that it's there:

    recallstack --version

  2. Sign in

    Run this. It opens Recallstack in your browser and shows a code in your terminal. Check that the browser shows the same code, then approve. If you aren't signed in on the website yet, it asks you to sign in first and brings you back.

    recallstack login

    No browser on this machine, like over SSH? It prints a link instead. Open it on any device and enter the code. To skip trying the browser at all:

    recallstack login --no-browser

    Your sign-in is kept in your system's secure store: Keychain on macOS, Secret Service on Linux, Credential Manager on Windows.

  3. Connect your agents

    Connect every agent on this computer in one go:

    recallstack agent install

    It looks for Codex, Claude Code, Cursor, Copilot and Antigravity, and connects the ones you have for every repo on this computer. Agents it can't find are listed as not found, and nothing is written for them. To connect one agent, name it. The targets are codex, claude, cursor, copilot and antigravity.

    recallstack agent install claude

    Codex asks you to trust new hooks once. Open Codex, run /hooks and trust the Recallstack hooks. Until you do, Codex skips them and its sessions get no brief.

    The project is recognised from the repo you're in and named after it. If Recallstack finds rules you already wrote for your agents, like CLAUDE.md or AGENTS.md, it offers to turn them into records.

    To keep Recallstack to a single repo instead, run the install inside it with --repo.

    Start a new session in each agent afterwards. Sessions that are already open won't get the brief until you restart them.

  4. Check it's working

    See what's connected:

    recallstack agent status

    Each connected agent gets a ✓. The output also says who's signed in, the project for this folder, and whether anything is waiting to be sent. If Codex is still waiting for you in /hooks, it says so.

    Then work in one agent for a bit, and see exactly what the next session will be told:

    recallstack brief

How capture works

You don't record anything by hand. After each agent turn, a hook hands the session to a background worker on your machine and returns straight away, so the agent never waits on it.

The worker reads the finished turn and runs a short, separate pass with an agent you already have: codex exec, claude -p or copilot -p. That pass stays out of your normal history. It picks out records, strips secrets, and sends only the records.

Agents also note decisions, new questions and corrections on their own as they work, without asking you. The skill Recallstack installs teaches them when.

What counts most

When signals disagree, the stronger one wins. Strongest first:

  1. Corrections. “No, do it this way.”
  2. Your own statements. A goal, a reason, a rule.
  3. Choices. The options that lost are kept too.
  4. Answers. A question closes and becomes a decision.
  5. Accepted proposals. The weakest, because silence isn't always a yes.

When something goes wrong

If the service can't be reached, records wait on your machine and are retried in the background for up to 24 hours. If you're signed out, they wait for your next recallstack login and are sent then.

Choosing the model

For Codex, Claude Code and Copilot you can pick which model the background pass uses:

recallstack agent model claude <model>

Run it without a model to see the current one, or add --clear to go back to the default.

The brief

Every session starts with a short brief, so the agent picks up where you left off. It's kept small on purpose and holds:

  • The active goal. What you're going for.
  • Current focus. What you're on and the next step.
  • Decisions in force. With the reason behind each one.
  • Open questions. Anything still waiting on an answer.
  • Taste. How you like things done, where it applies.

It stays current as you work, so there's no save step. Only things you said or confirmed go in. Anything an agent only guessed waits for you in review. See exactly what the next session will be told:

recallstack brief

Add --agent codex to see another agent's version, or --all to include the older decisions a full brief leaves out. To fix something in it, tell your agent, or change the record yourself (see Changing a record).

If an agent's plan goes against a decision in force, it stops, tells you what conflicts, and asks you to confirm before it acts.

Records

A record is one thing worth remembering. There are five kinds: goals, focus, decisions, questions and taste. Each one answers the same five things.

What
The thing itself, in a sentence.
Why
The reason, and for a decision, the options you turned down.
Where
Everywhere, one project, or one part of a project.
When
When it was set, and when it stopped applying.
How
Which agent heard it, your exact words, and how sure it is.

Changes and conflicts

Nothing is overwritten. When a record changes, the old one is kept and linked to the one that replaced it.

If you told Codex one thing on Oct 3 and Claude something else on Oct 10, Recallstack puts both to you and asks which holds. It never quietly picks one.

Projects

A project is recognised from the repo you're in and named after it. Records belong to you, not the project, so your taste and decisions can follow you from one project to the next.

recallstack project rename <name>

Work outside a repo gets a name you give it. Run this in that folder:

recallstack project use "<name>"

Changing a record

Usually you just tell the agent (“that only applies here”, “drop the Docker rule”) and it changes the record for you. You can do the same by hand. Every record has a short ref, like D1 or T2, shown in the brief.

Why something is the way it is, with your words and the options that lost. Pass words instead of a ref to search:

recallstack why "dark theme"

Narrow, reword or re-reason a record, end it, or take back the last change:

recallstack adjust T2 --where project
recallstack drop T5
recallstack undo

--where takes everywhere, project, project:<name> or path:<path>. undo <ref> reverses the latest change to one record, any time, so a dropped record can come back.

Settling what needs you

Conflicts, records an agent proposed, and imports you chose to look over wait for you. Go through them one at a time, with one key each:

recallstack review

Importing rules you already wrote

Rules in CLAUDE.md, AGENTS.md, Cursor rules and Copilot instructions hold a lot of your taste and decisions. Import reads them on your machine with an agent you have, keeps the intent and taste, and skips what only describes the code or your tools. It shows you everything before anything is sent, and your files stay as they are.

recallstack import

Add --preview to look without sending, or --review to keep them out of briefs until you've gone through them. Cursor's user rules live inside Cursor, so paste them in with --paste.

Agents

Every agent gets the same records and the same brief. Here's what agent install sets up for each one, first for every repo (the default), then with --repo.

Codex

Hooks at session start, on each prompt, before tools run, at the end of each turn and when the session closes, plus a Recallstack skill. It also turns on Codex's hooks feature in config.toml. Codex asks you to trust new hooks once in /hooks. The background pass runs with codex exec. Model can be set.

~/.codex/hooks.json, ~/.codex/config.toml, ~/.codex/skills/recallstack/. With --repo: the same files under .codex/ in the repo, which Codex reads only once it trusts that folder.

Claude Code

Hooks at session start, on each prompt, before edits and commands, at the end of each turn (in the background) and when the session closes, plus a skill. The background pass runs with claude -p. Model can be set.

~/.claude/settings.json, ~/.claude/skills/recallstack/. With --repo: .claude/settings.local.json and .claude/skills/recallstack/.

Cursor

Hooks before each prompt, after each response, at the end of a turn and before shell commands. Cursor has no session-start hook, so the brief goes into a rule file that's refreshed at the end of each turn. File edits can't be paused before they happen, so the hard stop covers shell commands. Works in the Cursor editor; the Cursor CLI isn't supported. Turns are read by Claude Code, Codex or Copilot, whichever you have.

~/.cursor/hooks.json. In each repo you use it in: .cursor/rules/recallstack-brief.mdc, kept out of git through .git/info/exclude.

Copilot

Works in both the Copilot CLI and VS Code. Hooks at session start, on each prompt, before tools run and at the end of a session. The background pass runs with copilot -p. Model can be set.

A Copilot CLI plugin, installed with copilot plugin install, so the copilot command needs to be on your PATH. With --repo: .github/hooks/recallstack.json.

Antigravity

An end-of-turn hook plus a skill, for the Antigravity editor and CLI. The brief reaches it through the skill, refreshed at the end of each turn. There's no hook to pause a plan, so the hard stop is an instruction only. Turns are read by Codex, Claude Code or Copilot, whichever you have.

An Antigravity CLI plugin in ~/.gemini/antigravity-cli/plugins/recallstack. With --repo: .agents/.

Disconnect an agent, or every agent with all. Add --repo to undo a repo install:

recallstack agent uninstall cursor

Your data

  • Only the records are kept, plus the exact words each one came from.
  • Full conversations stay on your machine.
  • Secrets are stripped before anything leaves it.
  • Your sign-in lives in your system's secure store. If there isn't one, it goes in a config file only your user can read.

What's on your machine

Everything the CLI keeps lives in ~/.recallstack: your settings, which project each repo belongs to, a cached brief, and records waiting to be sent. Set RECALLSTACK_HOME to move it. Nothing is written into your repos, apart from Cursor's brief rule, which stays out of git.

To disconnect every agent:

recallstack agent uninstall all

Export or delete everything Recallstack holds about you: [COMMAND TBD]. The privacy policy has the rest.

CLI reference

Add --help to any command to see its options. Commands print plain text; the ones with --json print JSON for scripts.

Account

recallstack login [--no-browser]Sign in through the browser, matching a code shown in the terminal.
recallstack logoutSign out on this computer.
recallstack whoamiShow who's signed in.

Agents

recallstack agent install [target...]Connect every agent found, or the ones named: codex, claude, cursor, copilot, antigravity. Options: --repo, --no-import, --json.
recallstack agent statusShow what's connected, who's signed in, the project and anything waiting to be sent. Option: --json.
recallstack agent uninstall <target|all>Disconnect an agent. Option: --repo.
recallstack agent model [target] [model]Show or set the model for the background pass (codex, claude, copilot). Option: --clear.

Projects

recallstack projectShow the project for this folder.
recallstack project rename <name>Rename it. Refs and records stay as they are.
recallstack project use <name>Link this repo to another project, or name work outside a repo.

Records

recallstack briefShow exactly what the next session will be told. Options: --agent <agent>, --all, --json.
recallstack reviewSettle what needs you, one key at a time. Option: --all for every project.
recallstack why <ref | "words">Why something is the way it is. Option: --project <name>.
recallstack adjust <ref>Narrow, reword or re-reason a record. Options: --where, --text, --why, --quote.
recallstack drop <ref>End a record. It's kept in history and left out of briefs.
recallstack undo [<ref>]Reverse the latest change, or the latest change to one record.
recallstack import [file...]Turn rules you wrote for agents into records. Options: --paste, --yes, --review, --preview.

Run by agents

recallstack note <kind> "<what>"Record a goal, focus, decision, question or taste. Options include --why, --quote, --instead-of, --replaces, --answers, --where.
recallstack hold <ref> --plan "..."Pause edits until you answer, when a plan goes against a decision.
recallstack resolve <ref> <choice>Settle a hold or a conflict with your answer.

Settings

recallstack config showShow settings and sign-in status.
recallstack config wherePrint the path of the config file in use.
recallstack config base-url [url]Point the CLI at a different server. --clear goes back to the default.
RECALLSTACK_HOME=<dir>Keep the CLI's files somewhere other than ~/.recallstack.
RECALLSTACK_TOKEN_STORE=fileKeep your sign-in in the config file instead of the secure store.
recallstack --versionPrint the installed version.

Troubleshooting

recallstack: command not found

The installer puts the binary in ~/.local/bin. If that folder isn't on your PATH, add it to your shell profile and open a new terminal:

export PATH="$HOME/.local/bin:$PATH"

On Windows, open a new PowerShell window so the updated PATH loads.

Codex sessions start without a brief

Codex skips new or changed hooks until you trust them. Open Codex, run /hooks and trust the Recallstack hooks. recallstack agent status tells you when Codex is still waiting.

An agent isn't capturing anything

Run recallstack agent status. If the agent doesn't have a ✓, connect it again and start a new session:

recallstack agent install codex

There's no browser for sign-in

On a server or over SSH, sign in from any other device. This prints the link and the code to enter:

recallstack login --no-browser

You used the old npm version

The npm package is retired. Remove the global npm install, run the installer above, then connect your agents again so the old hook commands are replaced. Your settings and project links are kept.

recallstack agent install

Copilot setup fails

It installs a plugin through the Copilot CLI, so copilot has to be on your PATH. Install the Copilot CLI, or connect Copilot for one repo with --repo.

Linux can't reach the secure store

On machines without Secret Service, Recallstack falls back to its config file on its own. To always use the file:

export RECALLSTACK_TOKEN_STORE=file

macOS or Windows warns about the binary

Release binaries are checksummed but not yet code-signed, so Gatekeeper or SmartScreen may warn about a manual download. The install script checks the checksum for you. To check a manual download yourself on macOS:

shasum -a 256 -c SHA256SUMS

On Linux, use sha256sum -c SHA256SUMS.

You were signed out for a while

Nothing is lost. Records wait on your machine and are sent the next time you run recallstack login, which tells you how many went through.

Still stuck? [SUPPORT CONTACT]