PlanDB: a local-first issue tracker for Claude Code and other coding agents

The problem PlanDB solves: agents that plan at machine speed

The README frames the target user directly: Linear and Jira were built for humans planning at human speed, while agents decompose tasks mid-flight, parallelize across branches, and abandon whole subtrees when an approach fails. The failure modes it names are concrete. Agents start coding before the schema exists, duplicate each other's work, and forget everything between sessions. That is a planning-state problem, not a model-quality problem, and the tool is a place to keep the plan.

It is aimed at people running coding agents rather than at project managers. The installer supports Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Windsurf and Aider, and the README describes the result as giving every agent its own Linear workspace in the form of a single binary. Everything lives in SQLite on the machine, so there is no account, no cloud dependency and no server to operate for the default path.

Compound graph, not a flat list: how the plan is stored

The central design choice is the data model. Most trackers give you a list or a tree. PlanDB stores a compound graph: tasks contain subtasks to any depth, like folders, and dependencies connect tasks across those boundaries, like symlinks. The README's example is a Build API subtask inside Backend depending directly on Define Schema inside Database. That is what lets an agent see which pieces are independent and run them at once.

Mutation is a first-class operation. split turns a stuck task into three parallel subtasks, insert adds a missed step between two existing tasks and rewires dependencies automatically, and pivot replaces an entire subtree when an approach fails. The README calls the plan a living hypothesis rather than a static spec, which is the honest way to describe it: the graph is expected to change while work is in progress.

Claiming is atomic. plandb go is documented as using atomic operations so two agents cannot claim the same task, with no locks and no races. The README also lists critical-path analysis for the longest dependency chain and bottlenecks for what blocks the most downstream work. Context entries recorded with plandb context are surfaced later through BM25 when a related task is claimed, which is how knowledge is meant to move between agents and sessions without anyone passing it along by hand.

Installing PlanDB and running a first plan with Claude Code

The README gives one install command. The installer downloads the binary and auto-configures supported agents with planning instructions, and the README states it can be re-run to update because it is idempotent.

curl -fsSL https://agentfield.ai/plandb/install | bash

Variants are documented for silent configuration of every detected framework and for a binary-only install with no framework config.

curl -fsSL https://agentfield.ai/plandb/install | bash -s -- --all
curl -fsSL https://agentfield.ai/plandb/install | bash -s -- --binary-only
cargo install --path .

The README's table says Claude Code gets a rules file at ~/.claude/rules/plandb.md plus a skill directory at ~/.claude/skills/plandb/, which is what makes the /plandb command available. Other frameworks are configured through their own instruction files: ~/.codex/AGENTS.override.md for Codex and ~/.gemini/GEMINI.md for Gemini CLI. Cursor is the exception: its setup is manual, and the installer prints instructions to paste into Cursor Settings under General, Rules for AI.

The first real use is a four-task plan with explicit dependencies. The README shows this sequence, where each add takes an alias, a kind, a description and one or more --dep references to earlier aliases.

plandb init "auth-system"
plandb add "Design schema" --as schema --kind research \
  --description "Define user/session tables, auth flows, token format"
plandb add "Build API" --as api --kind code --dep t-schema \
  --description "Implement endpoints: register, login, refresh, logout"
plandb add "Write tests" --as tests --kind test --dep t-schema \
  --description "Integration tests for all auth endpoints"
plandb add "Deploy" --as deploy --kind shell --dep t-api --dep t-tests \
  --description "Docker build, push, deploy to staging"
plandb go

After that, plandb go claims the first ready task. In this graph only Design schema is unblocked, so it is the one claimed. Once it completes, Build API and Write tests are both ready and can run in parallel, while Deploy waits on both. The README recommends driving the same flow from the agent itself, either with the /plandb skill in Claude Code or with a plain prompt such as "Use plandb to plan and build a CLI todo app", and says the agent then tracks progress with plandb go and plandb done --next. plandb watch opens a terminal dashboard that refreshes as tasks complete.

Where PlanDB stops being the right tool

The README does not document rollback for plandb pivot, and it does not describe what happens to context entries attached to a subtree that is discarded. If an agent pivots a large branch, treat the old context as unverified until you check it.

The version story needs attention before adoption. Cargo.toml declares version 0.1.0, while the newest release listed is v0.2.1 from 2026-05-05, with v0.2.0 and v0.1.27 both dated 2026-03-26. Those do not line up, so the packaged metadata lags the tagged releases. The last push to the repository was on 2026-05-05, which is more than four months before the date of writing; that is not a dead project, but it is not a fast-moving one either.

The bigger boundary is audience. PlanDB is not a replacement for Linear or Jira in front of people. There are no sprints, assignees, boards or reporting described in the README, and the value it claims comes from machine-speed replanning. A human team that needs status meetings will find the CLI surface thin. There is also an operational cost the README understates: the default install path pipes a remote script into bash, and the source path requires Rust 1.75 or newer according to Cargo.toml. In an environment where neither is acceptable, PlanDB has no documented path in.

Compared with an MCP task server or plain plan files

The obvious alternative is a general MCP task or memory server, or simply a plan file the agent reads and rewrites. The difference in approach is the execution model. A plan file is a document: the agent reads it, edits it, and consistency depends on the agent. PlanDB puts the plan behind atomic operations in SQLite, so claiming is a transaction rather than a convention, and two agents running at once cannot both take the same task.

The second difference is dependency structure. A markdown checklist is flat, and ordering lives in the agent's head. PlanDB stores cross-boundary dependencies and can compute the longest dependency chain and the tasks that block the most downstream work, which is what makes parallel dispatch a query rather than a judgement call. The third is retrieval. Context recorded during work is indexed and resurfaced by BM25 when a related task is claimed, so a discovery made in one session can reach a different agent later. A plan file cannot do that on its own.

The trade-off is that PlanDB is one more process in the loop. If a single agent works a short linear task, the graph is overhead, and a plan file is enough.

Licence and upgrade cost for PlanDB

PlanDB is Apache-2.0, declared in Cargo.toml and shipped as a LICENSE file at the repository root. That is a permissive licence with an explicit patent grant, and it is compatible with commercial use; the usual Apache-2.0 obligations around notices and attribution still apply, and this is not legal advice. Because the default install is a binary rather than a library you link, the practical licence exposure is low.

Upgrade cost is mostly the installer. The README says re-running the install command updates the tool and is idempotent, so the binary and the agent configuration move together. That also means an upgrade can rewrite files under ~/.claude/, ~/.codex/ and ~/.gemini/, which is worth knowing if you keep your own edits in those instruction files. The README points to CHANGELOG.md for what changed between releases; given the version gap between Cargo.toml and the v0.2.1 tag, read it before upgrading rather than assuming a patch-level change. Source builds pin to Rust 1.75 or newer, and the release profile uses opt-level "z" with LTO and stripped symbols, so expect a small binary rather than a fast-building one.

Editorial conclusion

Adopt PlanDB if you run Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf or Aider on work that decomposes into dependent tasks, and you want that structure on disk rather than in a chat transcript. Skip it if a human team needs boards, assignees and reporting, or if you cannot run a curl installer or a Rust build. Before committing, check the CHANGELOG.md for the jump between the Cargo.toml version 0.1.0 and release v0.2.1, and confirm the installer supports your framework in the table in the README.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes