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/images/state-done.svg b/images/state-done.svg new file mode 100644 index 0000000..a42db11 --- /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..7d41b2d --- /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..697a205 --- /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..21db5cc --- /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..e0d7ced --- /dev/null +++ b/images/state-working.svg @@ -0,0 +1 @@ + diff --git a/plans/install/index.mdx b/plans/install/index.mdx index d93b917..6cff6f8 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 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 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..c967ff7 --- /dev/null +++ b/plans/install/local-agent.mdx @@ -0,0 +1,67 @@ +--- +title: "Local agents" +description: "Connect Claude Code and Codex to Ref with one command." +--- + +import GetHelp from '/snippets/get-help.mdx'; + +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 + +``` +curl -fsSL https://api.plan.ref.tools/plugins/install/local-agent | bash +``` + +- 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 + +\* Active sessions may require restart. + +### Uninstall + +``` +curl -fsSL 'https://api.plan.ref.tools/plugins/install/local-agent?mode=uninstall' | bash -s -- --uninstall +``` + +## Support + + + + + + +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. + +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 + +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. + +## Your sessions in Ref Plans + +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. + +Each row names the agent it is running in, a short label for what it is working on, and its current state: + +| | State | What it means | +| --- | --- | --- | +| ![](/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 + +**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. + +**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). + +**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. + +