claude-task-tracker

claude-task-tracker

Passive task tracking for Claude Code. Observes your conversations via hooks, uses AI to infer task creation/progress/completion, and maintains a global task database with a web dashboard.

No manual input needed — tasks are created and updated automatically as you work.

How it works

Claude Code session
  ├── SessionStart hook → injects active tasks as context
  ├── UserPromptSubmit hook → sends transcript to worker for analysis
  └── Stop hook → final analysis of completed session

Worker (persistent background process)
  ├── Reads conversation transcript (JSONL)
  ├── Summarizes new messages since last analysis
  ├── Sends to Claude (via Agent SDK) for task inference
  ├── Updates global task database
  └── Serves web dashboard

Tasks are global — not tied to a specific folder or session. The AI recognizes when different sessions work on the same feature and links them together.

Example: what gets tracked

Suppose you work across several Claude Code sessions on different projects. The tracker observes your conversations and automatically builds a task list like this:

# Active Tasks

- #2 Add user authentication to web app (in_progress) [backend, auth]
    - #5  Set up OAuth2 provider integration (done)
    - #6  Build login/signup UI components (in_progress)
    - #7  Add session management middleware (open)
    - #8  Write auth integration tests (open)
- #3 Migrate database from Postgres to SQLite (open) [backend, db]
- #4 Fix responsive layout on mobile dashboard (in_progress) [frontend]
    - #9  Debug sidebar collapse on small screens (done)
    - #10 Fix chart overflow in analytics view (in_progress)

Notice:

• Automatic subtask creation — large tasks like "Add user authentication" get broken into trackable subtasks
• Cross-session linking — work done in /projects/backend/ and /projects/frontend/ both update related tasks
• Status inference — tasks move from open → in_progress → done based on conversation evidence
• No manual input — you never tell the tracker anything; it observes your Claude Code transcripts

Installation

Prerequisites

• Node.js >= 22 (uses built-in node:sqlite)
• Claude Code installed
• The @anthropic-ai/claude-agent-sdk must be available (automatically found if any globally-installed package depends on it)

Install via Claude Code plugins (recommended)

# Add the marketplace
claude plugins marketplace add github:ProblemFactory/claude-task-tracker

# Install the plugin
claude plugins install claude-task-tracker@ProblemFactory

That's it. Hooks are registered automatically. The worker starts on your next Claude Code session.

Verify

claude plugins list

Uninstall

claude plugins uninstall claude-task-tracker@ProblemFactory
claude plugins marketplace remove ProblemFactory

Usage

Once installed, the tracker runs silently in the background. Open the dashboard to see your tasks:

http://localhost:37778

Dashboard Features

• Task list grouped by status (In Progress, Open, Blocked, Done)
• Filter by status, priority, project/tag
• Full-text search across task titles and notes
• Activity stream showing recent task changes
• Settings panel (gear icon) for configuring the tracker

Configuration

Settings are stored in ~/.claude/task-tracker/config.json. You can edit this file directly, use environment variables, or configure via the dashboard settings panel.

Config file

{
  "port": 37778,
  "host": "0.0.0.0",
  "model": "sonnet",
  "analysisTimeout": 25000,
  "minDeltaChars": 2000,
  "autoRefreshInterval": 15000
}

Environment variables

Every config key can be overridden with a TASK_TRACKER_ prefix:

TASK_TRACKER_PORT=8080
TASK_TRACKER_MODEL=haiku
TASK_TRACKER_HOST=127.0.0.1

All options

Key	Default	Description
port	37778	Worker HTTP port
host	0.0.0.0	Bind address (0.0.0.0 for LAN, 127.0.0.1 for local)
model	sonnet	Claude model for analysis
analysisTimeout	25000	Max wait for AI response (ms)
maxTurns	1	Max conversation turns for analysis
minDeltaChars	2000	Skip analysis if conversation delta is shorter
minSummaryChars	100	Skip if summarized text is too short
maxPromptChars	12000	Truncate conversation in AI prompt
maxSummaryChars	15000	Max chars for message summarization
recentLinksLimit	50	Session links returned by API
recentSessionsLimit	10	Sessions shown in TASKS.md
recentCompletedLimit	20	Completed tasks shown in TASKS.md
autoRefreshInterval	15000	Dashboard auto-refresh interval (ms)

Architecture