The plan-of-record for AI coding agents

Your plan
survives the reset.

Capture intent of any size, keep it across sessions, and prove the work is done — readable by you, writable by your agent.

brew install felixgeelhaar/tap/roady

After install, run roady init then roady setup claude-code (or codex, gemini, cursor, …) and your agent starts every session from the plan.

See the actual workflowHow it talks to your AI

Roady Cloud — coming

Hosted MCP, multi-repo dashboard, audit retention, SOC2. CLI stays MIT forever; Cloud is the open-core paid wedge. Drop your email if you want first access.

Opens your mail client — no third-party form backend, no hidden datastore.

See the roadmap for the full open-core boundary.

Built narrowly, on purpose

What Roady is, and is not

Roady is…

  • •The plan-of-record for an AI-paired feature
  • •Memory that survives /clear and session resets
  • •File-based, git-friendly, local-first
  • •MCP-native — every operation is a tool
  • •Drift detection between intent, plan, and code
  • •Free of any model or API key — your agent already has one

Roady is not…

  • •A feature-for-feature Jira / Linear clone
  • •A model wrapper — it runs no inference and holds no key
  • •A chat history layer
  • •A hosted SaaS (today — see ROADMAP)
  • •A code-search or context-stuffing tool

The actual workflow

Spec → plan → execute → detect drift. The same loop whether you write the plan yourself or hand it to an AI agent. Roady doesn't replace your editor or your agent — it gives them durable state to work against.

Docs / Intentroady specroady plan[ Execution happens elsewhere ]roady drift

1. Establish Intent

Analyze your documentation tree. Roady extracts functional features and requirements deterministically.

$ roady spec analyze docs/

2. Derive Action

Decompose features into atomic engineering tasks. Deterministic by default; --ai hands your agent the prompt to do it instead.

$ roady plan generate

3. Detect Drift

Roady monitors your code and state. If your implementation diverges from your plan, you'll know instantly.

$ roady drift detect

Prove done, don't claim it

Each task can carry an acceptance check. roady task check runs it, and verify refuses until it passes with evidence on the record. roady audit trail proves which agent and session touched a task, with hash-chain verification.

$ roady task check task-42
new · v0.11

Nested sub-projects

One repo, many parallel projects under .roady/projects/<name>/. One agent juggles them by passing --project / -P (CLI) or project (MCP).

$ roady -P feature-auth task ready

Why this exists

Three days into a feature, your AI agent has forgotten what was decided yesterday and quietly rewritten the wrong file. Roady is the durable answer to what are we building, what's next, and where did reality diverge from the plan?

Context windows expire

Plan + execution state live in .roady/, not the model's working memory. Survives /clear.

"What's next?" is wasted

roady task ready answers it deterministically from the approved plan. No re-deliberation.

Drift is silent by default

Spec-lock + drift detection make divergence loud and actionable instead of accumulating as debt.

Provenance for every task

Every task carries an Origin (heuristic / ai / human) and a from doc:line citation. AI's choices stay auditable.

Everything else — policy, audit, semantic drift, sub-projects

The five commands you'll actually use

Roady has more commands than this. You will spend most of your time in these.

# 1. Hook your AI agent to Roady (one command per supported tool)
roady setup claude-code     # or codex, gemini, cursor, opencode, copilot, kiro

# 2. Initialise + import your existing docs
roady init my-project
roady spec analyze docs/    # parses markdown, captures source citations

# 3. Generate a plan (deterministic; --ai emits a prompt for your model)
roady plan generate
roady plan approve

# 4. Drive execution from inside your AI editor
/roady-task                  # agent picks the next ready task
# ...agent implements, commits with [roady:task-id] marker...
roady git sync              # state moves forward automatically

# 5. Ask the question that matters
roady drift detect          # has reality diverged from intent?

# 6. Prove it's done
roady task check task-42    # run the task's acceptance check
roady audit trail task-42   # which agent did this, and what proves it

# Bonus — multiple projects per repo (since v0.11)
roady -P feature-auth init --template minimal
roady -P feature-auth task ready

Pick up where you left off

roady next prints a brief for the task in progress, or the one to start next. The agent hooks run it at session start. Zero AI keys, zero signup.

brew install felixgeelhaar/tap/roady && roady init && roady next

Need the full reference?

Capture, plan import, policy, semantic drift, audit verify, sub-projects — everything else lives indocs/advanced.md, grouped by audience.

See all commands
AI-First

Native to Claude Code, Codex, Cursor, Gemini

Your agent can do everything the CLI can — one MCP tool per CLI noun — and reads and writes the same plan-of-record you see in roady status. Approving plans and accepting drift stay with you: your client asks, and nothing happens without your yes. One roady setup command per supported tool installs the MCP server and session hooks.

What the agent calls

roady_next

Brief for the current or next task

roady_capture

Record intent of any size in one write

roady_task

start · complete · check · verify · dispatch · list

roady_plan

import · generate · decompose · approve*

roady_spec

add · explain · review · lock*

roady_drift

detect · semantic · explain · accept*

roady_goal

The roadmap: now · next · later

roady_status

Where the plan stands

roady_query

Question over project state

roady_audit

verify · trail

roady_state · roady_git · roady_policy

get · rebuild* / sync / check

* A decision: it runs only after you confirm it in your client. Fourteen tools, under 4k tokens of your agent's prompt.

Transports

stdio (Claude Code, OpenCode)roady mcp
HTTP--transport http
WebSocket--transport ws
# One-command setup, per supported AI tool
roady setup claude-code
roady setup codex
roady setup gemini
roady setup cursor
roady setup opencode
roady setup copilot
roady setup kiro
// Real interaction inside Claude Code
You:
"What's blocked, and why?"
Tool call:
roady_query { question: "what is blocked?" }
Tool call:
roady_next {}
Claude:
2 blocked tasks. Both depend on auth-signup, which is still in_progress and its acceptance check is failing. Want me to pick it up?

Built for Continuous Planning

Agent hooks

roady setup <agent> wires hooks for Claude Code, Codex, Gemini, Cursor, OpenCode, Copilot, and Kiro, so every session starts from roady next.

Git Sync Loop

Roady parses your commit history for [roady:task-id] markers to automate status transitions.

No model of its own

Roady runs no inference and holds no API key. It assembles the context a model needs and hands it to the agent that already has one.

Evidence-gated verify

A task is verified only when its acceptance check passes and its evidence is on the record.

Shared through git

Task owners, optimistic locking, and a union-mergeable event log, so several people and agents can work one plan.

Go SDK

Public Go client package with typed helpers and a versioned MCP schema.