@shinobiapps/shinobi 0.1.6 → 0.2.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 (64) hide show
  1. package/CHANGELOG.md +92 -0
  2. package/LICENSE +21 -21
  3. package/README.md +50 -17
  4. package/dist/cli.js +23 -1
  5. package/dist/cli.js.map +1 -1
  6. package/dist/dashboard/auth.d.ts.map +1 -1
  7. package/dist/dashboard/auth.js +6 -3
  8. package/dist/dashboard/auth.js.map +1 -1
  9. package/dist/dashboard/server.d.ts +10 -1
  10. package/dist/dashboard/server.d.ts.map +1 -1
  11. package/dist/dashboard/server.js +28 -2
  12. package/dist/dashboard/server.js.map +1 -1
  13. package/dist/lib/db.d.ts.map +1 -1
  14. package/dist/lib/db.js +6 -2
  15. package/dist/lib/db.js.map +1 -1
  16. package/dist/lib/migrations.d.ts +2 -0
  17. package/dist/lib/migrations.d.ts.map +1 -1
  18. package/dist/lib/migrations.js +49 -4
  19. package/dist/lib/migrations.js.map +1 -1
  20. package/dist/lib/paths.d.ts +26 -0
  21. package/dist/lib/paths.d.ts.map +1 -0
  22. package/dist/lib/paths.js +68 -0
  23. package/dist/lib/paths.js.map +1 -0
  24. package/dist/lib/rate-limit.d.ts +25 -0
  25. package/dist/lib/rate-limit.d.ts.map +1 -0
  26. package/dist/lib/rate-limit.js +75 -0
  27. package/dist/lib/rate-limit.js.map +1 -0
  28. package/dist/models/decision_drafts.d.ts.map +1 -1
  29. package/dist/models/decision_drafts.js +2 -1
  30. package/dist/models/decision_drafts.js.map +1 -1
  31. package/dist/models/decisions.d.ts.map +1 -1
  32. package/dist/models/decisions.js +12 -3
  33. package/dist/models/decisions.js.map +1 -1
  34. package/dist/models/notes.d.ts.map +1 -1
  35. package/dist/models/notes.js +2 -1
  36. package/dist/models/notes.js.map +1 -1
  37. package/dist/models/subtasks.d.ts.map +1 -1
  38. package/dist/models/subtasks.js +2 -1
  39. package/dist/models/subtasks.js.map +1 -1
  40. package/dist/server/http.d.ts +17 -0
  41. package/dist/server/http.d.ts.map +1 -0
  42. package/dist/server/http.js +42 -0
  43. package/dist/server/http.js.map +1 -0
  44. package/dist/server/mcp.d.ts +14 -0
  45. package/dist/server/mcp.d.ts.map +1 -1
  46. package/dist/server/mcp.js +19 -1
  47. package/dist/server/mcp.js.map +1 -1
  48. package/dist/server/tools/projects.d.ts.map +1 -1
  49. package/dist/server/tools/projects.js +16 -2
  50. package/dist/server/tools/projects.js.map +1 -1
  51. package/dist/server/tools/workflow.d.ts.map +1 -1
  52. package/dist/server/tools/workflow.js +27 -3
  53. package/dist/server/tools/workflow.js.map +1 -1
  54. package/dist/services/auth/magic-link.d.ts.map +1 -1
  55. package/dist/services/auth/magic-link.js +3 -0
  56. package/dist/services/auth/magic-link.js.map +1 -1
  57. package/docs/configuration.md +21 -0
  58. package/docs/deploy-gcp-free.md +205 -0
  59. package/docs/getting-started.md +94 -0
  60. package/docs/recovery-runbook.md +162 -0
  61. package/docs/remote-mcp.md +132 -0
  62. package/migrations/0001_initial_schema.sql +284 -284
  63. package/migrations/0002_activity_and_links.sql +26 -26
  64. package/package.json +11 -5
