> ## 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.
# Your First Plan
> Get Ref Plans running at full power in about ten minutes.
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.
Create an account at [plan.ref.tools](https://plan.ref.tools). You'll land on a blank doc — your space to think through what you want to build.
Link a GitHub repo so Ref can read your code and write plans that match your architecture.
1. Go to [ref.tools/resources](https://ref.tools/resources?tab=github)
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.
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 key**
Paste your **Cursor** API key in the Agents settings tab. Get one from [cursor.com/dashboard](https://cursor.com/dashboard?tab=cloud-agents) 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](/plans/workflows/multi-agent).
**Add the MCP server**
Open **cursor.com**, click **MCPs**, click the `+` button and select `Custom MCP` then fill in the form or json as follows.
```json theme={null}
{
"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](https://ref.tools/keys).
**Configure security rules**
Cursor'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](/plans/install/cursor) for details.
**1. Add your API key**
Paste your **Devin** API key in the Agents settings tab. Get one from [app.devin.ai/settings/api-keys](https://app.devin.ai/settings/api-keys).
Installing the Ref Plans MCP server lets Devin read, write, and collaborate on plan documents. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
**Add the MCP server**
In the Devin dashboard, go to [Settings > MCP Marketplace](https://app.devin.ai/settings/mcp-marketplace) and click **Add MCP Server**:
1. **Name:** `ref-plan`
2. **URL:** `https://api.plan.ref.tools/mcp`
3. Add a header `x-ref-api-key` with your API key from [ref.tools/keys](https://ref.tools/keys)
4. Click **Enable**
**Configure security rules**
Devin runs in a sandboxed environment. If your workspace has network restrictions, ensure `api.plan.ref.tools` is allowed. Devin typically permits MCP server URLs automatically once enabled.
See the full [Devin MCP install guide](/plans/install/devin) for details.
**1. Add your API key**
Paste your **Warp API key** (starts with `wk-...`) in the Agents settings tab. In the Warp desktop app, open **Settings > Platform** and create an API key.
* **Environment ID** (optional) — most users with a single environment can leave this blank.
Installing the Ref Plans MCP server lets Warp read, write, and collaborate on plan documents. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
See the [MCP install docs](/plans/install/index) for step-by-step setup. If your environment restricts outbound network access, ensure `api.plan.ref.tools` is allowed.
**1. No API key needed**
These work as **launcher** agents — Ref generates a prompt with embedded webhook commands. You paste it into the agent yourself, and it reports progress back via the webhooks.
Supported launchers:
* Claude Code Web
* Codex (Cloud and Desktop)
* Conductor
* Factory
* Windsurf
* Zed
* GitHub Copilot
* Cursor Desktop
Installing the Ref Plans MCP server lets these agents read, write, and collaborate on plan documents directly. It's optional for single-agent workflows but required for [multi-agent orchestration](/plans/workflows/multi-agent).
See the [MCP install docs](/plans/install/index) for step-by-step setup instructions for your agent.
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](/plans/integrations/overview) for setup.
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.
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.
## What's next?
Learn how to write plans that get great results.
Set up fully automated multi-agent orchestration.
Connect Linear or GitHub issues for richer context.
Using Claude Code, Codex, or another local agent? Install the MCP server to connect them to Ref.