Ticket Tracker

Lightweight ticket tracking for agentic coding sessions. Tickets are managed by LLMs through an MCP server and viewed in a browser-based kanban board.

Usage

npx @eohutson/tickets

This starts both the MCP server (stdio) and the web UI at http://localhost:3000.

All tickets are stored in a single global file at ~/.local/share/ticket-tracker/tickets.json.

Project Prefixes

Create a .tickets file in your project root containing a prefix (e.g., AIP). Tickets will be created as AIP-001, AIP-002, etc. Without a .tickets file, the default prefix is T.

Listing and workable queries only return tickets matching the current project's prefix, so multiple projects share one store without conflicts.

Development

npm install
npm start        # run MCP server + web UI via tsx
npm run ui       # run only the web UI
npm run build    # compile TypeScript to dist/

Ticket Schema

| Field | Type | Description | |--------------------|----------------------------------------------|---------------------------------------| | id | string | Auto-generated (e.g., AIP-001, T-001) | | title | string | Ticket title | | description | string | Ticket description | | status | QUEUED | IN_PROGRESS | DONE | REJECTED | Current status | | priority | 1–5 | 1 = highest, 5 = lowest | | acceptanceCriteria | { description: string, verified: boolean }[] | Testable criteria for completion | | dependsOn | string[] | IDs of tickets that must finish first |

MCP Tools

| Tool | Description | |-----------------|----------------------------------------------------------------------------------| | create_ticket | Create a ticket with title, description, priority, acceptance criteria, deps | | update_ticket | Partial update any field by ticket ID | | get_ticket | Get a single ticket by ID | | list_tickets | List all tickets, optionally filter by status | | delete_ticket | Delete a ticket (fails if other tickets depend on it) | | get_workable | Get QUEUED tickets with all dependencies resolved, optionally sorted by priority |

MCP Configuration

Add to your .mcp.json to use as an MCP server:

{
  "mcpServers": {
    "ticket-tracker": {
      "command": "npx",
      "args": [
        "@eohutson/tickets"
      ]
    }
  }
}

Skills

The manage-tickets skill is automatically installed to ~/.claude/skills/ when the MCP server starts. It activates when you say things like "create a ticket", "what can I work on", or "mark T-001 as done".

Web UI

The kanban board at http://localhost:3000 is read-only and auto-refreshes every 5 seconds. It shows:

• Four columns: QUEUED, IN_PROGRESS, DONE, REJECTED
• Priority badges (color-coded P1–P5)
• Acceptance criteria with verified/unverified indicators
• Dependency status (blocked vs. ready)