issuedeck 0.5.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. Agent handoffs and progress tracking are covered in Agent Work Sessions. GitHub backlog imports are covered in GitHub Issues Import. Dashboard CSV, JSON, and Markdown uploads are covered in Dashboard File Imports. Reopening earlier import batches is covered in Dashboard Import History. Bulk cleanup after imports is covered in Dashboard Bulk Triage. Starter configs for new workspaces are covered in Project Templates. Project snapshots are covered in Audit Bundles.

Features

• Agent-ready: MCP tools let coding agents create, update, search, relate, and ship tracked work without scraping Markdown.
• Agent Work Sessions track which agent is working on which item, the goal, progress updates, and the final outcome.
• 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.
• GitHub Issues importer for pulling repository issues into IssueDeck from the dashboard or CLI with state/label filters and duplicate skipping.
• CSV, JSON, and Markdown task-list import from the dashboard or CLI 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.
• Dashboard bulk triage for updating status, kind, tags, branches, delete, and restore across many selected items.
• Dashboard import history for reopening recent GitHub, CSV, JSON, and Markdown import batches.
• 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.
• Project-level audit bundles for ZIP snapshots of config, items, relationships, work sessions, and import history.
• 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 with starter templates, 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.

Project configs live in projects/*.toml. The dashboard can create new projects from Basic issue deck, Agent workflow, and Software team starter templates; edit TOML directly for advanced customizations.

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.

GitHub Issues Import

Import open issues from a repository and safely rerun later without duplicating items that already have the same GitHub external link:

uv run issuedeck import-github-issues example/repo \
  --config server.toml \
  --project-key example \
  --kind feature \
  --state all \
  --status-map closed=done

Use GITHUB_TOKEN or --github-token for private repositories or higher rate limits. From the dashboard, open a project and choose Import GitHub in the sidebar to preview the same import before writing. See GitHub Issues 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. Maintainer and AI coding-window handoff rules are documented in Maintainer Workflow. 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.