tasks-toolkit

A small, self-contained task tracker (sprints → tasks → subtasks) with a CLI and an MCP server.

Contents

• scripts/ — all tracker code (see table below).

• pyproject.toml — ruff/mypy/pytest configuration.

Related MCP server: aiboard

Installation

From PyPI (recommended)

pipx install tasks-toolkit
# or: uv tool install tasks-toolkit
tasks-init
tasks overview

From source

git clone https://github.com/prachwal/tasks-toolkit.git
cd tasks-toolkit
python -m pip install -e .
tasks-init
tasks overview

Docker

docker build -t tasks-toolkit .
docker run --rm -i -v tasks-data:/data tasks-toolkit

Quick start (from source)

python3 scripts/tasks_init.py          # create tasks/tasks.db
python3 scripts/tasks.py overview      # show sprints
python3 scripts/tasks.py next          # next ready task

Data belongs to the current Git project (the main checkout when invoked from a worktree). Outside Git, it belongs to the current directory. Installed commands never use their installation directory for data. Override the location with TASKS_ROOT:

export TASKS_ROOT=/path/to/data
python3 scripts/tasks.py overview

MCP clients

The tasks-mcp command runs the same stdio server for every client. Set TASKS_ROOT to the absolute path of the project whose tasks you want to manage. It points to the project, not to the toolkit installation. An installed server needs no copy of this source repository. Use an absolute executable path if the client cannot find tasks-mcp on its PATH; command -v tasks-mcp shows it on Unix.

Claude Desktop

Open Settings → Developer → Edit Config, merge this entry into claude_desktop_config.json, and restart the app:

{
  "mcpServers": {
    "tasks": {
      "command": "/absolute/path/to/tasks-mcp",
      "args": [],
      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
    }
  }
}

See the official local-server setup guide for configuration locations and troubleshooting. The toolkit currently uses POSIX file locking (fcntl); run the server on macOS or Linux. The Windows Desktop app needs a launcher into a Linux environment such as WSL, rather than a native Windows Python process.

Claude Code

From your project directory, register a project-scoped stdio server:

claude mcp add --transport stdio --scope project \
  --env TASKS_ROOT="$(pwd)" tasks -- /absolute/path/to/tasks-mcp
claude mcp list

Claude Code saves project-scoped servers to .mcp.json; see its official MCP documentation.

VS Code / GitHub Copilot

Add a server to .vscode/mcp.json:

{
  "servers": {
    "tasks": {
      "type": "stdio",
      "command": "/absolute/path/to/tasks-mcp",
      "args": [],
      "env": {"TASKS_ROOT": "${workspaceFolder}"}
    }
  }
}

See VS Code's MCP configuration reference.

Cursor

Add this to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "tasks": {
      "command": "/absolute/path/to/tasks-mcp",
      "env": {"TASKS_ROOT": "/absolute/path/to/your-project"}
    }
  }
}

OpenCode

Add this entry to opencode.json:

{
  "mcp": {
    "tasks": {
      "type": "local",
      "command": ["/absolute/path/to/tasks-mcp"],
      "enabled": true,
      "environment": {"TASKS_ROOT": "/absolute/path/to/your-project"}
    }
  }
}

See the OpenCode MCP documentation.

Other stdio clients and source installs

Configure any MCP client to launch tasks-mcp, use stdio transport and pass TASKS_ROOT in the server environment. Clients use different JSON keys; adapt one of the examples above to the client's schema. To run from a source checkout, replace the executable with python3 and pass /absolute/path/to/tasks-toolkit/scripts/tasks_mcp.py as its first argument (or use that two-element array for OpenCode's command).

Verified task and sprint execution

Copy .tasks-toolkit.example.json to .tasks-toolkit.json, choose the checks for your project, and commit the configuration. Commands are argument arrays; no shell interpolation is performed. Every configured check must pass. Keep tmp/ and generated tasks/ files in .gitignore, as in this repository.

