Roady — the plan-of-record for AI coding agents

Spec, plan, and drift detection that survive context resets. File-based, git-versioned, MCP-native.

"With multiple Claude agents running in parallel, I'd lose track of specs, dependencies, and history." — verbatim from a 2026 Show HN thread.

You pair with Claude Code, Codex, Cursor, or Gemini on a multi-day feature. Three days in, the agent forgets what was decided, rewrites the wrong thing, or quietly drifts off-spec. Roady is the durable layer that holds the answer to what are we building, what's next, and where did reality diverge from the plan? — readable by you and writable by your agent.

See it in 60 seconds

brew trust klarlabs-studio/tap        # first time only
brew install --cask klarlabs-studio/tap/roady     # or: go install github.com/felixgeelhaar/roady/cmd/roady@latest
roady demo                               # scaffolds a sample project + shows drift

Homebrew refuses to load a cask from a third-party tap it has not been told to trust, so the first install of anything from this tap needs brew trust klarlabs-studio/tap once — per machine, not per tool.

The demo creates a roady-demo/ directory with a deliberately drifted spec/plan, runs roady drift detect, and prints the next steps. Zero prerequisites, zero AI keys, zero signup.

The actual workflow

# 1. Hook your agent to Roady (one command per supported tool)
roady setup claude-code           # or claude-desktop, opencode, openai, gemini

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

# 3. Generate a plan (heuristic by default; --ai for richer decomposition)
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?

Status, drift, and progress all show in roady status — including a from doc:line citation for every task so the AI's choices stay auditable.

Live Kanban dashboard

roady dashboard serve --port 3000
open http://localhost:3000/kanban

Five status columns (Backlog · Ready · In Progress · Blocked · Done). Click Start / Complete / Block / Unblock / Reopen or drag cards between columns — every drop is a real task transition. The board reloads within ~200 ms via Server-Sent Events.

/org/kanban merges every project under the repo into a single cross-project board, so one agent juggling many feature streams sees the whole pipeline at once.

For shared / remote use:

roady dashboard serve --port 3000 --auth-token "$(openssl rand -hex 16)"

Token accepted via Authorization: Bearer, Cookie: roady_token, or a one-time ?token=<value> handshake. See docs/dashboard.md.

Nested sub-projects

One repository can host many Roady projects in parallel:

repo/
  .roady/                          # root project
  .roady/projects/feature-auth/    # named sub-project
  .roady/projects/feature-payments/

roady -P feature-auth init --template minimal
roady -P feature-auth task ready
ROADY_PROJECT=feature-auth roady status

Tasks, spec, plan, and state are namespaced per project. Coding agents switch context by passing --project / -P <name> (CLI) or project (MCP). Existing flat .roady/ repos stay unchanged. See docs/rfcs/0001-nested-projects.md.

What Roady is, and is not

Roady is...	Roady is not...
The plan-of-record for an AI-paired feature	A Jira / Linear replacement
Memory that survives /clear and session resets	A chat history layer
File-based, git-friendly, local-first	A hosted SaaS (today)
MCP-native — every operation is a tool	A code-search or context-stuffing tool

See docs/positioning.md for the full positioning, ICP, and category claim.

How it compares

docs/vs.md — opinionated comparison vs Cursor rules, Claude.md, spec-kit, Backlog.md, Linear, GitHub Projects.

Everything else

The headline workflow is intentionally short. Roady supports billing rates, debt scoring, dependency graphs, multi-project org dashboards, plugin syncers, fsnotify watch mode, web dashboards, D3 visualisations, realtime SSE streaming, webhook + Slack notifications, and more — see docs/advanced.md for the full catalogue grouped by audience (solo dev / small team / org).

Roadmap

ROADMAP.md sketches what's next, including the planned Roady Cloud open-core boundary (hosted MCP, multi-repo org dashboard, audit retention, SOC2).

Contributing & license

Contributions welcome — open an issue or PR. MIT License, see LICENSE.

Maintainers: see docs/maintainer-setup.md for the one-time GitHub repo settings the release pipeline depends on (HOMEBREW_TAP_TOKEN secret, GitHub Pages source).

---

Built with cobra, bubbletea, mcp-go, fortify. Domain-driven Go with pkg/domain / pkg/application / internal/infrastructure. Architecture notes in the DDD docs (docs/ddd-insights.md, docs/ddd-refactor-spec.md).