Set up ResumeContext (for coding agents)

This page is addressed to a coding agent. A person can hand their agent this and say “set this up in this folder”:

Set up ResumeContext on this project, following https://resumecontext.com/docs/agent-setup.md (if your browser tool cannot read it, run: curl -fsSL https://resumecontext.com/docs/agent-setup.md)

That URL is this page as plain markdown, which is what an agent can read — the rendered page is a few hundred kilobytes of HTML that some agents cannot make sense of. If a tool reports it cannot read the page, fetch it with curl -fsSL instead: some agents answer a URL by searching for it rather than fetching it, and a recently published page is not indexed anywhere yet. If you are a person reading this, the human version is the quickstart. You are setting up ResumeContext for the person you are working for: ResumeContext records every coding-agent session in a project folder into one shared archive, and hands it back to any agent through an MCP server.

Rules

Ask before installing anything and before changing files outside the project folder. Show the command you intend to run.
Never commit the token. The token resumecontext mcp prints grants access to the person’s projects for a year and cannot be revoked. Keep it out of git, out of shared files, and out of anything you print into a report. Add any config file that contains it to .gitignore.
Configure MCP for this folder only, never a global or shared scope. Another project would otherwise connect to the wrong archive.
Stop and show the person the output if any command fails, or if a command asks something you cannot answer from what they told you. Do not guess an email address, an account or a project.
Never run resumecontext uninstall, logout, or resumecontext projects delete. They are destructive and are not part of setup.

Step 1: check the machine

node --version && resumecontext --version || true

Node.js 22 or newer is required. If it is older or missing, stop and tell the person.
On Windows everything here works except background auto-sync, which needs launchd or systemd. Say so, and tell the person that syncing there is resumecontext sync, run when they want to push.
resumecontext 0.3.0 or newer is required: everything below relies on flags that older versions do not have, and an older one fails with unknown option. Install or upgrade it, after asking:

npm install -g resumecontext@latest

Install it globally even inside a project. Background sync runs the installed command, so it is not set up when run through npx, and a folder install stops working when that folder is deleted. On macOS and Linux this needs no sudo with a normal Node.js setup; if npm reports a permissions error, show the person rather than re-running with sudo. Check the state of this folder first, so you never redo work that is already done:

resumecontext verify --json

Exit code 0 — the archive side is already set up, by an earlier run or from another agent. This does not mean there is nothing to do: you are probably not part of it yet. Skip init and follow “Already set up? Add yourself” below.
signed-in passes but others fail — skip to step 3 and carry on from there.
signed-in fails — sign in below.

When signed-in passes, its detail names the account (signed in as ...). Show it and check it is the account the person means. If it is not, they can switch with resumecontext logout followed by auth — ask first, because it signs this machine out of every project. To sign in, run:

resumecontext auth --no-browser

This prints a link and waits. Give the person the link and ask them to open it. It finishes on its own once they have signed in, and prints Logged in as <email>. Do not run it in the background where its output is lost, and do not attempt to sign in on their behalf.

Already set up? Add yourself

You are the second (or third) agent on a folder someone already connected. Nothing needs creating; two things need adding, and both are about you:

Is your own history being synced?
resumecontext agents --list --json
configured is what this project syncs from today, as {"claude-code": {"dirs": ["/Users/me/.claude"]}}. If the agent you are is missing from it, add yourself — passing the existing entries as well, because --set replaces the whole list:
# configured had claude-code; you are Cursor resumecontext agents --set claude-code=/Users/me/.claude,cursor --json
Use each agent’s own dirs from configured, and your own from available (the defaultDir of your entry, or a path the person gives you). If your entry shows "found": false, your history is not where it normally lives — ask the person for the path rather than guessing.
Can you search the archive? Configure the MCP server for yourself, as step 5 describes for your agent, unless this folder already has it.

Then run step 6 (verify) and report. Do not run init: this folder already belongs to a project, and the rest of this page is for setting one up from scratch.

Step 3: ask which coding agents this is for

This machine may hold history for several agents. Which ones belong to this project, and where their history lives, is the person’s call — ask, do not assume. Their answer decides two things: whose sessions are archived (step 4), and which agents get the MCP server configured so they can search it (step 5).

resumecontext agents --list --json

It prints every supported agent with defaultDir (where its history normally lives) and found (whether it is actually there). Show the person that list — the found ones, with their directories — and ask:

Which of these should sync into this project? Their sessions are archived, and each one they name also gets connected to the archive in step 5 — including agents that are not you. Include yourself unless they say otherwise: an agent that sets this up and then does not sync its own sessions is the surprise nobody wants.
Are those the right directories? Someone with history in an unusual place can give you another path.

Keep their answer for the next step, as name or name=/path/to/history entries: claude-code,cursor or claude-code=/Users/me/work/.claude. An agent that keeps history in more than one place is repeated, once per directory: claude-code=~/.claude,claude-code=/archive/.claude.

