TaskTracker

EN | RU | CN

TaskTracker: a board Claude Code and Codex fill in for themselves 🗂️

<p class="badges"> <img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757?logo=anthropic&logoColor=white" alt="Claude Code plugin"> <img src="https://img.shields.io/badge/MCP-HTTP%20server-111111" alt="MCP HTTP server"> <img src="https://img.shields.io/badge/docker-compose-2496ED?logo=docker&logoColor=white" alt="Docker Compose"> <img src="https://img.shields.io/badge/storage-SQLite-003B57?logo=sqlite&logoColor=white" alt="SQLite"> <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"> </p>

Claude Code keeps a task list while it works - and that list dies with the session.<br> TaskTracker mirrors it onto a board per project, and gives Claude MCP tools to read the queue back next time.<br> The board is a web panel: projects, then three columns - QUEUE, IN PROGRESS, DONE.<br> A project appears the moment you start Claude in it; the panel refreshes itself.

Codex is supported too: its native plan is mirrored through lifecycle hooks, and the same MCP server reads the queue. See Codex setup.

<img src="docs/board.png" width="800" alt="One project's board: three columns, drag and drop between them"> <img src="docs/projects.png" width="800" alt="The projects table: each project with its QUEUE, IN PROGRESS and DONE counts">

How it runs - a real Claude Code session, the panel never reloaded: Claude plans the work and the tasks land in QUEUE (1), each one moves to IN PROGRESS before Claude starts on it (2), and to DONE when it is finished (3).

<img src="docs/process.png" width="800" alt="Three moments of one session: three tasks in QUEUE, the first in IN PROGRESS, all three in DONE">

Click a task - a card on the board or a row in the table - to open it: edit the title and the detail, change the status, or delete it. Cards can also be dragged between columns.

<img src="docs/dialog.png" width="560" alt="The task dialog: title, detail, status, and DELETE, CANCEL and SAVE">

🚀 Quick start

1. Start the board - the panel and the MCP server, in one container:

cd TaskTracker
docker compose up -d

The panel is at http://127.0.0.1:8787. Where the cards come from is set in .env - see below.

2. Install the Claude Code plugin - once, from the same directory; it works in every project. For Codex, use the Codex steps instead:

claude plugin marketplace add ./
claude plugin install tasktracker@tasktracker

3. Restart Claude Code. From then on every project you open Claude in is on the board, and its cards follow Claude's work.

4. Check it works - in Claude Code:

• /mcp - plugin:tasktracker:tasktracker is listed as connected.
• /tasktracker:tasks - Claude reports this project's queue (empty on a new board).
• Ask Claude to "make a todo list of three steps for …", then open http://127.0.0.1:8787 - the project is there, with the three cards marked TODO.

Updating - after pulling changes, from the checkout:

docker compose up -d --build
claude plugin marketplace update tasktracker
claude plugin uninstall tasktracker@tasktracker
claude plugin install tasktracker@tasktracker

Then restart Claude Code.

🤖 Codex

After starting the board, run these from the checkout (Python 3.11+ on the host; Linux, macOS or WSL):

codex mcp add tasktracker --url http://127.0.0.1:8787/mcp
python3 hooks/install-codex.py

Restart Codex, open /hooks and review and trust the TaskTracker hooks; Codex requires that review before they run. Check the connection in /mcp. The installer keeps your other hooks and backs up a changed hooks.json.

With TASKTRACKER_CARDS=claude (the existing default, shared by both clients), Codex's update_plan steps become CODEX cards and follow their native status. With TASKTRACKER_CARDS=prompts, a prompt is in IN PROGRESS until Codex stops, then DONE. Claude and Codex share the board; their sessions remain separate.

After updates, rebuild the container, rerun the installer and restart Codex. Full setup, checks and limitations.

🃏 Where the cards come from

One setting, TASKTRACKER_CARDS in .env beside docker-compose.yml (copy .env.example). After changing it, rebuild and restart Claude Code.

TASKTRACKER_CARDS=claude    # the default
TASKTRACKER_CARDS=prompts

• claude - the cards are Claude's own tasks. The plugin tells Claude, at the start of every session and again with every prompt, to plan any work of more than one step as tasks and keep their status current; each task is a card, marked TODO, that moves as Claude works. If Claude still does work - Bash, Edit, Write - without a single task, the prompt itself lands in DONE, marked PROMPT. If it tracked the work with one of the tracker's MCP tasks instead, the prompt is glued to that task: one card, marked MCP + PROMPT, with the prompt under MERGED CARDS. A question answered by reading makes no card.
• prompts - every prompt you send is a card, marked PROMPT: its first line is the title, the whole prompt the detail. It is in IN PROGRESS while Claude answers and in DONE when it stops. Slash commands make no card, and Claude's own tasks are not shown.

<img src="docs/prompts.png" width="800" alt="Prompts mode: three prompts as cards, one in IN PROGRESS and two in DONE">

🔗 Duplicate cards

Claude/Codex compares card meaning through tasks_review and applies its decisions with tasks_reconcile. For example, a prompt asking for version 0.0.2 and an MCP task recording that release can become one card. Different subtasks, releases and uncertain matches stay separate.

After work, the Stop hook requests one review when cards from different sources have changed. It includes DONE cards. The surviving card shows all source badges; open MERGED CARDS in its dialog to read the originals and the reason. Repeated hooks resolve to that same card. A completed prompt never completes an unfinished task just because they were merged.

For existing duplicates, run /tasktracker:reconcile in Claude Code, or ask Codex to reconcile this project's TaskTracker cards. Update the container and installed hooks first. How the LLM review works.

🧪 Development

pip install -e '.[dev]'
pre-commit install              # ruff and the test suite before every commit
pytest --cov                    # the suite, with coverage and the lines it missed

ruff check and ruff format keep the style; the settings are in pyproject.toml. GitHub Actions (.github/workflows/ci.yml) runs ruff and pytest --cov on Python 3.11 and 3.12 for every pull request and every push to main.

The panel has no build step: src/tasktracker/www is served as it is, and every library is vendored there. The version stays 0.0.4 between releases - see CLAUDE.md for why, and for how a change reaches an installed plugin.

License

MIT. Montserrat is under the SIL Open Font License.