Skip to main content
Get Ref Plans running at full power in about ten minutes.
1

Sign up

Create an account at plan.ref.tools. You’ll land on a blank doc — your space to think through what you want to build.
The plan editor immediately after creating a new plan — empty document titled 'Untitled Plan', the chat panel on the right with quick actions, and a banner prompting you to connect GitHub.
2

Connect your codebase

Link a GitHub repo so Ref can read your code and write plans that match your architecture.
  1. Go to ref.tools/resources
  2. Click Connect GitHub and authorize Ref
  3. Select the repos you want to index and click Add to Ref
Once indexed, Ref can read files, find existing patterns, and reference them when structuring your tasks.
The Your Resources page with the Repos tab selected, showing a list of GitHub repositories with branch selectors and 'Add to Ref' buttons.
3

Pick a coding agent

Choose which coding agent Ref should use to implement your tasks.
  1. Open Settings (gear icon)
  2. Click the Agents tab
  3. Select an agent and enter its API key (or follow the launcher flow for agents that don’t use one)
Paste your Cursor API key. Get one from cursor.com/dashboard under the Cloud Agents tab.
The Agents settings tab configured for Cursor — API key entered, repo and branch selectors visible.
Giving agents access to your plans via MCP — Cloud agents (Cursor, Devin) are launched and tracked automatically via their API keys — they don’t need MCP access for basic task execution. However, if you want an agent to read, write, or collaborate on plan documents, or message other agents, you can install the Ref Plans MCP server in that agent’s environment. This is optional for single-agent workflows but required for multi-agent orchestration.
4

Write down what you're working on

No need for perfect formatting — just get your ideas down:
  • A rough description of the feature or bug
  • Links to a Linear ticket or GitHub issue
  • A schema, API shape, or data model
  • Bullet points, stream of consciousness, whatever gets it across
This is your thinking space. Get everything important out of your head and onto the page.If you want to pull in context from Linear, Asana, or GitHub Issues, you’ll need to connect those first — see the Integrations guide for setup.
5

Build the plan with Ref

Open the chat panel and ask Ref to turn your notes into tasks. For example:
Research the codebase and break this into tasks with
implementation steps and verification criteria.
Ref will:
  • Read relevant files from your indexed repos
  • Identify existing patterns (auth, DB models, API routes)
  • Structure your notes into tasks with file paths and verification steps
Go back and forth — ask it to split a task, add detail, or reconsider an approach. Use comments to leave notes for yourself or teammates.
Split view showing rough notes in the plan editor on the left, and the chat panel on the right where Ref is researching the codebase and writing tasks.

A comment thread on a task — the author leaving feedback, and the chat panel showing Ref addressing the comment and updating the plan.
6

Ship it

When your tasks are ready, tell Ref to start implementing. You can pick specific tasks or hand off the whole plan:
Implement tasks 1-3.

Implement the plan.
Ref spins up a separate coding agent for each task, pre-loaded with the task details, file references, and repo context. Multiple tasks run in parallel, each on its own branch.You can keep working while implementation runs. Progress flows back automatically — watch status updates come in, and continue refining upcoming tasks.When a task finishes, a PR appears directly in your plan. You can provide higher-level feedback as work progresses, or enable auto-merge to let Ref review and merge PRs on your behalf.
Manage multiple agents directly from Ref.

​
What’s next?

Best Practices

Learn how to write plans that get great results.

Multi-Agent Orchestration

Set up fully automated multi-agent orchestration.

Integrations

Connect Linear or GitHub issues for richer context.

Local Agents

Using Claude Code, Codex, or another local agent? Install the MCP server to connect them to Ref.