issuedeck 0.4.0

Local-first issue deck for AI coding agents and human developers

IssueDeck

English | 简体中文

Lighter than Jira. More stable than Markdown.

IssueDeck is a local-first, self-hosted issue deck for small teams and AI coding workflows. It gives multiple projects one shared FastAPI + SQLite tracker, a web dashboard for humans, and MCP tools for coding agents.

Try It in 30 Seconds

Run the latest PyPI release with fake demo data:

uvx issuedeck demo --open

No clone or real project data is needed. The demo creates a local example project and opens the dashboard. Sign in with issuedeck-local-token.

To try the latest unreleased main branch instead:

uvx --from git+https://github.com/xq520mmy/IssueDeck issuedeck demo --open

Why IssueDeck

• Replace project-specific Markdown trackers with one structured source of truth that stays close to code, commits, branches, and releases.
• Give humans and coding agents the same workflow instead of maintaining a dashboard in one place and agent instructions in another.
• Start safely with demo data, then add real project configs when you are ready.

See the screenshot gallery for list, kanban, detail, search, and project creation surfaces. Daily triage shortcuts are documented in Keyboard Shortcuts.

Features

• Agent-ready: MCP tools let coding agents create, update, search, relate, and ship tracked work without scraping Markdown.
• Multi-project: one SQLite DB holds items for any number of projects, keyed by project_key. Each project has its own kinds, statuses, branches, and numeric ID prefix (e.g. FEAT-0001, BUG-0003).
• Full-text search via SQLite FTS5.
• Bidirectional relationships (blocks/blocked_by, related_to).
• External links for GitHub issues, pull requests, commits, and other review context.
• GitHub URL helper to create linked IssueDeck items from issue, pull request, or commit URLs without a full sync engine.
• CSV, JSON, and Markdown task-list import for turning tracker exports, TODO.md, and GitHub checklist items into IssueDeck work items.
• Item activity timeline with automatic lifecycle events and manual comments.
• Signed lifecycle webhooks for downstream automation on create, update, ship, delete, and restore events.
• Built-in dashboard work queues for backlog, active, blocked, ready-to-ship, done, deleted, and recently touched items.
• Project-scoped saved dashboard filters for reusable views such as active bugs, blocked work, release queues, and tag-specific searches.
• Soft delete + restore.
• Ship records with version + commits, queryable by shipped branch.
• Markdown export (one file per item) and changelog rendering.
• Frontmatter migration from existing Markdown trackers.
• Server-rendered dashboard with list, kanban, detail, search, and create/edit flows.
• Keyboard-friendly dashboard triage for search, filters, create, and item focus.
• Dashboard project creation, language switching, and first-run setup checklist.
• MCP tools for coding-agent workflows.

Requirements

• Python 3.11+
• uv
• Docker, optional for container deployment
• Node.js 20+, only needed when changing dashboard styles

Quickstart

Try the latest PyPI release without cloning:

uvx issuedeck demo --open

To try unreleased changes from GitHub:

uvx --from git+https://github.com/xq520mmy/IssueDeck issuedeck demo --open

Start a local dashboard with fake demo data:

uv run issuedeck demo

This creates a local server.toml if one does not exist, applies database migrations, seeds the example project with fake items, and starts the server. Then open http://127.0.0.1:8765/dashboard/example and sign in with issuedeck-local-token.

To open the dashboard automatically:

uv run issuedeck demo --open

Health endpoints:

curl http://127.0.0.1:8765/healthz
curl http://127.0.0.1:8765/readyz

If the first run fails because of a missing uv, an occupied port, a token problem, SQLite migrations, or Docker Compose startup, see the first-run troubleshooting guide.

Dashboard CSS is committed in the repository, so Node is not required to run IssueDeck. If you change dashboard templates, helper class maps, or tailwind.config.cjs, rebuild the CSS with npm ci && npm run build:css.

Configure

server.toml controls the server:

host = "0.0.0.0"
port = 8765
api_token = "change-me-in-production"
data_dir = "./data"
projects_dir = "./projects"

For real use, set the token through the environment instead of committing it:

export ISSUEDECK_API_TOKEN="your-secret-token"

PowerShell:

$env:ISSUEDECK_API_TOKEN = "your-secret-token"

api_token remains the backwards-compatible admin token. For multiple clients, add scoped tokens:

[[tokens]]
name = "readonly"
token = "replace-with-readonly-token"
scopes = ["read"]

[[tokens]]
name = "agent"
token = "replace-with-agent-token"
scopes = ["agent"]

[[tokens]]
name = "admin-dashboard"
token = "replace-with-admin-token"
scopes = ["admin"]

read tokens can call read-only API endpoints. agent tokens can read and write REST API resources for MCP/coding-agent workflows. admin tokens have full API access and can sign in to the dashboard.

Optional signed lifecycle webhooks can notify downstream automation when items are created, updated, shipped, deleted, or restored; see Lifecycle Webhooks. Receiver examples for FastAPI, Flask, and Node/Express live in Webhook Receiver Examples.

