issuedeck 0.3.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.

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.
• 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 and language switch foundation.
• 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 GitHub version without cloning:

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

After the PyPI package is published, the command becomes:

uvx 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.

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.

Run the server

# Apply database migrations first
uv run alembic upgrade head

# Start the server
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.

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. See ROADMAP.md for planned work and contribution areas. 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.