Skip to main content
Thank you for your interest in https://plan.ref.tools!

​
TLDR; What is this?

Ref Plans is a tool for iterating and collaborating on plans for coding agents. It’s a place for context engineering and orchestration. You can research, revise and share plans with other humans for feedback. When a plan is ready, send it to your coding agent of choice (Claude Code, Cursor, Codex, Conductor etc) to implement and that agent will report progress back to Ref. It works great for large or complex plans that go beyond a single commit.

​
How to get started

  1. Signup for Ref https://ref.tools/signup
  2. (Optional but recommended) Connect your GitHub and repos to the index https://ref.tools/resources?tab=github
  3. Visit https://plan.ref.tools to create your first plan.
  4. Iterate on the Plan yourself and with Ref’s agent cloud Claude Code then send it to a coding agent to implement.

​
Quick Demo: My workflow with Plans

Ref Plans is a tool for researching and writing Plans and orchestrating agents to implement them. It take /plan mode beyond single changes to multi-day, multi-PR arches of work. Here’s a quick demo of my coding workflow with Ref Plans. I’m a solo developer so see below for more collaborative workflows.

​
Why use Ref Plans?

  • Write and iterate on multi-PR AI plans that span multiple days - The /plan modes in tools like Claude or Cursor are ephemeral. Commonly I’m building a feature that should be broken down to multiple code changes and I want to write and review one cohesive plan.
  • Lower the mental load of context switching - Managing multiple agents means context switching regularly. Plans provide a clean space to organize and clarify your thinking. When I was managing a bunch of agents ad hoc prior to Plans I felt tense and frazzled and with Ref Plans I felt noticably calmer and more relaxed.
  • Gather context and feedback from other humans - One of the richest sources of context is the wisdom and expertise of our human teammates. Plans lets you send AI plans to teammates for comments and collaborative editing, as easily as any other web-based collaboration tool.
  • Build a rich history of all features and changes - As you and your team do more planning in Ref, you naturally build up an knowledge base that’s easily kept up-to-date of all feature decisions and code changes.
  • Background agents let you work on your phone and close your tabs - Ref runs Claude Code as a background agent in the cloud so you can open the web app on your phone or start an agent and close browser tabs without worrying about losing state.
  • It’s composible, use only the parts you want - Ref’s MCP-first architecture means you can connect use Ref’s built-in Claude Code or buid custom workflows and connect any agent of your choosing.

​
Options and different ways to work

Plans are intended to be flexible to match your workflow but here are a few high-level choices to make. Use Ref as your main driver and orchestrator. Here’s my two-phase workflow which I call Plan and Polish.
  1. Do research and context engineering in Plan. I start with my notes and ask the agent to research the codebase and breakdown in to tasks.
  2. Once a plan feels good, I launch a background or cloud agent to implement it task by task. Sometimes multiple tasks in parallel.
  3. As background agents finish, checkout the branch locallly to test and verify. Ask the background agent for any fixes. Checkout and test other branches while it works.
  4. As tasks are finished, have my local agent open and merge PRs and update the Plan doc based on progress and ways we’ve diverged from the initial plan.

​
Provide context from Linear or Github PRs and Issues

Lots of your context for planning lives outside the codebase, often in Linear or GitHub. Here’s a Linear/GitHub Issues driven version of the same workflow. To connect Linear, click the Linear logo button in the chat panel. To connect GitHub issues and PRs you must connect GitHub and add repos to Ref.
  1. Do research and context engineering in Plan. Add Linear ticket or GitHub issue links and ask the agent to research the codebase and breakdown in to tasks.
  2. Once a plan feels good, launch a background or cloud agent to implement it task by task. Sometimes multiple tasks in parallel.
  3. As background agents finish, checkout the branch locallly to test and verify. Ask the background agent for any fixes. Checkout and test other branches while it works.
  4. As tasks are finished, have my local agent open and merge PRs and update the Plan doc based on progress and ways we’ve diverged from the initial plan.
  5. Have the Ref agent update Linear and GitHub based on progress.

​
Connect to the MCP and do planning locally

If you prefer not to have Ref index your codebase or are out of Ref credits and don’t want to buy more, you can still use Ref to manage and iterate on your Plans. The MCP server provides all the same tools to any agent of your choosing.

​
Claude Code /plan hook

If you have the perfect local Claude Code setup and you just want to collaborate on Plans more easily, we got you! Install is as simple as: 
curl -fsSL https://api.plan.ref.tools/plugins/install/ref-plan-hook | bash
Note: if you are at the limit number of plans, the hook will fail silently.

​
Working with a Team

There are a few ways Ref Plans get better with teams:
  • Share and comment on each others plans.
  • As a manager or lead, connect the MCP server and have you agent review active and recently finished plans to understand your team’s state.

​
Enabling agent progress reporting

When sending a plan to an agent, Ref will include instructions for how that agent can report progress. Settings for this are available in the Webhooks tab. If you are running a cloud agent in a sandboxed environment with limited network access (eg. Claude Code Web), make sure to update your Cloud Environment to allow network access to https://api.plan.ref.tools

​
New tiers and prices

This new launch comes with an update to Ref’s pricing. Since Ref credits can now be used for AI generation, we’re adding tiers with more credits at discounted prices for heavy users. There will be no price changes to existing subscriptions. Existing Basic and Team subscriptions will continue to get 1000 credits for $9/mo and will have Free tier limits for indexing and Plans. Extra usage now costs $10 per 1000 credits.

​
Roadmap

  • WYSIWYG Editor - There is so much work I’d like to do to make the editor experience better. The highest priority is a beautiful WYSIWYG editor.
  • MCP Client - You should be able to connect other MCP servers to Ref’s background agent.
  • Main app integation - Plans is almost an entirely separate app from the classic Ref MCP server. It needs to be integrated and included in landing pages and docs etc
  • Custom HTTP Endpoint Agents - I’d like to make it easier to connect to any agent platform.
Let me know what else should be on there!

​
Questions?

Email: matt@ref.tools Discord: https://discord.gg/dUuz5V2TM3 (tag @mjd)