Agent Task List

A self-hosted work queue shared by Codex, Claude Code, Claude Desktop, and any other AI client that supports the Model Context Protocol (MCP).

Project
└── Linear ticket
    └── Task

Every agent uses the same MCP tools and SQLite database. The browser UI reads and writes those records through a localhost-only API.

Why MCP

MCP is an open protocol for connecting AI applications to tools and data. Its standard transports include stdio and Streamable HTTP; clients are encouraged to support stdio for local integrations. This project uses stdio, where each AI client launches a lightweight MCP process and all processes share one WAL-mode SQLite database.

This works without tying the task list to a specific model vendor.

Related MCP server: bot-relay-mcp

Architecture

Codex ─────────────┐
Claude Code ───────┤
Claude Desktop ────┼─ stdio MCP processes ─┐
Other MCP clients ─┘                        │
                                           ▼
                                    shared SQLite DB
                                           ▲
Browser UI ───── localhost API ─────────────┘

• Source: github.com/vigneshr-07/agent-task-list

• Database: ~/.local/share/agent-task-list/tasks.sqlite3

• Local API: http://127.0.0.1:4783

• Dashboard: http://localhost:3000

Requirements

• Python 3.10 or newer

• Node.js 22.13 or newer for the dashboard

• An MCP-compatible AI client

Run the dashboard

Clone the repository and enter the project directory:

git clone https://github.com/vigneshr-07/agent-task-list.git
cd agent-task-list

Install the frontend dependencies once:

npm install

Start the API and UI together:

npm run local

Open http://localhost:3000. The MCP server does not require the dashboard to be running; agents can update SQLite directly whenever their client launches the stdio process.

Connect Codex

Register the server in the global Codex configuration:

codex mcp add agent-task-list -- python3 /absolute/path/to/agent-task-list/tasklist.py mcp

Replace /absolute/path/to/agent-task-list with the location where you cloned the repository.

Verify it:

codex mcp get agent-task-list

New Codex CLI, IDE, and desktop sessions load the global MCP registration. Reload MCP servers or restart an existing session if the tools are not visible.

Connect Claude Code

Register it at user scope so every Claude Code project and its agents can access the same task list:

claude mcp add --scope user agent-task-list -- python3 /absolute/path/to/agent-task-list/tasklist.py mcp

Verify it:

claude mcp get agent-task-list

Claude Code documents user-scoped MCP servers as private, cross-project integrations. Project-scoped servers can instead be committed through .mcp.json when a team should share the configuration.

Connect Claude Desktop or another MCP client

Use this standard stdio configuration:

{
  "mcpServers": {
    "agent-task-list": {
      "command": "python3",
      "args": [
        "/absolute/path/to/agent-task-list/tasklist.py",
        "mcp"
      ]
    }
  }
}

The same configuration is available in config/mcp-stdio.example.json. Claude Desktop increasingly packages local servers as desktop extensions, but its local development MCP mode and many other desktop clients accept this standard command-and-arguments shape.

MCP tools

• task_board

• create_project

• create_ticket

• create_task

• list_tasks

• claim_task

• update_task

• update_ticket

Useful prompts include:

Show my open Agent Task List tasks for Website Redesign.

Under project Website Redesign and ticket WEB-123, add a high-priority task to cover the retry path.

Claim task 17 as claude:website-redesign:WEB-123, work on it, and mark it done after the tests pass.

The intended agent workflow is:

Read board → claim task → do work → update progress → mark done

Data and configuration

Override the database location when needed:

AGENT_TASK_LIST_DB=/path/to/tasks.sqlite3 python3 tasklist.py api

LOCAL_CODEX_TASKS_DB remains accepted as a compatibility fallback, but new configurations should use AGENT_TASK_LIST_DB.

To back up the board, stop active writers or use SQLite's backup command against:

~/.local/share/agent-task-list/tasks.sqlite3

Development

python3 -m unittest discover -s tests/python -v
npm test

Boundaries

• Linear tickets are entered manually. Automatic Linear import and two-way synchronization are future work.

• The API is unauthenticated because it binds only to localhost. Do not expose port 4783 to a network.

• Local stdio MCP works only on the machine running the client. Cloud agents need a separately hosted, authenticated Streamable HTTP MCP service.

• Task claims prevent accidental ownership changes, but this MVP does not yet provide leases or stale-claim expiry.