@@ -0,0 +1,132 @@
1
+ # Remote mode: one Shinobi brain for every device
2
+
3
+ By default Shinobi runs local-first: the MCP server speaks stdio and the
4
+ SQLite database lives in `~/.shinobi/` on one machine. Remote mode exposes the
5
+ same 37 tools over MCP **streamable HTTP** so any MCP client — Claude Code
6
+ (desktop *and* web/mobile sessions), Cursor, Cline, Continue.dev, Zed — can
7
+ share a single brain hosted on a server you control.
8
+
9
+ ```
10
+ laptop: VS Code + Claude Code ──┐
11
+ ├──► https://your-host/mcp ──► one SQLite brain
12
+ phone: Claude Code web session ─┘ (token auth)
13
+ ```
14
+
15
+ Decisions logged from your desk are known to the session you open from your
16
+ phone, and vice versa. Sessions stay disposable; the memory doesn't.
17
+
18
+ ## How it works
19
+
20
+ `shinobi serve` starts the dashboard and mounts the MCP endpoint at `/mcp` in
21
+ the same process (same port). The endpoint is stateless — every POST gets a
22
+ fresh server over the shared tool registry — so it survives restarts and works
23
+ behind load balancers.
24
+
25
+ Auth reuses the dashboard token middleware:
26
+
27
+ - loopback bind (`127.0.0.1`) → auth off, same as the local dashboard
28
+ - any other bind → token auth **on automatically**; clients send
29
+ `Authorization: Bearer <token>`
30
+ - the token comes from `SHINOBI_DASHBOARD_TOKEN`, or is generated once and
31
+ stored at `<config-dir>/dashboard-token`
32
+
33
+ > **Never** expose a non-authenticated bind to the internet. The MCP tools
34
+ > can read and write your entire project memory. Always front the endpoint
35
+ > with HTTPS (reverse proxy or your platform's TLS).
36
+
37
+ > 💸 Want this for $0/month? Follow the step-by-step
38
+ > [GCP free tier + Cloudflare Tunnel walkthrough](deploy-gcp-free.md).
39
+
40
+ ## Quickstart: Docker on a VPS
41
+
42
+ ```bash
43
+ docker build -t shinobi .
44
+ docker run -d --name shinobi --restart unless-stopped \
45
+ -p 127.0.0.1:8765:8765 \
46
+ -v shinobi-data:/data \
47
+ -e SHINOBI_DASHBOARD_TOKEN="$(openssl rand -hex 24)" \
48
+ shinobi
49
+ ```
50
+
51
+ The volume on `/data` is **mandatory in practice** — the SQLite database
52
+ lives there (`SHINOBI_CONFIG_DIR=/data`); without it every restart wipes your
53
+ memory.
54
+
55
+ Then put HTTPS in front, e.g. Caddy:
56
+
57
+ ```
58
+ shinobi.example.com {
59
+ reverse_proxy 127.0.0.1:8765
60
+ }
61
+ ```
62
+
63
+ ## Quickstart: bare Node (no Docker)
64
+
65
+ ```bash
66
+ npm install -g @shinobiapps/shinobi
67
+ SHINOBI_DASHBOARD_TOKEN="$(openssl rand -hex 24)" \
68
+ shinobi serve --host 0.0.0.0 --port 8765
69
+ ```
70
+
71
+ Same rules: non-loopback bind enables token auth; front with HTTPS.
72
+
73
+ ## Connecting clients
74
+
75
+ **Claude Code (CLI / VS Code extension):**
76
+
77
+ ```bash
78
+ claude mcp add --transport http shinobi https://shinobi.example.com/mcp \
79
+ --header "Authorization: Bearer YOUR_TOKEN"
80
+ ```
81
+
82
+ **Claude Code on the web:** add the same URL + header in your environment's
83
+ MCP server configuration.
84
+
85
+ **Cursor / Cline / Continue.dev / Zed** (any client supporting remote MCP):
86
+
87
+ ```json
88
+ {
89
+ "mcpServers": {
90
+ "shinobi": {
91
+ "url": "https://shinobi.example.com/mcp",
92
+ "headers": { "Authorization": "Bearer YOUR_TOKEN" }
93
+ }
94
+ }
95
+ }
96
+ ```
97
+
98
+ **Make every session start informed** — add to your project's `CLAUDE.md`
99
+ (or rules file):
100
+
101
+ ```markdown
102
+ At the start of each session, call the shinobi `agent_bootstrap` tool for the
103
+ active project to load decisions, dead ends, context and open tasks. Before
104
+ implementing a new approach, call `check_dead_ends`. Log decisions and dead
105
+ ends as you go; call `session_closeout` before finishing.
106
+ ```
107
+
108
+ ## Environment reference
109
+
110
+ | Variable | Default | Purpose |
111
+ | --- | --- | --- |
112
+ | `SHINOBI_MCP_HTTP` | `off` | Set `on` to expose `/mcp` from `shinobi dashboard` (the `serve` command implies it) |
113
+ | `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Bind address (`serve --host` overrides) |
114
+ | `SHINOBI_DASHBOARD_PORT` | `8765` | Port (`serve --port` overrides) |
115
+ | `SHINOBI_DASHBOARD_TOKEN` | generated | Bearer token for dashboard + `/mcp` |
116
+ | `SHINOBI_DASHBOARD_AUTH` | auto | `on`/`off` override; auto = on for non-loopback binds |
117
+ | `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Database + config location (Docker image sets `/data`) |
118
+ | `SHINOBI_DB_PATH` | `<config-dir>/shinobi.db` | Explicit database file override |
119
+
120
+ ## FAQ
121
+
122
+ **Does local mode still work?** Yes, nothing changes — stdio (`shinobi mcp`)
123
+ remains the default and the npm install flow is untouched. Remote mode is the
124
+ same binary with a different transport.
125
+
126
+ **Can I keep a local copy of the brain?** Yes — `shinobi sync` (git snapshot
127
+ push/pull) works on the server like anywhere else, so the hosted database can
128
+ be backed up to a private git repo and pulled to any machine.
129
+
130
+ **Multiple people?** Remote mode is designed for one operator across many
131
+ devices. The token grants full read/write; don't share it as a team auth
132
+ scheme.