Skip to main content
Custom launchers let external tools open Ref Plans directly. Build a link to https://plan.ref.tools/new, optionally include starting content or a first agent prompt, and send users into a new plan.

​
URL pattern

Use the /new route with optional URL-encoded query parameters:
Both parameters are optional. If you omit both, Ref creates a blank untitled plan, the same as clicking New Plan in the UI.

​
Examples

Create a blank plan:
Create a plan with initial markdown content:
Create a plan with initial content and immediately ask Ref to research it:

​
Worked example: Linear

You can wire this pattern into any tool that can construct a URL. For Linear, add a custom link, automation, or internal workflow that builds a Ref URL from the ticket title and ticket link. For example, start with:
URL-encode those values and append them to /new:
When the user opens the link, Ref creates a new plan with the ticket title and link already in the document. It also sends the prompt as the first chat message, so the plan opens directly into an agent thread researching the ticket. If your automation can run code, build the URL with your platform’s URL encoder instead of hand-encoding strings:

​
Requirements

  • The user must be logged in to plan.ref.tools
  • The new plan is created in the user’s currently selected workspace, whether personal or team
  • Both content and prompt should be URL-encoded before they are added to the link

​
Get help

If you have any issues, please reach out to help@ref.tools. We’re happy to help you get started!