AgentTasker

A local-first, project-namespaced task tracker built for AI agents and humans working on the same projects. GitHub-Projects-style board (CLI + curses TUI), one SQLite file, no server, no accounts.

• CLI — agenttasker add|ls|show|update|move|done|rm|projects|board|mcp

• TUI — agenttasker board: interactive 6-column kanban for humans

• MCP — agenttasker mcp: stdio MCP server exposing the same board to agents

Statuses

Board order:

Tasks carry a name, description, evidence (analysis gathered pre-task), free-form external blockers, depends_on (hard task deps), affects (informational links), priority (P0…P3, default P2), type (task/feature/bugfix/improvement/chore), tags (workstream labels), an atomic owner claim, and attachments (any binary file, sha256-addressed on disk). Listings sort by status, then priority. A task is ready when it sits in backlog/todo, has no blockers, and all dependencies are done.

Related MCP server: Pigeon MCP Server

Install

python3 -m venv .venv && .venv/bin/pip install -e '.[mcp]'   # [mcp] only needed for the MCP server

Installs two equivalent commands: agenttasker and the short alias atx. Or standalone: pipx install 'agenttasker[mcp]' (once published / from a checkout: pipx install '/path/to/AgentTasker[mcp]').

Use as a Codex skill

scripts/install-codex-skill.sh     # copies SKILL.md into ~/.codex/skills/agenttasker/

Codex loads skills at session start (restart to pick up changes) and needs a real file, not a symlink. Invoke explicitly with $agenttasker, or let Codex select it from the description.

Quick start

agenttasker add "Fix login redirect" -d "Session cookie lost on 302" -e "traced to SameSite=None" --status todo --priority P1 --tag web
agenttasker add "Write regression test" --dep 1
agenttasker ls --ready              # work that can start now, P0s first
agenttasker claim 1 --owner agent-7 # atomically take it (refuses if held)
agenttasker ls --blocked            # stuck work (unfinished deps or external blockers)
agenttasker update 1 --append-evidence "repro confirmed"
agenttasker done 1
agenttasker board                   # TUI for humans (picks a project if none given)
agenttasker list                    # flat table: id title status pri type blocked-by created

Tasks are namespaced per project: the git repo name (or cwd name outside a repo), overridable with --project/-p or $AGENTTASKER_PROJECT. References accept 12 or ProjectName-12.

Storage

One SQLite file, WAL mode:

• default: ~/.local/share/agenttasker/tasks.db

• override: AGENTTASKER_DB=/path/to/tasks.db

• attachments: <db dir>/attachments/, content-addressed by sha256

Coordination, snapshots, attachments

agenttasker claim REF --owner NAME [--force]   # atomic ownership; also sets in_progress
agenttasker release REF [--owner NAME]         # give a task back
agenttasker handoff REF --to NAME [--from ME]  # explicit transfer
agenttasker claims [--stale HOURS]             # who holds what, and what's rotting

agenttasker attach REF FILE                    # any binary (image, zip, json…)
agenttasker attachments REF
agenttasker detach REF ID

agenttasker export [PATH] [-a]                 # portable JSON; attachments base64-embedded
agenttasker import PATH [--mode merge|replace] [--dry-run]

Web UI

agenttasker serve            # http://127.0.0.1:8988 (opens your browser)
agenttasker serve -p PROJ --port 9000 --no-browser

Same features as the TUI plus adding/deleting tasks: board and list views, full field editing, status moves, claim/release, evidence appends, and attachments — click one to open it in a new tab, or upload new files. Polls for changes every 2s. Stdlib only; binds 127.0.0.1 by default.

TUI keys

agenttasker board [-p PROJECT]

Cards are bordered mini-cards: a 2-line inverted title head in the status color, a rule, then a 4-line description/evidence body and a deps/blockers/ready meta line. ! = blocked (red), * = ready, dimmed = done. The board watches the database file and its WAL side files, so changes from the CLI, MCP agents, or other TUI sessions appear within ~0.5s.

MCP

Run the stdio MCP server:

agenttasker mcp

Client config (Claude Desktop / any MCP client):

{
  "mcpServers": {
    "agenttasker": {
      "command": "/path/to/.venv/bin/agenttasker",
      "args": ["mcp"],
      "env": { "AGENTTASKER_DB": "/home/you/.local/share/agenttasker/tasks.db" }
    }
  }
}

The server resolves its project from its working directory (git repo name), or $AGENTTASKER_PROJECT; every tool also takes an explicit project argument. Tools: add_task, get_task, list_tasks (filters: ready/blocked/priority/tag/stale_hours), update_task, set_status, delete_task, list_projects, claim_task, release_task, handoff_task, add_attachment (base64 in), list_attachments, read_attachment (base64 out).

Agents: see SKILL.md for the full working discipline.

Development

python3 -m unittest discover -s tests