# 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).

```text
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](https://docs.anthropic.com/en/docs/mcp) 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.

## Architecture

```text
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](https://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:

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

Install the frontend dependencies once:

```bash
npm install
```

Start the API and UI together:

```bash
npm run local
```

Open [http://localhost:3000](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:

```bash
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:

```bash
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:

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

Verify it:

```bash
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:

```json
{
  "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](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:

```text
Show my open Agent Task List tasks for Website Redesign.
```

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

```text
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:

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

## Data and configuration

Override the database location when needed:

```bash
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:

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

## Development

```bash
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.