choda-deck 0.1.0 โ†’ 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +122 -22
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,40 @@
1
1
  # choda-deck
2
2
 
3
- MCP server providing SQLite-backed task / session / conversation / inbox orchestration for [Claude Code](https://docs.claude.com/claude-code).
3
+ > **Persistent memory + orchestration layer for [Claude Code](https://docs.claude.com/claude-code).**
4
+ > Tasks, sessions, conversations, decisions, and inbox โ€” all backed by SQLite, all reachable through MCP tools.
4
5
 
5
- Pure Node, Windows-first, MIT.
6
+ [![npm version](https://img.shields.io/npm/v/choda-deck.svg)](https://www.npmjs.com/package/choda-deck)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
8
+
9
+ ---
10
+
11
+ ## What is choda-deck?
12
+
13
+ A pure-Node MCP server that turns Claude Code from a stateless chat into a **stateful collaborator**.
14
+
15
+ Claude can:
16
+ - ๐Ÿ“‹ Track tasks with acceptance criteria, status, and labels
17
+ - ๐Ÿงต Bind work sessions to tasks โ€” checkpoint progress, resume next time with full context
18
+ - ๐Ÿ’ฌ Hold structured conversations with decisions logged
19
+ - ๐Ÿ“ฅ Capture mid-flow ideas to an inbox, research them later, convert to tasks
20
+ - ๐Ÿ“š Maintain a knowledge layer (ADRs / decision logs) with staleness tracking
21
+ - ๐Ÿ’พ Auto-backup daily, restore on demand
22
+
23
+ Everything lives in a single SQLite file. No cloud, no SaaS, no telemetry.
24
+
25
+ ## Why?
26
+
27
+ Working with Claude Code across many days hits the same walls:
28
+
29
+ | Pain | Without choda-deck | With choda-deck |
30
+ |---|---|---|
31
+ | Lost task list | Scattered across markdown / TODO comments / chat history | One queryable source of truth |
32
+ | Lost context between sessions | Re-explain what you were doing last time | `session_resume` loads task body + AC + last checkpoint |
33
+ | Decisions disappear into chat | Scroll back, hope you find it | `conversation_decide` + `knowledge_create` log decisions next to code |
34
+ | Ideas dropped mid-flow | Forgotten or pile up in scratch files | `inbox_add` โ€” research/convert/archive later |
35
+ | ADRs drift from code | Manual review, never happens | `knowledge_verify` flags stale ADRs via `refs[]` |
36
+
37
+ choda-deck is the **memory layer** Claude wishes it had built-in.
6
38
 
7
39
  ## Install
8
40
 
@@ -14,9 +46,9 @@ npx choda-deck
14
46
 
15
47
  Requires Node.js >= 20.
16
48
 
17
- ## Use with Claude Code
49
+ ## Wire it into Claude Code
18
50
 
19
- Add to your Claude Code MCP config (`.claude.json` or project-scoped `.mcp.json`):
51
+ Add to `.claude.json` (user-level) or `.mcp.json` (project-level):
20
52
 
21
53
  ```json
22
54
  {
@@ -26,42 +58,110 @@ Add to your Claude Code MCP config (`.claude.json` or project-scoped `.mcp.json`
26
58
  "args": ["-y", "choda-deck"],
27
59
  "env": {
28
60
  "CHODA_DATA_DIR": "/absolute/path/to/data",
29
- "CHODA_CONTENT_ROOT": "/absolute/path/to/your/vault"
61
+ "CHODA_CONTENT_ROOT": "/absolute/path/to/your/notes-or-vault"
30
62
  }
31
63
  }
32
64
  }
33
65
  }
34
66
  ```
35
67
 
36
- ### Environment variables
68
+ Restart Claude Code โ†’ the `choda-tasks` MCP server is online.
37
69
 
38
- | Var | Purpose |
39
- |---|---|
40
- | `CHODA_DATA_DIR` | Where the SQLite DB, artifacts, and backups live. Created on first run. |
41
- | `CHODA_CONTENT_ROOT` | Root for knowledge / vault content lookup. Optional. |
70
+ ## Tools
42
71
 
43
- ### Data layout
72
+ All tools are namespaced `mcp__choda-tasks__<name>`. Claude calls them on your behalf โ€” you never invoke them directly.
73
+
74
+ | Domain | Tools | What it does |
75
+ |---|---|---|
76
+ | **Project** | `project_add`, `project_list`, `project_context` | Multi-project setup. Each project has its own task list and metadata. |
77
+ | **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. |
78
+ | **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. |
79
+ | **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. |
80
+ | **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. |
81
+ | **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`. |
82
+ | **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. |
83
+ | **Backup** | `backup_create`, `backup_list`, `backup_restore` | Daily auto-backup of the SQLite DB. Manual create + restore when you need to roll back. |
84
+
85
+ ## Common workflows
86
+
87
+ ### 1. Task-driven session
44
88
 
45
89
  ```
46
- $CHODA_DATA_DIR/
47
- โ”œโ”€โ”€ database/choda-deck.db
48
- โ”œโ”€โ”€ artifacts/<sessionId>/
49
- โ””โ”€โ”€ backups/choda-deck-<date>.db
90
+ You : "Let's work on TASK-123"
91
+ Claude : (task_context TASK-123) โ†’ loads body + AC
92
+ Claude : (session_start TASK-123) โ†’ binds session
93
+ You : (work happens)
94
+ Claude : (session_checkpoint "finished part 1, hit X issue")
95
+ You : "stop here, continue tomorrow"
96
+ Claude : (session_end)
97
+
98
+ โ€” next day โ€”
99
+ You : "resume yesterday's work"
100
+ Claude : (session_resume) โ†’ re-reads task body + last checkpoint
50
101
  ```
51
102
 
52
- Daily backups are taken automatically; restore via the `backup_restore` MCP tool.
103
+ ### 2. Capture without breaking flow
53
104
 
54
- ## What it gives you
105
+ ```
106
+ You : "While we're here โ€” idea: split this module into two"
107
+ Claude : (inbox_add content="split foo module โ†’ two") โ€” back to current work
108
+ ```
55
109
 
56
- Domain tools across project / workspace / task / phase / inbox / conversation / session / search / roadmap / backup. The full schema is described in `docs/knowledge/` (ADRs) on the [GitHub repo](https://github.com/butterngo/choda-deck).
110
+ Later:
111
+ ```
112
+ You : "show me the inbox"
113
+ Claude : (inbox_list) โ†’ 12 raw items
114
+ You : "research INBOX-008"
115
+ Claude : (inbox_research) โ†’ reads codebase, writes findings, sets status=ready
116
+ You : "convert it"
117
+ Claude : (inbox_convert) โ†’ creates TASK-456 with body from research
118
+ ```
119
+
120
+ ### 3. Decision log next to code
121
+
122
+ ```
123
+ You : "should we use sqlite-vec or qdrant for embeddings?"
124
+ Claude : (conversation_open "embedding store choice")
125
+ Claude : (analyzes both, posts trade-offs)
126
+ You : "go sqlite-vec for now"
127
+ Claude : (conversation_decide "sqlite-vec โ€” brute KNN fine at our scale")
128
+ Claude : (knowledge_create ADR-020 with refs to src/embeddings/*.ts)
129
+ Claude : (conversation_close)
130
+ ```
131
+
132
+ Three months later, when you edit `src/embeddings/`:
133
+ ```
134
+ Claude : (knowledge_verify) โ†’ flags ADR-020 as potentially stale (refs SHA mismatch)
135
+ ```
136
+
137
+ ## Configuration
138
+
139
+ | Env var | Default | Purpose |
140
+ |---|---|---|
141
+ | `CHODA_DATA_DIR` | _required_ | SQLite DB, artifacts, and backups directory. Created on first run. |
142
+ | `CHODA_CONTENT_ROOT` | _optional_ | Root for knowledge / vault content lookup. |
143
+
144
+ ### Data layout
145
+
146
+ ```
147
+ $CHODA_DATA_DIR/
148
+ โ”œโ”€โ”€ database/choda-deck.db โ† single source of truth
149
+ โ”œโ”€โ”€ artifacts/<sessionId>/ โ† per-session scratch
150
+ โ””โ”€โ”€ backups/choda-deck-<date>.db โ† auto daily, retained
151
+ ```
57
152
 
58
153
  ## Architecture
59
154
 
60
- - SQLite (`better-sqlite3`) โ€” single source of truth
61
- - MCP stdio โ€” AI interaction layer
62
- - Pure Node runtime (no Electron, no PTY)
155
+ - **SQLite** (`better-sqlite3`) โ€” single source of truth, file-based, no daemon
156
+ - **MCP stdio** โ€” AI interaction layer (Anthropic's [Model Context Protocol](https://modelcontextprotocol.io))
157
+ - **Pure Node runtime** โ€” no Electron, no PTY, no native deps beyond `better-sqlite3`
158
+ - **Windows-first**, but runs on macOS and Linux
159
+
160
+ See [`docs/architecture.md`](https://github.com/butterngo/choda-deck/blob/main/docs/architecture.md) for the full layout, and ADRs in [`docs/knowledge/`](https://github.com/butterngo/choda-deck/tree/main/docs/knowledge) for design decisions.
161
+
162
+ ## Status
63
163
 
64
- See [`docs/architecture.md`](https://github.com/butterngo/choda-deck/blob/main/docs/architecture.md) and ADRs in [`docs/knowledge/`](https://github.com/butterngo/choda-deck/tree/main/docs/knowledge) for design details.
164
+ `0.1.0` โ€” early, dogfooded daily by the author. API may move before `1.0`. Issues + PRs welcome.
65
165
 
66
166
  ## License
67
167
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "choda-deck",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "MCP server providing SQLite-backed task/session/conversation orchestration for Claude Code.",
5
5
  "author": "Vu Ngo",
6
6
  "license": "MIT",