Project files live in projects/*.toml. Each file defines one project and must use the same file stem, key, and dashboard URL segment. The repository includes projects/example.toml so the quickstart works immediately:

key = "myproject"
name = "My Project"

Dashboard: http://127.0.0.1:8765/dashboard/myproject

Demo Data

Use fake data for screenshots, docs, or a clean local demo:

uv run issuedeck seed-demo --config server.toml --project-key example

If the target project already has items, the command refuses to overwrite it. To intentionally replace that project's items, add --force-reset.

For the full first-run flow, prefer uv run issuedeck demo; it creates config, runs migrations, seeds fake data, and starts the dashboard.

GitHub URL Helper

Create an IssueDeck item from a GitHub issue, pull request, or commit URL:

uv run issuedeck import-github-url \
  --config server.toml \
  --project-key example \
  --kind feature \
  https://github.com/example/repo/issues/42

Use --dry-run to preview the create payload before writing. See GitHub URL Import.

Markdown Task List Import

Import ordinary Markdown checklists from a file or directory:

uv run issuedeck import-markdown-list TODO.md \
  --config server.toml \
  --project-key example \
  --kind feature \
  --tag planning

Checked tasks are skipped by default; add --include-checked to import them into the first terminal project status. See Markdown Task List Import.

CSV Import

Import tracker exports and spreadsheet rows:

uv run issuedeck import-csv issues.csv \
  --config server.toml \
  --project-key example \
  --preset github \
  --status-map open=proposed \
  --status-map closed=done

Use --field-alias for custom headers and --dry-run to validate before writing. See CSV Import.

JSON Import

Import JSON arrays or wrapped tracker exports such as { "issues": [...] }:

uv run issuedeck import-json issues.json \
  --config server.toml \
  --project-key example \
  --preset github \
  --status-map open=proposed \
  --status-map closed=done

Use --field-alias for custom keys and --dry-run to validate before writing. See JSON Import.

Hosted Tracker Exports

For GitHub Issues, Linear, Jira, and generic table exports, see Hosted Tracker Export Helpers. The guide shows source export commands and matching import-json / import-csv calls.

Run the server

# Start the server; it applies database migrations before listening.
export ISSUEDECK_API_TOKEN="your-secret-token"
uv run issuedeck serve --config server.toml

PowerShell:

$env:ISSUEDECK_API_TOKEN = "your-secret-token"
uv run issuedeck serve --config server.toml

The dashboard uses the same shared token as the API. Open the dashboard URL, enter ISSUEDECK_API_TOKEN, and IssueDeck will create an HTTP-only browser session cookie. API and MCP clients should keep using the Authorization: Bearer <token> header.

Docker

The default Compose file pulls the published image from GitHub Container Registry:

cp server.toml.example server.toml
cp .env.example .env
docker compose pull
docker compose up -d

Open http://127.0.0.1:8765/dashboard/example and sign in with ISSUEDECK_API_TOKEN from .env.

To run a locally built image from source instead:

docker build -t issuedeck:local .
ISSUEDECK_IMAGE=issuedeck:local docker compose up -d

For offline or server deployment details, see DEPLOY.md. A longer Chinese deployment guide is available at docs/deployment.zh.md. For a small production hardening checklist, see Docker Compose Hardening.

MCP stdio process

For client-specific examples, see MCP Client Setup.

Generic stdio config:

{
  "mcpServers": {
    "issuedeck": {
      "command": "uv",
      "args": ["run", "python", "-m", "issuedeck.mcp"],
      "env": {
        "ISSUEDECK_BASE_URL": "http://127.0.0.1:8765",
        "ISSUEDECK_TOKEN": "your-secret-token"
      }
    }
  }
}

Note: The MCP client reads ISSUEDECK_TOKEN; the server reads ISSUEDECK_API_TOKEN. They may hold the same value but the env var names differ by design (client/server are separate processes).

12 tools: list_projects, get_project_config, create_item, update_item, ship_item, append_item_event, delete_item, get_item, list_items, search_items, add_relationship, remove_relationship.

The MCP process reads ISSUEDECK_BASE_URL and ISSUEDECK_TOKEN, then talks to the REST server over HTTP. It does not access SQLite directly.

Migrate from Markdown Frontmatter

uv run issuedeck migrate \
  --config server.toml \
  --from-frontmatter /path/to/markdown-tracker \
  --project-key myproject

Add --dry-run to preview without writing. Add --force-reset to wipe existing items first. The importer accepts the canonical schema plus common aliases such as type, state, and labels; see Markdown Frontmatter Import for the full schema and custom alias options.

Export

uv run issuedeck export \
  --config server.toml \
  --project-key myproject \
  --out ./export

Writes one .md file per item with YAML frontmatter.

Development

uv sync
uv run pytest
uv run ruff check .

For dashboard UI work:

npm ci
npm run build:css

Read CONTRIBUTING.md before opening a pull request. Dashboard UI work should follow DESIGN.md. Use the Dashboard Accessibility Smoke Checklist for UI changes. See ROADMAP.md for planned work and contribution areas. Starter contribution candidates live in Starter Issue Backlog. Maintainer launch copy is collected in Launch Kit. For support and issue-reporting guidance, see SUPPORT.md. For sensitive vulnerabilities, follow SECURITY.md. For PyPI Trusted Publishing setup, see docs/pypi-publishing.md.

License

MIT. See LICENSE. Vendored dashboard browser assets are listed in THIRD_PARTY_NOTICES.md.