It's a Plan CLI
The @itsaplan/runner CLI takes tasks from the It's a Plan tracker and hands them to Claude Code, Codex or opencode locally.
- 2,295 ★ on the repository
- Last commit
- AGPL-3.0
Broad access
Why this level
- Presets start Claude Code and other CLIs without confirmations, so the agent writes files and runs commands on your machine based on task text.
- The agent key sits in `itsaplan-runner.json` and grants access to project tasks.
Install
- Works in
Manual install
npx -y @itsaplan/runnerBefore running, create an external agent in the project, enable MCP and place `itsaplan-runner.json` in the working folder.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Presets start Claude Code and other CLIs without confirmations, so the agent writes files and runs commands on your machine based on task text.
- The agent key sits in `itsaplan-runner.json` and grants access to project tasks.
This is third-party code. Review the repository files before installing.
What it does
It's a Plan is a self-hosted open-source issue tracker where an AI agent counts as a project member with a role, permissions and its own issues. The `@itsaplan/runner` package runs such external agents on your computer. The runner polls the server, finds queued runs and executes each through a coding-agent CLI. Presets exist for Claude Code, Codex, opencode, Antigravity CLI, GitHub Copilot CLI, Pi, Oh My Pi and Mastra Code. A preset sets the flags for unattended work and resumes the session. Instead of a preset you can name your own command, which receives the task on stdin. While a run is in progress, the runner forwards the agent's messages and tool calls to the issue and answers the agent's chat. The agent reads the task and writes its result through the tracker's MCP server, so MCP must be enabled for the project and the server address placed in `.mcp.json`.
Who it is for. Teams that manage work in a self-hosted tracker and want Claude Code or Codex from a local machine to act as an assignee on the board.
Good fit when
- A board task is assigned to an agent and starts in the developer's terminal with no manual handoff.
- Mentioning an agent in a comment should start work under your Claude Code or Codex subscription.
- Several agents with different keys and roles run on one computer.
- An agent behind a firewall takes tasks on an open port.
- The agent's progress should appear in the task itself: messages and tool calls show in the feed.
Not a fit when
- No tracker is deployed: the runner needs a running It's a Plan instance with a URL and an agent key.
- Tasks hold data that must not reach a coding agent on this computer.
- Every agent action must be confirmed by a person: presets start the CLI without confirmations.
Example request
Assign task KEY-42 to the Claude agent on the board and show in the feed which tools it called.Limitations
The runner works only together with an It's a Plan instance: the external agent's key is created in project settings and shown once. MCP is off by default in a project, and without it the agent cannot read the task. Claude Code, Oh My Pi, Mastra Code and Pi read `.mcp.json` from the working folder, while the other CLIs are set up as described in `docs/runner.md`. An installed and signed-in coding-agent CLI remains your responsibility. The key sits in `itsaplan-runner.json` as is.
How to disable. Stop the runner process and delete `itsaplan-runner.json`. Revoke the agent key in project settings and switch MCP off in the same place.
FAQ
How do I start the runner?
Run `npx -y @itsaplan/runner` in the folder with `itsaplan-runner.json`. The file holds the tracker `url`, the agent's `apiKey` and `agent`, for example `claude`. A few seconds later the project shows the agent online.
Which CLIs does the runner support?
Claude Code, Codex, opencode, Antigravity CLI, GitHub Copilot CLI, Pi, Oh My Pi and Mastra Code. Any other CLI connects through your own `command`, and the task arrives on stdin.
How does an external agent differ from an internal one?
An internal agent runs on the tracker server with your model API key. An external one is started by the runner on your machine under your Claude Code, Codex, Copilot CLI or opencode account.
Why enable MCP in the project?
Through the MCP server the agent reads the task and writes the result. It is off by default: enable it in project settings, under MCP Server.
Can several agents run at once?
Yes. The runner drives one agent or several at once, each with its own key and role in the project.
Discussion
No questions or reviews yet.
Related
CLI toolsA CLI that loops Claude Code, Codex, OpenCode and other agents over a task list or PRD until everything is done
A self-hosted control plane for running several agents: task dispatch, run review, spend tracking, connected via MCP, CLI or REST
A self-hosted task board for people and agents: agents claim cards over MCP, and the receipt log cannot be rewritten.
groundcrew hands Linear and Jira tasks to local Claude Code, Codex and Cursor agents, each in its own worktree and sandbox
Yandex Tracker MCP with a report scheduler
Yandex Tracker MCP
A Python Yandex Tracker MCP server with issues, a recurring report scheduler and a SQLite run history
Orchestrator for Claude Code, Codex and Gemini CLI: YAML workflows that loop until your own quality gates pass
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| It's a Plan (this card) | yes | 2,295 | ||
| Paperclip | no | 113,333 | orchestrates a team of agents as a company; here a task board and a runner start Claude Code or Codex on a local machine | |
| Plane MCP Server: project management in Plane | yes | API key | 362 | gives an agent access to Plane issues through MCP; the runner starts the agent for a task itself |
README in short
The tracker puts people and AI agents on one board: kanban, table, cycles, docs and import from Linear, Trello and Plane. The runner is a separate package so the executor works locally.