Step 4: connect the folder

First find out which case you are in. Look in this folder and every folder above it, because a marker in a parent means this project already exists and running init here would create a second, separate one:

dir=$PWD; while [ "$dir" != "/" ]; do [ -f "$dir/.resumecontext.json" ] && echo "$dir/.resumecontext.json" && break; dir=$(dirname "$dir"); done

If it finds one above the current folder, that folder is the project: work there instead, and tell the person rather than creating a new project for a subfolder.

No .resumecontext.json
.resumecontext.json exists

A new project. Confirm with the person that this exact folder is what they want archived (init never walks up to a git root, so a monorepo subfolder can be its own project), then pass what they chose in step 3:

resumecontext init --agents claude-code,cursor --json

Use name=/path/to/history for any directory they corrected. --yes instead of --agents takes every agent found on this machine without asking — only use it if they said so.

The project already exists — a teammate created it, or this is another of the person’s own machines, and the file came with the repository. Run the same command in the folder that contains the file, not a subfolder.

resumecontext init --agents claude-code,cursor --json

It connects this machine to the existing project and leaves the file unchanged. If it reports a pending invite, the person has been invited but has not accepted:

resumecontext accept --agents claude-code,cursor --json

.resumecontext.json is meant to be committed: it is how teammates and the person’s other machines join the same project. Do not add it to .gitignore. If init fails with No <agent> history found at ..., that directory is not where that agent keeps its history on this machine. Ask the person for the right path and pass it as --agents name=/path. If it fails with You don't have access to this project, the marker belongs to someone else’s project and this account was never invited. Stop: the person needs the owner to run resumecontext share <their email>, and then resumecontext accept here. Do not delete the marker, and do not create a new project in its place. To change the choice later, at any time:

resumecontext agents --set claude-code=/path/to/history,cursor --json

Step 5: connect the MCP server, for every agent they chose

Two different things share the word “agent”, and this step is the second one:

Step 3 was whose history is read into the archive.
This step is which agents can search it.

Do this for every agent the person named in step 3, not only the one you are. Someone who picked Claude Code and Cursor expects both to be able to ask the archive questions; configuring only yourself leaves them with half a setup and no way to know. Get this project’s MCP URL and token once:

resumecontext mcp --json

It prints {"mcpUrl": "...", "token": "..."}. Every block below uses those two values. Keep them out of anything shared, and add each file you create to .gitignore. If a config file already exists, merge into it. Add the resumecontext entry beside whatever servers are already there; never overwrite the file. If an entry named resumecontext is already present with a different URL or token, show the person both and ask which to keep. Most of these need one action from the person afterwards, which you cannot do for them. Note each one as you go and list them all in step 7.

Claude Code

claude mcp add-json resumecontext \
  '{"type":"http","url":"<MCP_URL>","headers":{"Authorization":"Bearer <TOKEN>"}}' \
  --scope local

--scope local means this folder only, and keeps the token out of any shared file. Do not use --scope user (global) or --scope project (writes the token into a committed .mcp.json). The single quotes above work in a POSIX shell and in PowerShell. In cmd.exe they are not quoting at all: use double quotes around the JSON and double the quotes inside it, or run the command from PowerShell, Git Bash or WSL. Then the person must: start a new Claude Code session in this folder, or run /mcp in the current one, before the tools appear. Run the command even if you are not Claude Code — it only needs the claude CLI on PATH. If it is not installed, say so rather than writing ~/.claude.json yourself.

Cursor

Create .cursor/mcp.json in the project folder:

