GitHub

Planban documentation

Planban documentation explains how to install Planban in Codex and Claude Code, how its board models work as Items, Groups, Status, Specs and Plans, and how agents use its CLI and MCP tools to keep that board current.

Planban is a local-first, agent-native Kanban board. Your agent keeps the plan current as it works, and you see the whole project at a glance. Board state stays on your machine.

Where do I start?

Install Planban in the host you use, then set up Planban for a project. The pages after that explain how the board works and how agents change it. Every page is listed here in reading order.

Get started

  • Install Planban in CodexInstall Planban as a Codex plugin: what you need, the one-prompt install, manual commands for macOS, Linux and Windows, a local clone, and how to check it works.
  • Install Planban in Claude CodeInstall Planban as a Claude Code plugin: what you need, the one-prompt install, the manual commands, a local clone, and how to check the plugin and MCP server work.
  • Use Planban from other MCP hostsRun Planban's MCP server from any host that supports local stdio MCP servers: what the host gets, how to configure it, and how the agent returns the board link.
  • Set up Planban for a projectCreate a Planban board for a repository: what set-up writes, how the board id is chosen, the tutorial and Demo board, importing existing plans, and refreshing guidance.

Use Planban

  • Planban commands in Codex and Claude CodeThe six Planban commands, how to type them in Codex and Claude Code, what each one does, the plain prompts that work instead, and what the reply contains.
  • Items and GroupsWhat Planban Items and Groups are, when to create a Group, how Items move into and out of Groups, why Groups do not nest, and what Group progress shows.
  • Status and priorityPlanban's five statuses, what priority means, how to reorder work, who marks work Complete, what archiving does, and what a blocked-by link records.
  • Specs, Plans and next actionsWhat goes on a Planban card, what a Spec and a Plan hold, when an Item gets a Plan, what makes a good next action, where the files live, and how agents edit them safely.
  • How agents work with the boardThe Planban protocol agents follow: when they change an Item's Status, why finished work waits for your review, what they report, and how new sessions find the board.

Reference

  • Planban CLI referenceEvery Planban CLI command in v1.1.6: how to run the CLI from your marketplace folder, the shared options, and the commands for boards, Items, documents, updates and recovery.
  • Planban MCP tools referenceEvery Planban MCP tool in v1.1.6: the 13 default tools, their inputs and results, the board link every result carries, and the admin and recovery profiles.
  • Where Planban stores your dataWhat Planban keeps in your project's .planban/ folder and in ~/.planban on your machine, whether to commit it, how much history it keeps, and what it never uploads.
  • Planban in git worktreesHow Planban finds the right board when an agent session runs in a linked git worktree, which cwd to pass, how to tell it happened, and when it does not apply.

Maintain

  • Update PlanbanHow Planban tells you an update is ready, what the board's update buttons do in Codex, the commands to update in Codex and Claude Code, and what the update check sends.
  • Troubleshooting PlanbanFixes for common Planban problems: missing tools, runtime not found, a project that is not set up, a busy port, the launch log, the board not opening, and stale plugins.

Changelog

  • Planban changelogEvery public Planban release, newest first: what changed in the latest version, earlier releases back to v1.0.0, and how to update.
  • Planban v1.1.6Planban v1.1.6 adds Claude Code desktop support, puts the board link in MCP results for every host, and resolves boards from linked git worktrees.

Which host should I install Planban in?

Install Planban in each host you use. Each install is separate, but all installs on one device share the same boards, so a board you create from Codex is the same board you open from Claude Code.

  • Codex desktop. The board opens in the Codex in-app browser, and you open it with /pb or /planban. See Install Planban in Codex.
  • Claude Code desktop. The board opens in the Claude Code browser pane, and the commands carry the plugin prefix, as in /planban:pb. See Install Planban in Claude Code.
  • Other MCP hosts. Any host that can run a local stdio MCP server gets the same tools without commands, and the board opens as a link. See Use Planban from other MCP hosts.

Which version do these docs describe?

These docs describe Planban v1.1.6, the current release. Planban is open source under the MIT licence. It is not published to npm: you install it through the Codex or Claude Code plugin marketplace from GitHub.

Each page ends with the version it applies to and the date it was last updated. The changelog lists every release.