Choda Deck
No description available
Ask AI about Choda Deck
Powered by Claude Β· Grounded in docs
I know everything about Choda Deck. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
choda-deck
Persistent memory + orchestration layer for Claude Code. Tasks, sessions, conversations, decisions, and inbox β all backed by SQLite, all reachable through MCP tools.
What is choda-deck?
A pure-Node MCP server that turns Claude Code from a stateless chat into a stateful collaborator.
Claude can:
- π Track tasks with acceptance criteria, status, and labels
- π§΅ Bind work sessions to tasks β checkpoint progress, resume next time with full context
- π¬ Hold structured conversations with decisions logged
- π₯ Capture mid-flow ideas to an inbox, research them later, convert to tasks
- π Maintain a knowledge layer (ADRs / decision logs) with staleness tracking
- πΎ Auto-backup daily, restore on demand
Everything lives in a single SQLite file. No cloud, no SaaS, no telemetry.
Why?
Working with Claude Code across many days hits the same walls:
| Pain | Without choda-deck | With choda-deck |
|---|---|---|
| Lost task list | Scattered across markdown / TODO comments / chat history | One queryable source of truth |
| Lost context between sessions | Re-explain what you were doing last time | session_resume loads task body + AC + last checkpoint |
| Decisions disappear into chat | Scroll back, hope you find it | conversation_decide + knowledge_create log decisions next to code |
| Ideas dropped mid-flow | Forgotten or pile up in scratch files | inbox_add β research/convert/archive later |
| ADRs drift from code | Manual review, never happens | knowledge_verify flags stale ADRs via refs[] |
choda-deck is the memory layer Claude wishes it had built-in.
Install
npm install -g choda-deck
# or run on demand
npx choda-deck
Requires Node.js >= 20.
Wire it into Claude Code
Add to .claude.json (user-level) or .mcp.json (project-level):
{
"mcpServers": {
"choda-tasks": {
"command": "npx",
"args": ["-y", "choda-deck"],
"env": {
"CHODA_DATA_DIR": "/absolute/path/to/data",
"CHODA_CONTENT_ROOT": "/absolute/path/to/your/notes-or-vault"
}
}
}
}
Restart Claude Code β the choda-tasks MCP server is online.
CLI
choda-deck ships a read-only CLI that talks to the same SQLite store directly β no AI in the loop, no MCP roundtrip. Use it to verify state, script automations, or pipe to jq.
choda-deck --help # show all subcommands
choda-deck task list --status TODO --json # script-friendly
choda-deck task show TASK-669 # body + linked conversations
choda-deck inbox list --project choda-deck
choda-deck knowledge list
choda-deck knowledge show ADR-020-embedding-architecture
choda-deck project context choda-deck # AI's session_start view
choda-deck mcp serve # start the MCP stdio server
Pass --json to any read command for machine-readable output. Plain text is the default for humans.
Reading freshness
The CLI opens SQLite in WAL mode for shared reads. While the MCP server is actively writing, a CLI read may see a snapshot from a few seconds ago β re-run after 1-2s if state looks stale. See knowledge entry sqlite-wal-read-consistency for details.
Tools
All tools are namespaced mcp__choda-tasks__<name>. Claude calls them on your behalf β you never invoke them directly.
| Domain | Tools | What it does |
|---|---|---|
| Project | project_add, project_list, project_context | Multi-project setup. Each project has its own task list and metadata. |
| Workspace | workspace_add, workspace_list, workspace_archive, workspace_remove | Sub-scope inside a project (e.g. frontend, backend, infra). Knowledge entries can be scoped to a workspace. |
| Task | task_create, task_list, task_update, task_context, tasks_update_batch | TODO β READY β IN-PROGRESS β DONE/BLOCKED. Each task has body + acceptance criteria + labels + priority. |
| Session | session_start, session_checkpoint, session_end, session_resume, session_list | Bind a work session to a task. Checkpoint progress so the next session resumes with full context. |
| Conversation | conversation_open, conversation_add, conversation_decide, conversation_close, conversation_reopen, conversation_list, conversation_read, conversation_poll | Structured threads (e.g. FE/BE alignment, ADR debate). decide logs the resolution. |
| Inbox | inbox_add, inbox_research, inbox_convert, inbox_ready, inbox_archive, inbox_delete, inbox_list, inbox_get, inbox_update | Capture-now, decide-later. Items move raw β researching β ready β converted (to a task) or archived. |
| Knowledge | knowledge_create, knowledge_list, knowledge_get, knowledge_search, knowledge_update, knowledge_verify, knowledge_register_existing, knowledge_delete | ADRs / decision logs with frontmatter. refs[] tracks implementation files + commit SHAs β staleness banner when code drifts. |
| Backup | backup_create, backup_list, backup_restore | Daily auto-backup of the SQLite DB. Manual create + restore when you need to roll back. |
Common workflows
1. Task-driven session
You : "Let's work on TASK-123"
Claude : (task_context TASK-123) β loads body + AC
Claude : (session_start TASK-123) β binds session
You : (work happens)
Claude : (session_checkpoint "finished part 1, hit X issue")
You : "stop here, continue tomorrow"
Claude : (session_end)
β next day β
You : "resume yesterday's work"
Claude : (session_resume) β re-reads task body + last checkpoint
2. Capture without breaking flow
You : "While we're here β idea: split this module into two"
Claude : (inbox_add content="split foo module β two") β back to current work
Later:
You : "show me the inbox"
Claude : (inbox_list) β 12 raw items
You : "research INBOX-008"
Claude : (inbox_research) β reads codebase, writes findings, sets status=ready
You : "convert it"
Claude : (inbox_convert) β creates TASK-456 with body from research
3. Decision log next to code
You : "should we use sqlite-vec or qdrant for embeddings?"
Claude : (conversation_open "embedding store choice")
Claude : (analyzes both, posts trade-offs)
You : "go sqlite-vec for now"
Claude : (conversation_decide "sqlite-vec β brute KNN fine at our scale")
Claude : (knowledge_create ADR-020 with refs to src/embeddings/*.ts)
Claude : (conversation_close)
Three months later, when you edit src/embeddings/:
Claude : (knowledge_verify) β flags ADR-020 as potentially stale (refs SHA mismatch)
Configuration
| Env var | Default | Purpose |
|---|---|---|
CHODA_DATA_DIR | required | SQLite DB, artifacts, and backups directory. Created on first run. |
CHODA_CONTENT_ROOT | optional | Root for knowledge / vault content lookup. |
Data layout
$CHODA_DATA_DIR/
βββ database/choda-deck.db β single source of truth
βββ artifacts/<sessionId>/ β per-session scratch
βββ backups/choda-deck-<date>.db β auto daily, retained
Architecture
- SQLite (
better-sqlite3) β single source of truth, file-based, no daemon - MCP stdio β AI interaction layer (Anthropic's Model Context Protocol)
- Pure Node runtime β no Electron, no PTY, no native deps beyond
better-sqlite3 - Windows-first, but runs on macOS and Linux
See docs/architecture.md for the full layout, and ADRs in docs/knowledge/ for design decisions.
Status
0.1.0 β early, dogfooded daily by the author. API may move before 1.0. Issues + PRs welcome.
License
MIT β see LICENSE.