Runner names and commands are defined entirely in .tasks-toolkit.json:

{
  "default_runner": "coder",
  "runners": {
    "coder": ["python3", "tools/coder_adapter.py"],
    "backup-coder": ["/absolute/path/to/another-adapter"]
  },
  "checks": [["python3", "-m", "pytest", "-q"]],
  "timeout": 120
}

Replace these sample adapter commands with your own. Adapters receive the spec on stdin, edit files in their current working directory, leave changes uncommitted, and return nonzero on failure. There are no built-in providers or model choices. --runner NAME selects any registered adapter; otherwise default_runner is used. If no default is configured, select a runner explicitly. --fallback NAME uses the same registry; none is reserved to disable fallback. Reports and statistics accept any runner name containing letters, digits, underscores and hyphens.

Optional protected_paths adds project-specific files or directories to the built-in protection, for example "protected_paths": ["config/private/", "./credentials.json"]. Entries are relative to the project root; ./ and trailing separators are normalized. Absolute paths and entries containing .. are rejected. Directory entries protect the directory and its descendants. Planner commands resolve the project using the same current-directory, Git-worktree and TASKS_ROOT rules as the tracker; their helper scripts are loaded from the toolkit installation.

When upgrading from 0.1.4, register the command you previously relied on explicitly: implicit provider commands and the implicit default have been removed. Existing checkpoint and report runner names remain valid when registered in the configuration. Changing configuration still invalidates a resume checkpoint's approval fingerprint.

Installed commands are tasks-run and tasks-sprint; from source, the corresponding wrappers are scripts/run-task.sh and scripts/sprint-auto.sh.

Run one task in a clean working tree, with an explicit allowed scope:

tasks-run result \
  --file tmp/tasks/result.md --scope src/ --runner coder

Alternatively, --task-id 1.1 reads scope links from the tracker. The runner checks all actual tracked changes, deletions and untracked files, runs the configured checks and commits only verified changes. Input flags such as checks_green and tracker_done are never evidence. Failures preserve the working tree and write a report to tmp/runs/<name>.result.json. Exit codes: 0 verified, 1 rejected, 3 runner/configuration failure. Optional fallback runs only after a runner failure that left the working tree clean.

For a complete sprint, supply a plan containing sprint (slug, title, goal) and tasks (key, title, scope, spec_name, spec, depends_on). Specs must pass scripts/spec-lint.sh; dependencies reference earlier task keys. An answers file binds the reviewed goal, allowed paths and execution policy. policy.runner overrides the configured default; delegated decisions use the same registry:

{
  "goal_reviewed": true,
  "allowed_scopes": ["src/"],
  "policy": {
    "runner": "coder", "serial": true, "fallback": "none", "retries": 0,
    "push": false, "accept_flags": false, "reset": false, "clean": false
  }
}

Start from a clean main branch:

tasks-sprint --yolo-force \
  --goal "Implement the feature" --run-name feature \
  --answers tmp/plans/feature.answers.json --plan tmp/plans/feature.json

The lifecycle imports the plan, creates a sprint branch and worktree, executes tasks serially, checks the diff against task and approved scopes, and records verified commits in the tracker. Final checks precede a fast-forward into the unchanged approved main; no push is performed. Worktrees and checkpoints remain available for inspection.

Use the same command with --resume to continue a clean checkpoint. Goal, answers, plan, configuration and Git refs must still match. A dirty or unexpectedly advanced worktree requires inspection; it is never reset, cleaned or blindly rerun.

Development checks

python3 -m pip install -e '.[dev]'
bash scripts/test_python_lint.sh
python3 -m pytest -q
bash scripts/test_spec_lint.sh

CI requires lint, type checking, all Python tests, shell tests and distribution builds to pass. VS Code tracker commands are provided in .vscode/tasks.json.

Scripts

Core tracker

Sprint automation

Spec / quality

Tests

Test runners

License

MIT — see LICENSE.