Getting started
Claude Code Kanban shows your Claude Code sessions in the browser. Each session gets a board with Pending, In Progress and Completed columns, a session log, and a list of its subagents. This page takes you from a clean machine to a live board.
Requirements
Section titled “Requirements”- Node.js 20 or later.
- The
claudeCLI. The installer runsclaude --versionfirst. If the command fails, the installer printsclaude CLI not foundand stops. @lydell/node-pty(optional). The embedded terminal needs this package. npm installs it as an optional dependency. If you turn on the terminal and the package does not load, the server printsTerminal unavailable: <reason>. The board works without it.
Install the command
Section titled “Install the command”npm install -g claude-code-kanbanThis installs the claude-code-kanban command. To update it, run the same command again.
Install the integration
Section titled “Install the integration”Run the installer once:
claude-code-kanban --installThe integration is a Claude Code plugin. The installer copies it to <config-dir>/.cck/plugin, registers that folder with claude plugin marketplace add, and then runs claude plugin install claude-code-kanban@claude-code-kanban. If the plugin is already installed, it runs claude plugin update claude-code-kanban instead. The config dir is ~/.claude by default.
The installer asks [Y/n] before it installs the plugin. Press Enter or type any answer other than n to say yes.
The plugin holds the hooks, the skills and a Claude Code mod that records context use, cost and rate limits for each session. The mod needs Claude Code 2.1.287 or later. The installer warns you when your version is older.
If an earlier version of the installer added context-status.sh to your statusLine, the installer removes it and puts back your own command. It keeps all your other settings.
Installer options
Section titled “Installer options”| Option | What it does |
|---|---|
--yes |
With --install, installs the plugin with no prompt. |
--dir=<path> |
Uses another Claude config dir. CLAUDE_CONFIG_DIR does the same. The plugin goes into that dir. |
--uninstall |
Removes the plugin, its marketplace entry and the plugin copy. |
If you use --dir for the install, use the same --dir for --uninstall and when you start the board.
What the hooks give you
Section titled “What the hooks give you”The plugin adds a mod. It runs when a session starts, when a subagent starts or finishes, at the end of each turn, and on each tool call:
- It records subagents, session activity, and context use.
- It shows permission prompts on the board and lets you answer them there.
Without the hooks, the board shows tasks only. You get no agent log and no live activity indicators.
Start the board
Section titled “Start the board”claude-code-kanban --open--open opens your browser after the server starts. The server prints:
Claude Task Kanban running at http://localhost:3541The default port is 3541. To use another port, set the PORT environment variable:
PORT=8080 claude-code-kanbanThe --port flag in --help has no effect. If the port is busy, it prints Port 3541 in use, trying random port... and uses a random free port. The banner shows the port it got.
The server listens on 127.0.0.1 only. For network access and other settings, see Configuration.
Run your first session
Section titled “Run your first session”Run claude as usual, in any project. You do not configure anything per project.
Claude Code writes task files and session transcripts to the config dir. The board watches these files and sends changes to the browser over server-sent events (SSE). Your session appears in the Sessions sidebar. Select it to see its tasks move from Pending to In Progress to Completed.
Turn on the embedded terminal (optional)
Section titled “Turn on the embedded terminal (optional)”When Claude Code Kanban runs by itself, the embedded terminal is off. Start the server with --enable-terminal to run Claude Code sessions inside the board:
claude-code-kanban --enable-terminalThe server then prints a second line:
Terminal enabled - open http://localhost:3541/#t=<token>Open that link. The terminal needs the token in the link. A tab that --open opens has no token, so the terminal does not work in it. See Embedded terminal for details.
Next steps
Section titled “Next steps”- Sessions and the board: the sidebar, filters, and task cards.
- Session log and details: messages, pins, session info and tool stats.
- Subagents: follow the agents a session starts.
- Answer prompts from the board: allow or deny permission asks and answer questions.
- Embedded terminal: start, resume and swap sessions in the browser.
- Session groups: put sessions and projects into named groups.
- Dispatch tasks to other sessions: start a session with a task and get a report back.
- Claude Code plugin skills:
kanbananddispatch, and steering a session with card moves. - Run inside Claude Code Hub: use the board next to the other hub apps.
- Keyboard shortcuts, CLI reference, Configuration and Troubleshooting.