Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ref.tools/llms.txt

Use this file to discover all available pages before exploring further.

In this guide you’ll connect a repo, plan a feature with AI, and hand off the work to coding agents that open PRs for you. It takes about ten minutes. By the end you’ll have a connected repo, a configured agent, and a clear path from rough idea to merged code.
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 follow the setup instructions below
1. Add your API keyPaste your Cursor API key in the Agents settings tab. Get one from cursor.com/dashboard under the Cloud Agents tab.
Installing the Ref Plans MCP server lets Cursor read, write, and collaborate on plan documents. It’s optional for single-agent workflows but required for multi-agent orchestration.Add the MCP serverOpen cursor.com, click MCPs, click the + button and select Custom MCP then fill in the form or json as follows.
{
  "mcpServers": {
    "ref-plan": {
      "type": "http",
      "url": "https://api.plan.ref.tools/mcp",
      "headers": {
        "x-ref-api-key": "YOUR_REF_API_KEY"
      }
    }
  }
}
Replace YOUR_REF_API_KEY with your key from ref.tools/keys.Configure security rulesCursor’s cloud agents run in a sandbox that blocks external network requests by default. You need to allowlist api.plan.ref.tools so the agent can reach the MCP server.In the Cursor dashboard, go to Cloud Agents > Security Rules and add api.plan.ref.tools to the allowed domains.See the full Cursor MCP install guide for details.
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 reads through your indexed repos, finds the patterns that matter — auth flows, DB models, API routes — and turns your notes into concrete tasks with file paths and verification steps. Ask it to split a task, add more detail, or reconsider an approach until the plan feels right.Once the draft is down, use comments to leave feedback or tag teammates for review. Ref can address comments directly, updating the plan based on what you and your team surface.
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.