@shinobiapps/shinobi 0.1.3 → 0.1.4

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.
package/README.md CHANGED
@@ -1,368 +1,369 @@
1
- # Shinobi
2
-
3
- [![test](https://github.com/numbererikson/shinobi/actions/workflows/test.yml/badge.svg)](https://github.com/numbererikson/shinobi/actions/workflows/test.yml)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
- [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
6
-
7
- Your AI coding agent forgets every session. Shinobi is the fix — local SQLite + MCP, decisions stick, dead-ends stay logged, approvals come to your phone.
8
-
9
- Works with Claude Code, Cursor, Cline, Continue.dev, Zed — any MCP-compatible client.
10
-
11
- > **Status:** v0.1 — feature-complete first release. MCP server with 37 tools, web dashboard, plugin system, cross-machine sync, optional semantic recall.
12
-
13
- ## What it does
14
-
15
- Shinobi gives your AI coding agent persistent project memory across sessions:
16
-
17
- - **Projects + subtasks** — track multi-session work as the agent claims, completes, or pivots
18
- - **Decisions** — record architectural choices with rationale so future sessions don't re-litigate them
19
- - **Dead ends** — log approaches that failed; the agent checks here before retrying
20
- - **Notes** — free-form annotations and voice notes (audio_path field)
21
- - **Plans** — versioned plan snapshots, retrievable mid-task
22
- - **Context** — per-project conventions, "don't touch" rules, test patterns, deploy notes, file annotations
23
- - **Recall** — fulltext (FTS5) by default, semantic (embedding-backed) when an embedding provider is configured
24
- - **Activity timeline** — every write path lands in the timeline so you can replay what happened
25
- - **Git linking** — `link_commit` ties commits to subtasks via `[SHI-N]` tags or via `target_path` attribution
26
- - **Web dashboard** — Hono-served Kanban + decisions + dead ends + notes + plans + context + timeline + analytics on `localhost:8765`
27
- - **Cross-machine sync** — git-based snapshot push/pull, zero cloud infrastructure
28
- - **Plugin system** — drop a `.js` file in `~/.shinobi/plugins/` or install a `@shinobi/plugin-*` npm package and register custom `plugin_*` tools
29
-
30
- All local. SQLite. No cloud account required (BYO embedding provider only if you want semantic recall).
31
-
32
- ## Install
33
-
34
- Requirements:
35
-
36
- - Node.js 18+ on `PATH`
37
- - C++ build toolchain for `better-sqlite3` native build (most systems have prebuilt binaries; Windows may need [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) as fallback)
38
-
39
- ### From npm (recommended)
40
-
41
- ```bash
42
- npm install -g @shinobiapps/shinobi
43
- ```
44
-
45
- The binary is `shinobi` (e.g. `shinobi serve`, `shinobi dashboard`).
46
-
47
- ### From GitHub (latest, unreleased)
48
-
49
- ```bash
50
- npm install -g github:numbererikson/shinobi
51
- ```
52
-
53
- Pulls from `main`. Useful for trying unreleased fixes. On Windows you may need
54
- to add your Node directory to system `PATH` before this works, because the
55
- `prepare` build script runs in a subshell that does not always inherit
56
- per-session `PATH` (Laragon, portable installs). If install fails with `'node'
57
- is not recognized`, prefer the npm install above.
58
-
59
- ### From a cloned source folder (for development / contributing)
60
-
61
- ```bash
62
- git clone https://github.com/numbererikson/shinobi.git
63
- cd shinobi
64
- npm install # triggers `prepare` → builds dist/
65
- npm install -g .
66
- ```
67
-
68
- ### Then bootstrap
69
-
70
- In any project root where you want Shinobi available to your MCP client:
71
-
72
- ```bash
73
- shinobi init
74
- shinobi dashboard
75
- ```
76
-
77
- `init` will:
78
- 1. Create `~/.shinobi/` with `config.json`, `.env` template, and `shinobi.db` (migrations applied)
79
- 2. Drop a `.mcp.json` snippet for the current project
80
- 3. Print next steps
81
-
82
- `shinobi init` writes config for the two clients with a workspace-local
83
- MCP convention out of the box:
84
-
85
- - **Claude Code** — `<workspace>/.mcp.json`
86
- - **Cursor** — `<workspace>/.cursor/mcp.json`
87
-
88
- Restart the client and the `mcp__shinobi__*` tools become available.
89
-
90
- For other MCP clients (Cline, Continue.dev, Zed), see the
91
- [MCP client setup](#mcp-client-setup) section below.
92
-
93
- Then open:
94
-
95
- ```text
96
- http://127.0.0.1:8765
97
- ```
98
-
99
- On Windows PowerShell, if script execution blocks `shinobi`, use the `.cmd` shim:
100
-
101
- ```powershell
102
- shinobi.cmd dashboard
103
- ```
104
-
105
- If you upgraded Node or copied an old `node_modules`, rebuild native dependencies:
106
-
107
- ```bash
108
- npm rebuild better-sqlite3
109
- ```
110
-
111
- Important: the code lives in the Shinobi folder, but the local memory database lives in:
112
-
113
- ```text
114
- ~/.shinobi/shinobi.db
115
- ```
116
-
117
- To move the tool only, copy/clone the Shinobi folder and run the install commands above. To move the existing projects, tasks, decisions, notes, and context too, either copy `~/.shinobi/` or use `shinobi sync`.
118
-
119
- ## MCP client setup
120
-
121
- Every snippet below uses the **same JSON shape** — `command` is the path
122
- to the Node binary that's running Shinobi, `args` is `[<absolute path to
123
- dist/cli.js>, "mcp"]`. Print the exact values for your machine:
124
-
125
- ```bash
126
- shinobi init --print-config
127
- ```
128
-
129
- (Or read `.mcp.json` from any project where you already ran
130
- `shinobi init` — the values are identical.)
131
-
132
- ### Claude Code
133
-
134
- Drops in automatically — `shinobi init` writes `<workspace>/.mcp.json`.
135
- Restart Claude Code to pick up the server.
136
-
137
- ### Cursor
138
-
139
- Drops in automatically — `shinobi init` writes `<workspace>/.cursor/mcp.json`.
140
- Works on Cursor 0.43+. Restart Cursor or reload the workspace.
141
-
142
- For a **global** Cursor config (every project sees Shinobi), paste the
143
- same snippet into `~/.cursor/mcp.json` (or use Cursor Settings → MCP).
144
-
145
- ### Cline (VS Code extension)
146
-
147
- Open Cline's settings file:
148
-
149
- - Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
150
- - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
151
- - Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
152
-
153
- Merge the contents of your project's `.mcp.json` into the file's
154
- `mcpServers` object. Restart VS Code.
155
-
156
- ### Continue.dev
157
-
158
- Edit `~/.continue/config.json`. Add Shinobi to the `mcpServers` array
159
- (note: Continue uses an **array**, not an object like the others):
160
-
161
- ```json
162
- {
163
- "mcpServers": [
164
- {
165
- "name": "shinobi",
166
- "command": "/absolute/path/to/node",
167
- "args": ["/absolute/path/to/dist/cli.js", "mcp"]
168
- }
169
- ]
170
- }
171
- ```
172
-
173
- Use the values from your project's `.mcp.json` for `command` and `args`.
174
-
175
- ### Zed
176
-
177
- Edit `~/.config/zed/settings.json`. Zed nests MCP servers under
178
- `context_servers`:
179
-
180
- ```json
181
- {
182
- "context_servers": {
183
- "shinobi": {
184
- "command": {
185
- "path": "/absolute/path/to/node",
186
- "args": ["/absolute/path/to/dist/cli.js", "mcp"]
187
- }
188
- }
189
- }
190
- }
191
- ```
192
-
193
- Restart Zed.
194
-
195
- ### Generic / other clients
196
-
197
- Any MCP client that supports the standard `{ command, args }` server spec
198
- should work. Use the same values your `.mcp.json` has:
199
-
200
- - `command`: absolute path to the Node binary running Shinobi
201
- - `args`: `[<absolute path to dist/cli.js>, "mcp"]`
202
-
203
- Avoid the bare `shinobi` command in MCP config — many clients spawn
204
- servers with `shell: false`, which skips the OS PATH resolution that
205
- makes `shinobi` work in a terminal.
206
-
207
- ## CLI
208
-
209
- ```
210
- shinobi <command> [options]
211
-
212
- Commands:
213
- init Bootstrap ~/.shinobi/ and drop .mcp.json in the current directory
214
- mcp Run the MCP server over stdio (invoked by the MCP client)
215
- migrate Apply pending SQL migrations
216
- dashboard Start the web dashboard on localhost (default port 8765)
217
- sync init <path> [branch] Configure a local git repo as the cross-machine sync target
218
- sync push Snapshot the DB and commit it to the sync repo
219
- sync pull Restore the DB from the sync repo's snapshot
220
- sync status Show last push/pull timestamps and git status
221
- ```
222
-
223
- ## MCP tools (37)
224
-
225
- | Group | Tools |
226
- |---|---|
227
- | Projects | list_projects, get_project, create_project, update_project, archive_project, unarchive_project, delete_project |
228
- | Subtasks | list_tasks, get_task, create_task, bulk_create_tasks, update_subtask, delete_subtask, claim_task, complete_task, next_task |
229
- | Decisions | log_decision, decisions_for_file, update_decision_status |
230
- | Dead ends | log_dead_end, check_dead_ends |
231
- | Notes | add_note, list_notes |
232
- | Plans | save_plan, get_plan |
233
- | Context | get_context, update_context |
234
- | Recall | recall (FTS5 or semantic) |
235
- | Timeline | history, link_commit |
236
- | Workflow | agent_bootstrap, session_closeout, file_context |
237
- | Extraction | extract_decisions, compress_session_summary |
238
- | Approvals | request_approval |
239
- | Plugins | plugin_hello |
240
-
241
- ## Architecture
242
-
243
- | Layer | Tech |
244
- |---|---|
245
- | Language | TypeScript (strict mode, ES2022, NodeNext) |
246
- | Runtime | Node 18+ |
247
- | MCP | `@modelcontextprotocol/sdk` 1.x |
248
- | Storage | SQLite via `better-sqlite3` (WAL mode) |
249
- | Dashboard | Hono + `@hono/node-server` (same process, localhost:8765) |
250
- | Embeddings (optional) | OpenAI text-embedding-3-small / Voyage voyage-3-lite / Ollama nomic-embed-text |
251
- | Migrations | Forward-only, sha256 checksum, `schema_migrations` table |
252
-
253
- See [docs/architecture.md](docs/architecture.md) for the request lifecycle and module layout.
254
-
255
- ## Dashboard auth
256
-
257
- The dashboard is open on loopback binds (`127.0.0.1`, `localhost`, `::1`) and token-protected on any non-loopback bind. The token is read from `SHINOBI_DASHBOARD_TOKEN`, otherwise loaded from `~/.shinobi/dashboard-token`, otherwise auto-generated and persisted there. `/health` is always open for probes.
258
-
259
- Browser flow — open the dashboard with the token once and the cookie sticks:
260
-
261
- ```text
262
- http://192.168.1.10:8765/?token=YOUR_TOKEN
263
- ```
264
-
265
- Curl / scripts — any of these works:
266
-
267
- ```bash
268
- curl -H "Authorization: Bearer $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
269
- curl -H "X-Shinobi-Token: $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
270
- curl --cookie "shinobi_token=$SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
271
- ```
272
-
273
- See [docs/configuration.md](docs/configuration.md#dashboard) for the full env-var reference.
274
-
275
- ## Cross-machine sync
276
-
277
- Shinobi syncs your local SQLite database via a private git repo. Setup once per machine:
278
-
279
- ```bash
280
- # Once: clone a private GitHub repo to act as the sync repo
281
- git clone git@github.com:USER/shinobi-sync.git ~/shinobi-sync
282
-
283
- # Once per machine: tell shinobi about it
284
- shinobi sync init ~/shinobi-sync main
285
-
286
- # Push from the writer machine:
287
- shinobi sync push
288
-
289
- # Pull on the reader machine:
290
- shinobi sync pull
291
- ```
292
-
293
- The DB file lands on the `main` branch as a binary; pre-existing local DB is backed up to `<path>.bak-<timestamp>` before restore.
294
-
295
- ## Configuration
296
-
297
- Edit `~/.shinobi/.env` or set env vars before running `shinobi mcp`:
298
-
299
- | Variable | Default | Purpose |
300
- |---|---|---|
301
- | `SHINOBI_DB_PATH` | `~/.shinobi/shinobi.db` | SQLite location |
302
- | `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Config + plugins directory |
303
- | `SHINOBI_PLUGINS_DIR` | `${configdir}/plugins` | Plugin discovery directory |
304
- | `SHINOBI_DASHBOARD_PORT` | `8765` | Dashboard port |
305
- | `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind host. Loopback skips auth; non-loopback auto-enables token auth. |
306
- | `SHINOBI_DASHBOARD_TOKEN` | _(auto)_ | Override the dashboard token; auto-generated to `~/.shinobi/dashboard-token` when needed. |
307
- | `SHINOBI_EMBED_PROVIDER` | `none` | `openai` / `voyage` / `ollama` / `none` |
308
- | `SHINOBI_EMBED_API_KEY` | — | Auth for OpenAI / Voyage (else falls back to `OPENAI_API_KEY` / `VOYAGE_API_KEY`) |
309
- | `SHINOBI_EMBED_MODEL` | provider default | Override model id |
310
- | `SHINOBI_EMBED_DIMS` | provider default | Override dimensions |
311
- | `SHINOBI_OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |
312
- | `SHINOBI_MIGRATIONS_DIR` | `<package>/migrations` | Override migrations source |
313
-
314
- Full reference: [docs/configuration.md](docs/configuration.md).
315
-
316
- ## Plugins
317
-
318
- Write a single `.js` file in `~/.shinobi/plugins/`:
319
-
320
- ```js
321
- // ~/.shinobi/plugins/my-plugin.js
322
- export default function register(registry, api) {
323
- registry.registerTool({
324
- name: 'plugin_count_open',
325
- description: 'Count open decisions across all projects',
326
- inputSchema: { type: 'object', properties: {}, additionalProperties: false },
327
- handler: (_args, api) => {
328
- const projects = api.listProjects();
329
- let total = 0;
330
- for (const p of projects) {
331
- total += api.listDecisions({ projectId: p.id, status: 'open' }).length;
332
- }
333
- return { open_decisions: total };
334
- },
335
- });
336
- }
337
- ```
338
-
339
- Restart the MCP client and `mcp__shinobi__plugin_count_open` is available. See [docs/plugin-development.md](docs/plugin-development.md).
340
-
341
- ## Roadmap
342
-
343
- - **v0.1 (current)** — local MCP + dashboard + plugin system + git sync + relay
344
- + optional embeddings + voice + mobile push + VS Code/Cursor extensions.
345
- - **v0.2** — multi-user team mode (auth + members + mentions UI), vite/dev-deps
346
- upgrade, plugin marketplace UI polish, deeper integrations (Linear /
347
- GitHub Issues sync candidates).
348
- - **v0.3** — hosted SaaS GA + Stripe billing.
349
- - **v1.0** — stability, audit, performance pass.
350
-
351
- ## Changelog
352
-
353
- See [CHANGELOG.md](CHANGELOG.md) for release notes.
354
-
355
- ## Contributing
356
-
357
- See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
358
-
359
- By participating you agree to our [Code of Conduct](CODE_OF_CONDUCT.md).
360
-
361
- ## Security
362
-
363
- For vulnerability reports, see [SECURITY.md](SECURITY.md) — please do
364
- **not** open public issues for security matters.
365
-
366
- ## License
367
-
368
- MIT — see [LICENSE](LICENSE).
1
+ # Shinobi
2
+
3
+ [![Website](https://img.shields.io/badge/Website-shinobi--apps.com-c96442)](https://shinobi-apps.com/shinobi)
4
+ [![test](https://github.com/numbererikson/shinobi/actions/workflows/test.yml/badge.svg)](https://github.com/numbererikson/shinobi/actions/workflows/test.yml)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
7
+
8
+ Your AI coding agent forgets every session. Shinobi is the fix — local SQLite + MCP, decisions stick, dead-ends stay logged, approvals come to your phone.
9
+
10
+ Works with Claude Code, Cursor, Cline, Continue.dev, Zed — any MCP-compatible client.
11
+
12
+ > **Status:** v0.1 — feature-complete first release. MCP server with 37 tools, web dashboard, plugin system, cross-machine sync, optional semantic recall.
13
+
14
+ ## What it does
15
+
16
+ Shinobi gives your AI coding agent persistent project memory across sessions:
17
+
18
+ - **Projects + subtasks** — track multi-session work as the agent claims, completes, or pivots
19
+ - **Decisions** — record architectural choices with rationale so future sessions don't re-litigate them
20
+ - **Dead ends** — log approaches that failed; the agent checks here before retrying
21
+ - **Notes** — free-form annotations and voice notes (audio_path field)
22
+ - **Plans** — versioned plan snapshots, retrievable mid-task
23
+ - **Context** — per-project conventions, "don't touch" rules, test patterns, deploy notes, file annotations
24
+ - **Recall** — fulltext (FTS5) by default, semantic (embedding-backed) when an embedding provider is configured
25
+ - **Activity timeline** — every write path lands in the timeline so you can replay what happened
26
+ - **Git linking** — `link_commit` ties commits to subtasks via `[SHI-N]` tags or via `target_path` attribution
27
+ - **Web dashboard** — Hono-served Kanban + decisions + dead ends + notes + plans + context + timeline + analytics on `localhost:8765`
28
+ - **Cross-machine sync** — git-based snapshot push/pull, zero cloud infrastructure
29
+ - **Plugin system** — drop a `.js` file in `~/.shinobi/plugins/` or install a `@shinobi/plugin-*` npm package and register custom `plugin_*` tools
30
+
31
+ All local. SQLite. No cloud account required (BYO embedding provider only if you want semantic recall).
32
+
33
+ ## Install
34
+
35
+ Requirements:
36
+
37
+ - Node.js 18+ on `PATH`
38
+ - C++ build toolchain for `better-sqlite3` native build (most systems have prebuilt binaries; Windows may need [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) as fallback)
39
+
40
+ ### From npm (recommended)
41
+
42
+ ```bash
43
+ npm install -g @shinobiapps/shinobi
44
+ ```
45
+
46
+ The binary is `shinobi` (e.g. `shinobi serve`, `shinobi dashboard`).
47
+
48
+ ### From GitHub (latest, unreleased)
49
+
50
+ ```bash
51
+ npm install -g github:numbererikson/shinobi
52
+ ```
53
+
54
+ Pulls from `main`. Useful for trying unreleased fixes. On Windows you may need
55
+ to add your Node directory to system `PATH` before this works, because the
56
+ `prepare` build script runs in a subshell that does not always inherit
57
+ per-session `PATH` (Laragon, portable installs). If install fails with `'node'
58
+ is not recognized`, prefer the npm install above.
59
+
60
+ ### From a cloned source folder (for development / contributing)
61
+
62
+ ```bash
63
+ git clone https://github.com/numbererikson/shinobi.git
64
+ cd shinobi
65
+ npm install # triggers `prepare` → builds dist/
66
+ npm install -g .
67
+ ```
68
+
69
+ ### Then bootstrap
70
+
71
+ In any project root where you want Shinobi available to your MCP client:
72
+
73
+ ```bash
74
+ shinobi init
75
+ shinobi dashboard
76
+ ```
77
+
78
+ `init` will:
79
+ 1. Create `~/.shinobi/` with `config.json`, `.env` template, and `shinobi.db` (migrations applied)
80
+ 2. Drop a `.mcp.json` snippet for the current project
81
+ 3. Print next steps
82
+
83
+ `shinobi init` writes config for the two clients with a workspace-local
84
+ MCP convention out of the box:
85
+
86
+ - **Claude Code** — `<workspace>/.mcp.json`
87
+ - **Cursor** — `<workspace>/.cursor/mcp.json`
88
+
89
+ Restart the client and the `mcp__shinobi__*` tools become available.
90
+
91
+ For other MCP clients (Cline, Continue.dev, Zed), see the
92
+ [MCP client setup](#mcp-client-setup) section below.
93
+
94
+ Then open:
95
+
96
+ ```text
97
+ http://127.0.0.1:8765
98
+ ```
99
+
100
+ On Windows PowerShell, if script execution blocks `shinobi`, use the `.cmd` shim:
101
+
102
+ ```powershell
103
+ shinobi.cmd dashboard
104
+ ```
105
+
106
+ If you upgraded Node or copied an old `node_modules`, rebuild native dependencies:
107
+
108
+ ```bash
109
+ npm rebuild better-sqlite3
110
+ ```
111
+
112
+ Important: the code lives in the Shinobi folder, but the local memory database lives in:
113
+
114
+ ```text
115
+ ~/.shinobi/shinobi.db
116
+ ```
117
+
118
+ To move the tool only, copy/clone the Shinobi folder and run the install commands above. To move the existing projects, tasks, decisions, notes, and context too, either copy `~/.shinobi/` or use `shinobi sync`.
119
+
120
+ ## MCP client setup
121
+
122
+ Every snippet below uses the **same JSON shape** — `command` is the path
123
+ to the Node binary that's running Shinobi, `args` is `[<absolute path to
124
+ dist/cli.js>, "mcp"]`. Print the exact values for your machine:
125
+
126
+ ```bash
127
+ shinobi init --print-config
128
+ ```
129
+
130
+ (Or read `.mcp.json` from any project where you already ran
131
+ `shinobi init` — the values are identical.)
132
+
133
+ ### Claude Code
134
+
135
+ Drops in automatically — `shinobi init` writes `<workspace>/.mcp.json`.
136
+ Restart Claude Code to pick up the server.
137
+
138
+ ### Cursor
139
+
140
+ Drops in automatically — `shinobi init` writes `<workspace>/.cursor/mcp.json`.
141
+ Works on Cursor 0.43+. Restart Cursor or reload the workspace.
142
+
143
+ For a **global** Cursor config (every project sees Shinobi), paste the
144
+ same snippet into `~/.cursor/mcp.json` (or use Cursor Settings → MCP).
145
+
146
+ ### Cline (VS Code extension)
147
+
148
+ Open Cline's settings file:
149
+
150
+ - Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
151
+ - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
152
+ - Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
153
+
154
+ Merge the contents of your project's `.mcp.json` into the file's
155
+ `mcpServers` object. Restart VS Code.
156
+
157
+ ### Continue.dev
158
+
159
+ Edit `~/.continue/config.json`. Add Shinobi to the `mcpServers` array
160
+ (note: Continue uses an **array**, not an object like the others):
161
+
162
+ ```json
163
+ {
164
+ "mcpServers": [
165
+ {
166
+ "name": "shinobi",
167
+ "command": "/absolute/path/to/node",
168
+ "args": ["/absolute/path/to/dist/cli.js", "mcp"]
169
+ }
170
+ ]
171
+ }
172
+ ```
173
+
174
+ Use the values from your project's `.mcp.json` for `command` and `args`.
175
+
176
+ ### Zed
177
+
178
+ Edit `~/.config/zed/settings.json`. Zed nests MCP servers under
179
+ `context_servers`:
180
+
181
+ ```json
182
+ {
183
+ "context_servers": {
184
+ "shinobi": {
185
+ "command": {
186
+ "path": "/absolute/path/to/node",
187
+ "args": ["/absolute/path/to/dist/cli.js", "mcp"]
188
+ }
189
+ }
190
+ }
191
+ }
192
+ ```
193
+
194
+ Restart Zed.
195
+
196
+ ### Generic / other clients
197
+
198
+ Any MCP client that supports the standard `{ command, args }` server spec
199
+ should work. Use the same values your `.mcp.json` has:
200
+
201
+ - `command`: absolute path to the Node binary running Shinobi
202
+ - `args`: `[<absolute path to dist/cli.js>, "mcp"]`
203
+
204
+ Avoid the bare `shinobi` command in MCP config — many clients spawn
205
+ servers with `shell: false`, which skips the OS PATH resolution that
206
+ makes `shinobi` work in a terminal.
207
+
208
+ ## CLI
209
+
210
+ ```
211
+ shinobi <command> [options]
212
+
213
+ Commands:
214
+ init Bootstrap ~/.shinobi/ and drop .mcp.json in the current directory
215
+ mcp Run the MCP server over stdio (invoked by the MCP client)
216
+ migrate Apply pending SQL migrations
217
+ dashboard Start the web dashboard on localhost (default port 8765)
218
+ sync init <path> [branch] Configure a local git repo as the cross-machine sync target
219
+ sync push Snapshot the DB and commit it to the sync repo
220
+ sync pull Restore the DB from the sync repo's snapshot
221
+ sync status Show last push/pull timestamps and git status
222
+ ```
223
+
224
+ ## MCP tools (37)
225
+
226
+ | Group | Tools |
227
+ |---|---|
228
+ | Projects | list_projects, get_project, create_project, update_project, archive_project, unarchive_project, delete_project |
229
+ | Subtasks | list_tasks, get_task, create_task, bulk_create_tasks, update_subtask, delete_subtask, claim_task, complete_task, next_task |
230
+ | Decisions | log_decision, decisions_for_file, update_decision_status |
231
+ | Dead ends | log_dead_end, check_dead_ends |
232
+ | Notes | add_note, list_notes |
233
+ | Plans | save_plan, get_plan |
234
+ | Context | get_context, update_context |
235
+ | Recall | recall (FTS5 or semantic) |
236
+ | Timeline | history, link_commit |
237
+ | Workflow | agent_bootstrap, session_closeout, file_context |
238
+ | Extraction | extract_decisions, compress_session_summary |
239
+ | Approvals | request_approval |
240
+ | Plugins | plugin_hello |
241
+
242
+ ## Architecture
243
+
244
+ | Layer | Tech |
245
+ |---|---|
246
+ | Language | TypeScript (strict mode, ES2022, NodeNext) |
247
+ | Runtime | Node 18+ |
248
+ | MCP | `@modelcontextprotocol/sdk` 1.x |
249
+ | Storage | SQLite via `better-sqlite3` (WAL mode) |
250
+ | Dashboard | Hono + `@hono/node-server` (same process, localhost:8765) |
251
+ | Embeddings (optional) | OpenAI text-embedding-3-small / Voyage voyage-3-lite / Ollama nomic-embed-text |
252
+ | Migrations | Forward-only, sha256 checksum, `schema_migrations` table |
253
+
254
+ See [docs/architecture.md](docs/architecture.md) for the request lifecycle and module layout.
255
+
256
+ ## Dashboard auth
257
+
258
+ The dashboard is open on loopback binds (`127.0.0.1`, `localhost`, `::1`) and token-protected on any non-loopback bind. The token is read from `SHINOBI_DASHBOARD_TOKEN`, otherwise loaded from `~/.shinobi/dashboard-token`, otherwise auto-generated and persisted there. `/health` is always open for probes.
259
+
260
+ Browser flow — open the dashboard with the token once and the cookie sticks:
261
+
262
+ ```text
263
+ http://192.168.1.10:8765/?token=YOUR_TOKEN
264
+ ```
265
+
266
+ Curl / scripts — any of these works:
267
+
268
+ ```bash
269
+ curl -H "Authorization: Bearer $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
270
+ curl -H "X-Shinobi-Token: $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
271
+ curl --cookie "shinobi_token=$SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
272
+ ```
273
+
274
+ See [docs/configuration.md](docs/configuration.md#dashboard) for the full env-var reference.
275
+
276
+ ## Cross-machine sync
277
+
278
+ Shinobi syncs your local SQLite database via a private git repo. Setup once per machine:
279
+
280
+ ```bash
281
+ # Once: clone a private GitHub repo to act as the sync repo
282
+ git clone git@github.com:USER/shinobi-sync.git ~/shinobi-sync
283
+
284
+ # Once per machine: tell shinobi about it
285
+ shinobi sync init ~/shinobi-sync main
286
+
287
+ # Push from the writer machine:
288
+ shinobi sync push
289
+
290
+ # Pull on the reader machine:
291
+ shinobi sync pull
292
+ ```
293
+
294
+ The DB file lands on the `main` branch as a binary; pre-existing local DB is backed up to `<path>.bak-<timestamp>` before restore.
295
+
296
+ ## Configuration
297
+
298
+ Edit `~/.shinobi/.env` or set env vars before running `shinobi mcp`:
299
+
300
+ | Variable | Default | Purpose |
301
+ |---|---|---|
302
+ | `SHINOBI_DB_PATH` | `~/.shinobi/shinobi.db` | SQLite location |
303
+ | `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Config + plugins directory |
304
+ | `SHINOBI_PLUGINS_DIR` | `${configdir}/plugins` | Plugin discovery directory |
305
+ | `SHINOBI_DASHBOARD_PORT` | `8765` | Dashboard port |
306
+ | `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Dashboard bind host. Loopback skips auth; non-loopback auto-enables token auth. |
307
+ | `SHINOBI_DASHBOARD_TOKEN` | _(auto)_ | Override the dashboard token; auto-generated to `~/.shinobi/dashboard-token` when needed. |
308
+ | `SHINOBI_EMBED_PROVIDER` | `none` | `openai` / `voyage` / `ollama` / `none` |
309
+ | `SHINOBI_EMBED_API_KEY` | — | Auth for OpenAI / Voyage (else falls back to `OPENAI_API_KEY` / `VOYAGE_API_KEY`) |
310
+ | `SHINOBI_EMBED_MODEL` | provider default | Override model id |
311
+ | `SHINOBI_EMBED_DIMS` | provider default | Override dimensions |
312
+ | `SHINOBI_OLLAMA_URL` | `http://localhost:11434` | Ollama endpoint |
313
+ | `SHINOBI_MIGRATIONS_DIR` | `<package>/migrations` | Override migrations source |
314
+
315
+ Full reference: [docs/configuration.md](docs/configuration.md).
316
+
317
+ ## Plugins
318
+
319
+ Write a single `.js` file in `~/.shinobi/plugins/`:
320
+
321
+ ```js
322
+ // ~/.shinobi/plugins/my-plugin.js
323
+ export default function register(registry, api) {
324
+ registry.registerTool({
325
+ name: 'plugin_count_open',
326
+ description: 'Count open decisions across all projects',
327
+ inputSchema: { type: 'object', properties: {}, additionalProperties: false },
328
+ handler: (_args, api) => {
329
+ const projects = api.listProjects();
330
+ let total = 0;
331
+ for (const p of projects) {
332
+ total += api.listDecisions({ projectId: p.id, status: 'open' }).length;
333
+ }
334
+ return { open_decisions: total };
335
+ },
336
+ });
337
+ }
338
+ ```
339
+
340
+ Restart the MCP client and `mcp__shinobi__plugin_count_open` is available. See [docs/plugin-development.md](docs/plugin-development.md).
341
+
342
+ ## Roadmap
343
+
344
+ - **v0.1 (current)** — local MCP + dashboard + plugin system + git sync + relay
345
+ + optional embeddings + voice + mobile push + VS Code/Cursor extensions.
346
+ - **v0.2** — multi-user team mode (auth + members + mentions UI), vite/dev-deps
347
+ upgrade, plugin marketplace UI polish, deeper integrations (Linear /
348
+ GitHub Issues sync candidates).
349
+ - **v0.3** — hosted SaaS GA + Stripe billing.
350
+ - **v1.0** — stability, audit, performance pass.
351
+
352
+ ## Changelog
353
+
354
+ See [CHANGELOG.md](CHANGELOG.md) for release notes.
355
+
356
+ ## Contributing
357
+
358
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
359
+
360
+ By participating you agree to our [Code of Conduct](CODE_OF_CONDUCT.md).
361
+
362
+ ## Security
363
+
364
+ For vulnerability reports, see [SECURITY.md](SECURITY.md) — please do
365
+ **not** open public issues for security matters.
366
+
367
+ ## License
368
+
369
+ MIT — see [LICENSE](LICENSE).