{
  "mcpServers": {
    "resumecontext": {
      "url": "<MCP_URL>",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Then the person must: open Cursor Settings → MCP & Tools (called Tools & MCP in some versions), find resumecontext, and enable and approve it. Cursor does not load a project MCP server until they do, so the file alone changes nothing. Add .cursor/mcp.json to .gitignore.

Codex

Create .codex/config.toml in the project folder:

[mcp_servers.resumecontext]
url = "<MCP_URL>"
http_headers = { Authorization = "Bearer <TOKEN>" }

Then the person must: trust this project when Codex asks, and restart Codex if it is already running. Codex ignores project configuration for untrusted folders. Add .codex/config.toml to .gitignore.

opencode

Create opencode.json in the project root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "resumecontext": {
      "type": "remote",
      "url": "<MCP_URL>",
      "enabled": true,
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

Then the person must: restart opencode if it is running. Add opencode.json to .gitignore.

Any other agent

Use its own folder-level MCP configuration, with the same URL and an Authorization: Bearer <token> header. If you cannot find one, say so and give the person the two values — do not put them in a global configuration.

What to hand back

Agent	What the person still has to do
Claude Code	New session in this folder, or `/mcp`
Cursor	Settings → MCP & Tools → enable and approve `resumecontext`
Codex	Trust the project, restart Codex
opencode	Restart opencode

Step 6: verify

resumecontext verify --json

Exit code 0 means every check passed. Otherwise each failing check carries a fix; apply the ones you can, and show the person the rest. verify covers the archive side — signed in, folder connected, history syncing. It cannot see any agent’s MCP configuration, which is why step 5 and the question below are separate checks.

Check	Means
`signed-in`	This machine has a session
`machine-bound`	Sessions will be attributed to this machine
`project-marker`	The folder is connected to a project
`project-access`	The account can reach that project
`agents-configured`	Which agents this machine reads history from
`auto-sync`	The background service is running and covers this folder
`sync`	History was scanned and anything new was pushed just now

If the sync check says turns were found locally but none were pushed, that is normal for a session written moments ago: the last turn of a session is held back for a few seconds in case the file is still being written, and auto-sync picks it up within about 20 seconds. Then confirm the MCP server is connected from your side. You can only check your own tools — for the other agents the person chose, the check is theirs to run once they have done their part from step 5, by asking the same question in that agent. Reconnect or restart so the new server is loaded, and ask it something only the archive can answer:

who all are a part of this project?

A connected agent lists the project’s members. If your tools do not include ResumeContext, the MCP configuration in step 4 has not been picked up yet.

Step 7: tell the person what happened

Report, briefly:

which account is signed in, which folder is now archived, and which coding agents it syncs from;
what they still have to do by hand, per agent, from the table in step 5 — Cursor in particular does nothing until they enable the server in its settings;
that sessions sync automatically about every 20 seconds, with nothing to run;
which config file you created, and that you added it to .gitignore;
anything you could not finish, with the exact command that failed.

Do not print the token in your summary.

If something goes wrong

Symptom	What it means
A command hangs	It is waiting for an answer it cannot get. Stop it, and use the flags above (`--agents`, `--yes`, `--no-browser`) instead.
`not an interactive terminal`	Same thing, reported properly. The message names the flag to use.
`Auto-sync couldn't be set up`	Everything else works; syncing needs `resumecontext sync` by hand. Show the person the reason. See daemon.
`You're not logged in`	Go back to step 2.
`No resumecontext project found`	You are not in the project folder, or step 3 did not finish.
MCP tools missing	The agent has not reloaded its MCP configuration, or has not been enabled in its settings (Cursor) or trusted (Codex). See the table in step 5.
`unknown option '--json'` (or `--agents`)	The installed CLI is older than 0.3.0. `npm install -g resumecontext@latest`.
`You don't have access to this project`	The marker belongs to a project this account was never invited to. See step 4.
A second project appeared for the same repo	`init` was run in a subfolder of a folder that already had a marker. The marker in the subfolder should be deleted, and the extra project removed by its owner.

Every command works this way

Anything the CLI can do, you can do for the person: every command takes --json and prints one object, and every command that would ask something takes a flag that answers it instead — --agents/--yes for the agent question, -y for a confirmation. A command that still cannot get an answer fails immediately and names the flag, rather than hanging.

resumecontext members --json                    # who has access
resumecontext share teammate@example.com --json # invite someone
resumecontext projects list --json              # every project
resumecontext daemon status --json              # is auto-sync running here
resumecontext sync --json                       # push now, don't wait

Two exceptions to run only when asked in so many words, because they cannot be undone: resumecontext projects delete <id> -y and resumecontext uninstall -y. The full human documentation is at resumecontext.com/docs, and every page is available as raw markdown by adding .md to its URL.

Getting started

How it works

What your agent can do

CLI reference

The web app

Set up ResumeContext (for coding agents)

Rules

Step 1: check the machine

Already set up? Add yourself

Step 3: ask which coding agents this is for

Step 4: connect the folder

Step 5: connect the MCP server, for every agent they chose

Claude Code

Cursor

Codex

opencode

Any other agent

What to hand back

Step 6: verify

Step 7: tell the person what happened

If something goes wrong

Every command works this way

​Rules

​Step 1: check the machine

​Step 2: see what is already set up, and sign in

​Already set up? Add yourself

​Step 3: ask which coding agents this is for

​Step 4: connect the folder

​Step 5: connect the MCP server, for every agent they chose

​Claude Code

​Cursor

​Codex

​opencode

​Any other agent

​What to hand back

​Step 6: verify

​Step 7: tell the person what happened

​If something goes wrong

​Every command works this way

Rules

Step 1: check the machine

Step 2: see what is already set up, and sign in

Already set up? Add yourself

Step 3: ask which coding agents this is for

Step 4: connect the folder

Step 5: connect the MCP server, for every agent they chose

Claude Code

Cursor

Codex

opencode

Any other agent

What to hand back

Step 6: verify

Step 7: tell the person what happened

If something goes wrong

Every command works this way