From 2af2db74dc8c8a8a5e8387f6680830c99942ed63 Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 01:29:27 +0000 Subject: [PATCH 1/7] Document the local-agent install one-liner Adds plans/install/local-agent.mdx covering the curl | bash installer that ref.tools leads with: the unified command, per-agent variants and why they must be quoted, platform support, sign-in via browser device pairing, re-running and updates, what the plugin adds to each agent, and uninstall. Lists it first in the Install MCP Server group and points at it from the install index intro and card group. --- docs.json | 1 + plans/install/index.mdx | 6 ++ plans/install/local-agent.mdx | 126 ++++++++++++++++++++++++++++++++++ 3 files changed, 133 insertions(+) create mode 100644 plans/install/local-agent.mdx diff --git a/docs.json b/docs.json index 61de6b4..a6ca386 100644 --- a/docs.json +++ b/docs.json @@ -88,6 +88,7 @@ { "group": "Install MCP Server", "pages": [ + "plans/install/local-agent", "plans/install/index", "plans/install/claude-code", "plans/install/codex", diff --git a/plans/install/index.mdx b/plans/install/index.mdx index d93b917..3d91b68 100644 --- a/plans/install/index.mdx +++ b/plans/install/index.mdx @@ -3,6 +3,8 @@ title: "Installation" description: "Install the Ref Plans MCP server in your preferred coding environment" --- +Using Claude Code or Codex on your own machine? One command sets up both, signs you in through your browser, and installs the planning loop along with the MCP server — see the [quick install](/plans/install/local-agent). The guides below are the manual path, and the one to use for every other agent. + ## About the Ref Plans MCP Server Ref Plans has its own MCP server, separate from the [Ref Context MCP server](/context/install/index). It lets coding agents read, write, and manage your plans directly. @@ -99,6 +101,10 @@ These tools require: Choose your coding environment below to get started: + + Set up Claude Code and Codex with one command. + + Connect Cursor to Ref Plans. diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx new file mode 100644 index 0000000..7069275 --- /dev/null +++ b/plans/install/local-agent.mdx @@ -0,0 +1,126 @@ +--- +title: "Quick Install" +description: "Set up Ref in Claude Code and Codex with one command." +--- + +import GetHelp from '/snippets/get-help.mdx'; + +Ref only changes how you work once it is inside the agent you already use, and doing that by hand means registering an MCP server in every agent, on every machine. One command does it instead: it installs Ref into Claude Code and Codex on your machine, signs you in through your browser, and sets up the planning loop, so on substantial tasks the agent drafts a Ref plan and pauses for your review before it writes code. + +## Requirements + +| Requirement | Detail | +| --- | --- | +| Operating system | macOS or Linux, Intel or ARM. Linux works on glibc and musl distributions. Windows is not supported. | +| Coding agent | Claude Code, Codex, or both, on your `PATH`. Codex must be version 0.138.0 or newer — an older one is skipped with a warning, and Claude Code still installs. | +| Tools | `curl`. Node.js is not required, at install time or afterwards. | +| Account | A Ref account — you approve the install from your browser. | + +## Install + +``` +curl -fsSL https://api.plan.ref.tools/plugins/install/local-agent | bash +``` + +One run sets up every supported agent it finds on your `PATH`. If it finds neither Claude Code nor Codex, it stops and says so without changing anything. + +## What the installer does + + + + The binary lands under `~/.ref`. Your `PATH` and your shell startup files are not modified, and the download is checksum-verified before it runs. If the binary cannot be installed, the run stops there — before it configures any agent. + + + + There is no API key to copy. The installer prints an approval link and opens it in your browser, where the page names the machine asking and gives you **Approve** or **Cancel**. Approving mints a new API key and delivers it to your terminal. + + The link is good for ten minutes. If it expires, the installer offers to let you paste a key from [ref.tools/keys](https://ref.tools/keys) instead. If the machine already holds a working Ref key, the installer reuses it and never prompts. + + The key is written to `~/.ref/config.json`, readable only by you. It stays valid until you revoke it at [ref.tools/keys](https://ref.tools/keys). + + + + Both agents get the same thing: a session-start hook, a stop hook, and the Plans MCP server, packaged as a plugin. See [what gets added to your agent](#what-gets-added-to-your-agent) below. + + + + The run closes with a line per agent. Claude Code is ready immediately. Codex needs one more step from you: run `codex`, and when it says **Hooks need review**, answer **Trust all and continue**. Ref stays off in Codex until you do. + + + +## Install one agent only + +To set up a single agent, use its own command instead of the bare one: + +``` +curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=claude-code' | bash +``` + +``` +curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=codex' | bash +``` + +**Keep the quotes.** The `?agent=` parameter has to survive your shell. Unquoted, the URL serves the unified installer rather than the targeted one — and on an uninstall that removes more state than you asked for. + +## Verify + +The installer's own closing summary is the first check: a line per agent, and `You're set.` when nothing is left to do. + +For Claude Code, you can confirm the MCP server separately: + +``` +claude mcp list +``` + +You should see `plugin:ref:Plans` listed. + +## Re-running and updates + +Re-running the install command is safe. It rewrites the plugin files in place rather than stacking a second copy, and reuses the key already on the machine instead of asking you to approve again. If one agent reported an error, re-running is how you finish it — the agent that already succeeded is left as it is. + +The same command is the update path. Run it again to move to the current version of the binary and the plugins. + +## What gets added to your agent + +Everything Ref installs rides inside a plugin, so the config you own is left alone. + +**Claude Code** — a plugin directory under `~/.claude/skills/ref`, which Claude Code loads on its own. Your `settings.json` is never touched. + +**Codex** — two plugins served from a local marketplace at `~/.ref/codex-plugins`, plus one line in `~/.codex/.env` holding your API key, readable only by you. Codex's MCP config can name an environment variable but cannot run a command to fetch a key, which is why that one line lives outside the plugin. + +In each agent, the plugin adds: + +- **A session-start hook** — tells the agent to read Ref's planning guidance before it starts work, so it routes the request instead of diving straight into the first file. +- **A stop hook** — checks the turn actually reached the end state it committed to, and nudges the agent to finish rather than stopping halfway, including when a plan review it requested is still pending. +- **The Plans MCP server** — read, write, comment on, and create plans from inside the agent. This is the same server the [manual install guides](/plans/install/index) configure. + +A second plugin, installed alongside it, records agent lifecycle events locally. A capture policy fetched from Ref during install decides what may leave your machine: file contents, prompts, and command arguments are dropped before anything is sent, and what ships is the shape of a session — tool names, counts, timings, and the working directory. + +To stop recording without uninstalling anything else: + +``` +~/.ref/bin/ref record disable +``` + +That choice survives reinstalls and updates. Undo it with `~/.ref/bin/ref record enable`. + +## Uninstall + +``` +curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstall' | bash -s -- --uninstall +``` + +This removes the plugins from every agent that has them, then removes the binary and the key store once no agent still needs them. Add flags after `--`: + +| Flag | Effect | +| --- | --- | +| `--only claude` or `--only codex` | Limit the run to one agent. Repeatable. The other agent keeps working. | +| `--purge` | With `--uninstall`, also delete the locally recorded session data. Without it, that data survives, so a reinstall keeps its place. | + +Your API key stays active on your account after an uninstall — revoke it at [ref.tools/keys](https://ref.tools/keys) if you are done with it. Agent sessions that are already running keep the old key until you restart them. + +## Other agents + +This command covers Claude Code and Codex. For every other agent — Cursor, VS Code, Zed, Windsurf, and the rest — register the MCP server by hand with the [installation guides](/plans/install/index). + + From d69a488841152a62b98724a6b082f95d033db3a3 Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 01:53:46 +0000 Subject: [PATCH 2/7] Plainer wording: prefer needs/needed and earlier Word-level pass toward simplified technical English. Swaps requires/required and previous for their plainer equivalents on lines this PR introduced. No technical content or product names changed. --- plans/install/local-agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx index 7069275..c9484b9 100644 --- a/plans/install/local-agent.mdx +++ b/plans/install/local-agent.mdx @@ -13,7 +13,7 @@ Ref only changes how you work once it is inside the agent you already use, and d | --- | --- | | Operating system | macOS or Linux, Intel or ARM. Linux works on glibc and musl distributions. Windows is not supported. | | Coding agent | Claude Code, Codex, or both, on your `PATH`. Codex must be version 0.138.0 or newer — an older one is skipped with a warning, and Claude Code still installs. | -| Tools | `curl`. Node.js is not required, at install time or afterwards. | +| Tools | `curl`. Node.js is not needed, at install time or afterwards. | | Account | A Ref account — you approve the install from your browser. | ## Install From e44187d7a8d1f2304a5166b12c3adf082b9b3aa4 Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 02:08:18 +0000 Subject: [PATCH 3/7] Rework the local-agent page around install and the Plans UI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Retitles "Quick Install" to "Local agents" and reorders the page around what a reader needs: the one install command and the browser approval, a supported platforms table, then the payoff — local sessions in the Ref Plans sidebar with live status, the plan/investigation/receipt shapes, the review wait, and the trigger rating. Cuts the implementation detail: the step-by-step of what the installer writes, manifests, PATH and binaries, the uninstall flag table, and the capture-policy and plugin internals. Targeted per-agent installs and the uninstall command stay, demoted below the plain install, with the quoting warning intact. Updates the install index lead-in and card to match the new title. --- plans/install/index.mdx | 4 +- plans/install/local-agent.mdx | 115 ++++++++++++++-------------------- 2 files changed, 50 insertions(+), 69 deletions(-) diff --git a/plans/install/index.mdx b/plans/install/index.mdx index 3d91b68..6cff6f8 100644 --- a/plans/install/index.mdx +++ b/plans/install/index.mdx @@ -3,7 +3,7 @@ title: "Installation" description: "Install the Ref Plans MCP server in your preferred coding environment" --- -Using Claude Code or Codex on your own machine? One command sets up both, signs you in through your browser, and installs the planning loop along with the MCP server — see the [quick install](/plans/install/local-agent). The guides below are the manual path, and the one to use for every other agent. +Using Claude Code or Codex on your own machine? One command sets up both, signs you in through your browser, and connects their sessions to Ref Plans — see [local agents](/plans/install/local-agent). The guides below are the manual path, and the one to use for every other agent. ## About the Ref Plans MCP Server @@ -101,7 +101,7 @@ These tools require: Choose your coding environment below to get started: - + Set up Claude Code and Codex with one command. diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx index c9484b9..9b30d30 100644 --- a/plans/install/local-agent.mdx +++ b/plans/install/local-agent.mdx @@ -1,20 +1,11 @@ --- -title: "Quick Install" -description: "Set up Ref in Claude Code and Codex with one command." +title: "Local agents" +description: "Set up Claude Code and Codex with one command, and see their sessions in Ref Plans." --- import GetHelp from '/snippets/get-help.mdx'; -Ref only changes how you work once it is inside the agent you already use, and doing that by hand means registering an MCP server in every agent, on every machine. One command does it instead: it installs Ref into Claude Code and Codex on your machine, signs you in through your browser, and sets up the planning loop, so on substantial tasks the agent drafts a Ref plan and pauses for your review before it writes code. - -## Requirements - -| Requirement | Detail | -| --- | --- | -| Operating system | macOS or Linux, Intel or ARM. Linux works on glibc and musl distributions. Windows is not supported. | -| Coding agent | Claude Code, Codex, or both, on your `PATH`. Codex must be version 0.138.0 or newer — an older one is skipped with a warning, and Claude Code still installs. | -| Tools | `curl`. Node.js is not needed, at install time or afterwards. | -| Account | A Ref account — you approve the install from your browser. | +One command connects the coding agents on your machine to Ref. After it runs, those sessions show up in your Ref Plans sidebar with live status, and on substantial work the agent drafts a plan and waits for your review before it writes code. ## Install @@ -22,35 +13,29 @@ Ref only changes how you work once it is inside the agent you already use, and d curl -fsSL https://api.plan.ref.tools/plugins/install/local-agent | bash ``` -One run sets up every supported agent it finds on your `PATH`. If it finds neither Claude Code nor Codex, it stops and says so without changing anything. +One run sets up every supported agent it finds — Claude Code, Codex, or both. If it finds neither, it stops and says so without changing anything. -## What the installer does +**There is no API key to copy.** The installer opens your browser, the page names the machine asking to connect, and you click **Approve**. The link is good for ten minutes; if it expires you can paste a key from [ref.tools/keys](https://ref.tools/keys) instead. A machine that already holds a working Ref key is reused, and you are not asked again. - - - The binary lands under `~/.ref`. Your `PATH` and your shell startup files are not modified, and the download is checksum-verified before it runs. If the binary cannot be installed, the run stops there — before it configures any agent. - +Claude Code is ready as soon as the run finishes. Codex needs one more step from you: run `codex`, and when it says **Hooks need review**, answer **Trust all and continue**. Ref stays off in Codex until you do. Codex also needs version 0.138.0 or newer — an older one is skipped with a warning, and Claude Code still installs. - - There is no API key to copy. The installer prints an approval link and opens it in your browser, where the page names the machine asking and gives you **Approve** or **Cancel**. Approving mints a new API key and delivers it to your terminal. +Agent sessions that are already running keep their old configuration until you restart them, so restart any session you had open. - The link is good for ten minutes. If it expires, the installer offers to let you paste a key from [ref.tools/keys](https://ref.tools/keys) instead. If the machine already holds a working Ref key, the installer reuses it and never prompts. +Re-running the command is safe, and it is also the update path — run it again to move to the current version. - The key is written to `~/.ref/config.json`, readable only by you. It stays valid until you revoke it at [ref.tools/keys](https://ref.tools/keys). - +## Supported platforms - - Both agents get the same thing: a session-start hook, a stop hook, and the Plans MCP server, packaged as a plugin. See [what gets added to your agent](#what-gets-added-to-your-agent) below. - +| Platform | Support | +| --- | --- | +| macOS | Apple silicon and Intel | +| Linux | x86_64 and arm64, on glibc and musl distributions | +| Windows | Not supported | - - The run closes with a line per agent. Claude Code is ready immediately. Codex needs one more step from you: run `codex`, and when it says **Hooks need review**, answer **Trust all and continue**. Ref stays off in Codex until you do. - - +You need `curl`. Node.js is not needed, at install time or afterwards. -## Install one agent only +## Install one agent, or uninstall -To set up a single agent, use its own command instead of the bare one: +To set up a single agent, use its own command: ``` curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=claude-code' | bash @@ -60,64 +45,60 @@ curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=claude- curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=codex' | bash ``` -**Keep the quotes.** The `?agent=` parameter has to survive your shell. Unquoted, the URL serves the unified installer rather than the targeted one — and on an uninstall that removes more state than you asked for. +**Keep the quotes.** The `?agent=` parameter has to survive your shell. Unquoted, the URL serves the unified installer rather than the targeted one — and on an uninstall that removes more than you asked for. -## Verify - -The installer's own closing summary is the first check: a line per agent, and `You're set.` when nothing is left to do. - -For Claude Code, you can confirm the MCP server separately: +To remove Ref from every agent that has it: ``` -claude mcp list +curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstall' | bash -s -- --uninstall ``` -You should see `plugin:ref:Plans` listed. +Your API key stays active on your account afterwards — revoke it at [ref.tools/keys](https://ref.tools/keys) if you are done with it. -## Re-running and updates +## Your sessions in Ref Plans -Re-running the install command is safe. It rewrites the plugin files in place rather than stacking a second copy, and reuses the key already on the machine instead of asking you to approve again. If one agent reported an error, re-running is how you finish it — the agent that already succeeded is left as it is. +Once a session touches a plan — reading it, writing to it, creating it, reviewing it — that session appears in the Ref Plans sidebar under the plan, and stays there while it works. A session working across two plans appears under both. -The same command is the update path. Run it again to move to the current version of the binary and the plugins. +Each row names the agent it is running in, a short label the agent writes for what it is working on (falling back to the repo or folder name), and its current state: -## What gets added to your agent +| What you see | What it means | +| --- | --- | +| A spinner | Working. Hovering names the tool in flight and how long it has been running | +| Waiting for approval | The session is blocked on a permission it needs from you | +| Agent asked a question | The session is blocked on an answer from you | +| Waiting for your next prompt | Idle, with nothing in flight | +| Session finished | The session ended normally | +| Process ended unexpectedly | The session died before it finished | -Everything Ref installs rides inside a plugin, so the config you own is left alone. +The plan row above lights up while any of its sessions is working or waiting on you, so a collapsed sidebar still tells you where things stand. Hovering a row also names the machine it is running on, which matters once you have more than one. -**Claude Code** — a plugin directory under `~/.claude/skills/ref`, which Claude Code loads on its own. Your `settings.json` is never touched. +Rows are honest about what they can see. If a machine stops reporting, or your own browser goes offline, the row dims and drops its live claims rather than showing a stale spinner. -**Codex** — two plugins served from a local marketplace at `~/.ref/codex-plugins`, plus one line in `~/.codex/.env` holding your API key, readable only by you. Codex's MCP config can name an environment variable but cannot run a command to fetch a key, which is why that one line lives outside the plugin. +## What your agent does differently -In each agent, the plugin adds: +Every connected session starts by asking Ref how to handle your request, and the answer routes the work into one of a few shapes: -- **A session-start hook** — tells the agent to read Ref's planning guidance before it starts work, so it routes the request instead of diving straight into the first file. -- **A stop hook** — checks the turn actually reached the end state it committed to, and nudges the agent to finish rather than stopping halfway, including when a plan review it requested is still pending. -- **The Plans MCP server** — read, write, comment on, and create plans from inside the agent. This is the same server the [manual install guides](/plans/install/index) configure. +- **Plan** — you should decide something before work starts. The agent drafts a plan and asks you to review it before it builds. +- **Investigation** — you want to understand something. The digging lands as a document with a link, instead of terminal output that scrolls away. +- **Receipt** — the path was already clear. The agent does the work, then records what it did. -A second plugin, installed alongside it, records agent lifecycle events locally. A capture policy fetched from Ref during install decides what may leave your machine: file contents, prompts, and command arguments are dropped before anything is sent, and what ships is the shape of a session — tool names, counts, timings, and the working directory. +Genuinely small asks are still answered in chat with no document at all. That is a normal outcome, not a failure. -To stop recording without uninstalling anything else: +The shape is judged by the decisions involved, not by the size of the change. A mechanical edit across thirty files is a receipt; a one-line change that settles a non-obvious design call is a plan. -``` -~/.ref/bin/ref record disable -``` +## Plan review and the wait -That choice survives reinstalls and updates. Undo it with `~/.ref/bin/ref record enable`. +When the agent drafts a plan, it genuinely stops and waits for you. -## Uninstall +The review request opens in your browser as a full-screen ask: which agent is asking, and its note on what it wants reviewed. **Start review** takes you into the plan, where you comment inline and then choose **Approve**, **Request changes**, or **Comment**. In the sidebar, the request reads *waiting for your feedback…* for as long as the agent is holding. -``` -curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstall' | bash -s -- --uninstall -``` +Requesting changes is a loop, not a stopping point — the agent revises the plan and asks again. On approval it implements, and where the change lands as a pull request, that pull request links back to the plan. -This removes the plugins from every agent that has them, then removes the binary and the key store once no agent still needs them. Add flags after `--`: +Reviews from an agent are the same review workflow people use on each other's plans; see [review requests](/plans/collaboration/reviews) for the rest of it. -| Flag | Effect | -| --- | --- | -| `--only claude` or `--only codex` | Limit the run to one agent. Repeatable. The other agent keeps working. | -| `--purge` | With `--uninstall`, also delete the locally recorded session data. Without it, that data survives, so a reinstall keeps its place. | +## Rating the trigger -Your API key stays active on your account after an uninstall — revoke it at [ref.tools/keys](https://ref.tools/keys) if you are done with it. Agent sessions that are already running keep the old key until you restart them. +When an agent decides on its own to write something up, you get one question about that decision: was creating it the right call, or should it have just answered next time? Your answers tune how eagerly your agents reach for a document in future. The question is only ever about the decision to write — the content is what reviews and comments are for. ## Other agents From 27f3a22f188f29115d96599dee9515260d966b2c Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 14:56:35 +0000 Subject: [PATCH 4/7] Rework local agents page from review Trims the page to what a reader needs: install and support first, then what changes once connected. Adds a Support matrix in the same shape the custom MCP page uses, a short how-it-works, the session states a sidebar row renders, and the plan-review loop. Drops the installer walkthrough, binary and PATH mechanics, the capture-policy note, and the uninstall flag table. Session-state glyphs are inline data URIs taken from the sidebar's own icon source. Harness requests point at the existing request form. --- plans/install/local-agent.mdx | 107 +++++++++++----------------------- 1 file changed, 34 insertions(+), 73 deletions(-) diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx index 9b30d30..f2a813d 100644 --- a/plans/install/local-agent.mdx +++ b/plans/install/local-agent.mdx @@ -1,11 +1,11 @@ --- title: "Local agents" -description: "Set up Claude Code and Codex with one command, and see their sessions in Ref Plans." +description: "Connect Claude Code and Codex to Ref with one command." --- import GetHelp from '/snippets/get-help.mdx'; -One command connects the coding agents on your machine to Ref. After it runs, those sessions show up in your Ref Plans sidebar with live status, and on substantial work the agent drafts a plan and waits for your review before it writes code. +Connecting the coding agents on your machine to Ref does three things. Your sessions appear in Ref next to the plans they are working on. Your agents work out when a piece of work deserves a plan of its own. And when one decides it does, it drafts that plan and asks you to review it before it writes any code. ## Install @@ -13,95 +13,56 @@ One command connects the coding agents on your machine to Ref. After it runs, th curl -fsSL https://api.plan.ref.tools/plugins/install/local-agent | bash ``` -One run sets up every supported agent it finds — Claude Code, Codex, or both. If it finds neither, it stops and says so without changing anything. +- Authorizes and configures the Ref MCP server +- Installs and signs in the `ref` helper +- Configures every detected agent for local session tracking in Ref +- Configures every detected agent for automatic plan creation and the review loop -**There is no API key to copy.** The installer opens your browser, the page names the machine asking to connect, and you click **Approve**. The link is good for ten minutes; if it expires you can paste a key from [ref.tools/keys](https://ref.tools/keys) instead. A machine that already holds a working Ref key is reused, and you are not asked again. +\* Active sessions may require restart. -Claude Code is ready as soon as the run finishes. Codex needs one more step from you: run `codex`, and when it says **Hooks need review**, answer **Trust all and continue**. Ref stays off in Codex until you do. Codex also needs version 0.138.0 or newer — an older one is skipped with a warning, and Claude Code still installs. - -Agent sessions that are already running keep their old configuration until you restart them, so restart any session you had open. - -Re-running the command is safe, and it is also the update path — run it again to move to the current version. - -## Supported platforms - -| Platform | Support | -| --- | --- | -| macOS | Apple silicon and Intel | -| Linux | x86_64 and arm64, on glibc and musl distributions | -| Windows | Not supported | - -You need `curl`. Node.js is not needed, at install time or afterwards. - -## Install one agent, or uninstall - -To set up a single agent, use its own command: - -``` -curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=claude-code' | bash -``` - -``` -curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?agent=codex' | bash -``` - -**Keep the quotes.** The `?agent=` parameter has to survive your shell. Unquoted, the URL serves the unified installer rather than the targeted one — and on an uninstall that removes more than you asked for. - -To remove Ref from every agent that has it: +### Uninstall ``` curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstall' | bash -s -- --uninstall ``` -Your API key stays active on your account afterwards — revoke it at [ref.tools/keys](https://ref.tools/keys) if you are done with it. - -## Your sessions in Ref Plans - -Once a session touches a plan — reading it, writing to it, creating it, reviewing it — that session appears in the Ref Plans sidebar under the plan, and stays there while it works. A session working across two plans appears under both. - -Each row names the agent it is running in, a short label the agent writes for what it is working on (falling back to the repo or folder name), and its current state: +## Support -| What you see | What it means | -| --- | --- | -| A spinner | Working. Hovering names the tool in flight and how long it has been running | -| Waiting for approval | The session is blocked on a permission it needs from you | -| Agent asked a question | The session is blocked on an answer from you | -| Waiting for your next prompt | Idle, with nothing in flight | -| Session finished | The session ended normally | -| Process ended unexpectedly | The session died before it finished | +| | Support | Notes | +| --- | --- | --- | +| Claude Code | ✅ Supported | | +| Codex | ✅ Supported | Needs 0.138.0 or newer | +| macOS | ✅ Supported | Apple silicon and Intel | +| Linux | ✅ Supported | x86_64 and arm64, on glibc and musl | +| Windows | ❌ Not supported | | -The plan row above lights up while any of its sessions is working or waiting on you, so a collapsed sidebar still tells you where things stand. Hovering a row also names the machine it is running on, which matters once you have more than one. +Using something else? Every other agent can [connect the MCP server by hand](/plans/install/index). Want first-class support for a harness? [Tell us which one](https://tally.so/r/wQW0x8). -Rows are honest about what they can see. If a machine stops reporting, or your own browser goes offline, the row dims and drops its live claims rather than showing a stale spinner. +## How it works -## What your agent does differently +Your agent emits lifecycle events as it works — a session starting, a tool running, a prompt landing, a session ending. Ref reads those events to map each session to the plans it touches, and to report what that session is doing right now. That mapping is what puts a session in your sidebar, and those events are what keep its state current. -Every connected session starts by asking Ref how to handle your request, and the answer routes the work into one of a few shapes: - -- **Plan** — you should decide something before work starts. The agent drafts a plan and asks you to review it before it builds. -- **Investigation** — you want to understand something. The digging lands as a document with a link, instead of terminal output that scrolls away. -- **Receipt** — the path was already clear. The agent does the work, then records what it did. - -Genuinely small asks are still answered in chat with no document at all. That is a normal outcome, not a failure. - -The shape is judged by the decisions involved, not by the size of the change. A mechanical edit across thirty files is a receipt; a one-line change that settles a non-obvious design call is a plan. - -## Plan review and the wait - -When the agent drafts a plan, it genuinely stops and waits for you. +## Your sessions in Ref Plans -The review request opens in your browser as a full-screen ask: which agent is asking, and its note on what it wants reviewed. **Start review** takes you into the plan, where you comment inline and then choose **Approve**, **Request changes**, or **Comment**. In the sidebar, the request reads *waiting for your feedback…* for as long as the agent is holding. +A session appears in the sidebar under any plan it touches — reading, writing, creating, or reviewing — and stays there while it works. A session working across two plans appears under both. -Requesting changes is a loop, not a stopping point — the agent revises the plan and asks again. On approval it implements, and where the change lands as a pull request, that pull request links back to the plan. +Each row names the agent it is running in, a short label for what it is working on, and its current state: -Reviews from an agent are the same review workflow people use on each other's plans; see [review requests](/plans/collaboration/reviews) for the rest of it. +| | State | What it means | +| --- | --- | --- | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjOGE4YTk0IiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjkiIG9wYWNpdHk9Ii4zIi8+PHBhdGggZD0iTTIxIDEyYTkgOSAwIDAgMC05LTkiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPjwvc3ZnPg==) | **Working** | Hovering names the tool in flight and how long it has run | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYjI2YTAwIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PHBhdGggZD0iTTkuNSA5YTIuNSAyLjUgMCAxIDEgMy42IDIuMjVjLS43LjM1LTEuMS45LTEuMSAxLjc1IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE3IiByPSIxIiBmaWxsPSIjYjI2YTAwIiBzdHJva2U9Im5vbmUiLz48L3N2Zz4=) | **Waiting for approval** | Blocked on a permission it needs from you | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYjI2YTAwIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PHBhdGggZD0iTTkuNSA5YTIuNSAyLjUgMCAxIDEgMy42IDIuMjVjLS43LjM1LTEuMS45LTEuMSAxLjc1IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE3IiByPSIxIiBmaWxsPSIjYjI2YTAwIiBzdHJva2U9Im5vbmUiLz48L3N2Zz4=) | **Agent asked a question** | Blocked on an answer from you | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0iIzhhOGE5NCI+PGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iNiIvPjwvc3ZnPg==) | **Waiting for your next prompt** | Idle, nothing in flight | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMmU3ZDMyIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0yMiAxMS4wOFYxMmExMCAxMCAwIDEgMS01LjkzLTkuMTQiLz48cG9seWxpbmUgcG9pbnRzPSIyMiA0IDEyIDE0LjAxIDkgMTEuMDEiLz48L3N2Zz4=) | **Session finished** | Ended normally | +| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYzYyODI4IiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PGxpbmUgeDE9IjE1IiB5MT0iOSIgeDI9IjkiIHkyPSIxNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGxpbmUgeDE9IjkiIHkxPSI5IiB4Mj0iMTUiIHkyPSIxNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PC9zdmc+) | **Session ended unexpectedly** | Died before it finished | -## Rating the trigger +## Plans your agent creates -When an agent decides on its own to write something up, you get one question about that decision: was creating it the right call, or should it have just answered next time? Your answers tune how eagerly your agents reach for a document in future. The question is only ever about the decision to write — the content is what reviews and comments are for. +**Three kinds of document.** Your agent picks one based on what the work needs: a **plan** when there is a decision to make before work starts, an **investigation** when you want to understand something, or a **receipt** when the path was already clear and it just records what it did. Small asks are answered in chat with no document at all. -## Other agents +**Review requested.** When your agent drafts a plan, it asks you to review it and then waits. The request opens in your browser and names the agent asking. You comment inline, then **Approve**, **Request changes**, or **Comment**. Requesting changes is a loop — the agent revises and asks again. On approval it implements, and the pull request links back to the plan. It is the same workflow as [reviewing a teammate's plan](/plans/collaboration/reviews). -This command covers Claude Code and Codex. For every other agent — Cursor, VS Code, Zed, Windsurf, and the rest — register the MCP server by hand with the [installation guides](/plans/install/index). +**Tell us if it got it wrong.** When an agent decides on its own to write something up, you get one question: was creating it the right call? Your answers tune how eagerly your agents reach for a document next time. From 470f8e25ac9b047aecffca54201be4c3cee8025d Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 15:23:00 +0000 Subject: [PATCH 5/7] Present local-agent support as agent cards plus a platform line The support matrix repeated 'Supported' across four rows to carry five facts. Agents are the question readers arrive with, so they lead as cards; platforms and the Codex version floor fit in one sentence. --- plans/install/local-agent.mdx | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx index f2a813d..de44a24 100644 --- a/plans/install/local-agent.mdx +++ b/plans/install/local-agent.mdx @@ -28,15 +28,14 @@ curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstal ## Support -| | Support | Notes | -| --- | --- | --- | -| Claude Code | ✅ Supported | | -| Codex | ✅ Supported | Needs 0.138.0 or newer | -| macOS | ✅ Supported | Apple silicon and Intel | -| Linux | ✅ Supported | x86_64 and arm64, on glibc and musl | -| Windows | ❌ Not supported | | + + + + + +Runs on **macOS** (Apple silicon and Intel) and **Linux** (x86_64 and arm64, on glibc and musl). Windows is not supported yet. Codex needs 0.138.0 or newer. -Using something else? Every other agent can [connect the MCP server by hand](/plans/install/index). Want first-class support for a harness? [Tell us which one](https://tally.so/r/wQW0x8). +Every other agent can [connect the MCP server by hand](/plans/install/index). Want first-class support for a harness? [Tell us which one](https://tally.so/r/wQW0x8). ## How it works From 92fc4c930980a99cf9cb0c810494d9a8ac6548c4 Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 15:27:26 +0000 Subject: [PATCH 6/7] Serve session-state glyphs as committed SVGs Base64 data URIs were the only ones in the repo, did not preview on GitHub, and left the diff unreviewable. The glyphs also carried no intrinsic size, so an img referencing them fell back to the default replaced-element box instead of rendering at glyph scale. --- images/state-done.svg | 1 + images/state-failed.svg | 1 + images/state-idle.svg | 1 + images/state-question.svg | 1 + images/state-working.svg | 1 + plans/install/local-agent.mdx | 12 ++++++------ 6 files changed, 11 insertions(+), 6 deletions(-) create mode 100644 images/state-done.svg create mode 100644 images/state-failed.svg create mode 100644 images/state-idle.svg create mode 100644 images/state-question.svg create mode 100644 images/state-working.svg diff --git a/images/state-done.svg b/images/state-done.svg new file mode 100644 index 0000000..91a238b --- /dev/null +++ b/images/state-done.svg @@ -0,0 +1 @@ + diff --git a/images/state-failed.svg b/images/state-failed.svg new file mode 100644 index 0000000..4ca7242 --- /dev/null +++ b/images/state-failed.svg @@ -0,0 +1 @@ + diff --git a/images/state-idle.svg b/images/state-idle.svg new file mode 100644 index 0000000..30cc173 --- /dev/null +++ b/images/state-idle.svg @@ -0,0 +1 @@ + diff --git a/images/state-question.svg b/images/state-question.svg new file mode 100644 index 0000000..3eb37c5 --- /dev/null +++ b/images/state-question.svg @@ -0,0 +1 @@ + diff --git a/images/state-working.svg b/images/state-working.svg new file mode 100644 index 0000000..a450322 --- /dev/null +++ b/images/state-working.svg @@ -0,0 +1 @@ + diff --git a/plans/install/local-agent.mdx b/plans/install/local-agent.mdx index de44a24..c967ff7 100644 --- a/plans/install/local-agent.mdx +++ b/plans/install/local-agent.mdx @@ -49,12 +49,12 @@ Each row names the agent it is running in, a short label for what it is working | | State | What it means | | --- | --- | --- | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjOGE4YTk0IiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjkiIG9wYWNpdHk9Ii4zIi8+PHBhdGggZD0iTTIxIDEyYTkgOSAwIDAgMC05LTkiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPjwvc3ZnPg==) | **Working** | Hovering names the tool in flight and how long it has run | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYjI2YTAwIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PHBhdGggZD0iTTkuNSA5YTIuNSAyLjUgMCAxIDEgMy42IDIuMjVjLS43LjM1LTEuMS45LTEuMSAxLjc1IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE3IiByPSIxIiBmaWxsPSIjYjI2YTAwIiBzdHJva2U9Im5vbmUiLz48L3N2Zz4=) | **Waiting for approval** | Blocked on a permission it needs from you | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYjI2YTAwIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PHBhdGggZD0iTTkuNSA5YTIuNSAyLjUgMCAxIDEgMy42IDIuMjVjLS43LjM1LTEuMS45LTEuMSAxLjc1IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48Y2lyY2xlIGN4PSIxMiIgY3k9IjE3IiByPSIxIiBmaWxsPSIjYjI2YTAwIiBzdHJva2U9Im5vbmUiLz48L3N2Zz4=) | **Agent asked a question** | Blocked on an answer from you | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0iIzhhOGE5NCI+PGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iNiIvPjwvc3ZnPg==) | **Waiting for your next prompt** | Idle, nothing in flight | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMmU3ZDMyIiBzdHJva2Utd2lkdGg9IjIiPjxwYXRoIGQ9Ik0yMiAxMS4wOFYxMmExMCAxMCAwIDEgMS01LjkzLTkuMTQiLz48cG9seWxpbmUgcG9pbnRzPSIyMiA0IDEyIDE0LjAxIDkgMTEuMDEiLz48L3N2Zz4=) | **Session finished** | Ended normally | -| ![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjYzYyODI4IiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PGxpbmUgeDE9IjE1IiB5MT0iOSIgeDI9IjkiIHkyPSIxNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PGxpbmUgeDE9IjkiIHkxPSI5IiB4Mj0iMTUiIHkyPSIxNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIi8+PC9zdmc+) | **Session ended unexpectedly** | Died before it finished | +| ![](/images/state-working.svg) | **Working** | Hovering names the tool in flight and how long it has run | +| ![](/images/state-question.svg) | **Waiting for approval** | Blocked on a permission it needs from you | +| ![](/images/state-question.svg) | **Agent asked a question** | Blocked on an answer from you | +| ![](/images/state-idle.svg) | **Waiting for your next prompt** | Idle, nothing in flight | +| ![](/images/state-done.svg) | **Session finished** | Ended normally | +| ![](/images/state-failed.svg) | **Session ended unexpectedly** | Died before it finished | ## Plans your agent creates From 34fb74f632d78ea362c1b61af68b2ced6050ac68 Mon Sep 17 00:00:00 2001 From: TJ Pavlu Date: Wed, 12 Aug 2026 15:32:12 +0000 Subject: [PATCH 7/7] Correct session-state glyphs against the product's own icons Four glyphs now carry the exact geometry of the components the sidebar renders. The running glyph had no SVG to copy: the product renders a CSS border-ring primitive, so it is reproduced as a stroked three-quarter circle at the same relative weight and given the same 0.8s linear spin. Colors were hand-picked hex that matched no token. They now resolve through the real values behind the tone classes, with the dark-mode variants the palette defines. --- images/state-done.svg | 2 +- images/state-failed.svg | 2 +- images/state-idle.svg | 2 +- images/state-question.svg | 2 +- images/state-working.svg | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/images/state-done.svg b/images/state-done.svg index 91a238b..a42db11 100644 --- a/images/state-done.svg +++ b/images/state-done.svg @@ -1 +1 @@ - + diff --git a/images/state-failed.svg b/images/state-failed.svg index 4ca7242..7d41b2d 100644 --- a/images/state-failed.svg +++ b/images/state-failed.svg @@ -1 +1 @@ - + diff --git a/images/state-idle.svg b/images/state-idle.svg index 30cc173..697a205 100644 --- a/images/state-idle.svg +++ b/images/state-idle.svg @@ -1 +1 @@ - + diff --git a/images/state-question.svg b/images/state-question.svg index 3eb37c5..21db5cc 100644 --- a/images/state-question.svg +++ b/images/state-question.svg @@ -1 +1 @@ - + diff --git a/images/state-working.svg b/images/state-working.svg index a450322..e0d7ced 100644 --- a/images/state-working.svg +++ b/images/state-working.svg @@ -1 +1 @@ - +