@shinobiapps/shinobi 0.1.6 → 0.2.0
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/CHANGELOG.md +51 -0
- package/LICENSE +21 -21
- package/README.md +50 -17
- package/dist/cli.js +23 -1
- package/dist/cli.js.map +1 -1
- package/dist/dashboard/auth.d.ts.map +1 -1
- package/dist/dashboard/auth.js +6 -3
- package/dist/dashboard/auth.js.map +1 -1
- package/dist/dashboard/server.d.ts +10 -1
- package/dist/dashboard/server.d.ts.map +1 -1
- package/dist/dashboard/server.js +19 -2
- package/dist/dashboard/server.js.map +1 -1
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +6 -2
- package/dist/lib/db.js.map +1 -1
- package/dist/server/http.d.ts +17 -0
- package/dist/server/http.d.ts.map +1 -0
- package/dist/server/http.js +42 -0
- package/dist/server/http.js.map +1 -0
- package/dist/server/mcp.d.ts +14 -0
- package/dist/server/mcp.d.ts.map +1 -1
- package/dist/server/mcp.js +19 -1
- package/dist/server/mcp.js.map +1 -1
- package/docs/deploy-gcp-free.md +183 -0
- package/docs/getting-started.md +94 -0
- package/docs/remote-mcp.md +132 -0
- package/migrations/0001_initial_schema.sql +284 -284
- package/migrations/0002_activity_and_links.sql +26 -26
- package/package.json +10 -5
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Getting started with Shinobi (local)
|
|
2
|
+
|
|
3
|
+
From zero to an agent that remembers your project — on one machine, no
|
|
4
|
+
cloud, in about ten minutes. When you outgrow one machine, see
|
|
5
|
+
[remote mode](remote-mcp.md) and the
|
|
6
|
+
[$0/month cloud deployment guide](deploy-gcp-free.md).
|
|
7
|
+
|
|
8
|
+
## 1. Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
npm install -g @shinobiapps/shinobi
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Requirements: Node 18+. `better-sqlite3` ships prebuilt binaries for common
|
|
15
|
+
platforms; Windows may need
|
|
16
|
+
[VS Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
|
17
|
+
as a fallback.
|
|
18
|
+
|
|
19
|
+
## 2. Bootstrap your project
|
|
20
|
+
|
|
21
|
+
In your project's root:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
shinobi init
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
This creates `~/.shinobi/` (SQLite database + config) and writes the MCP
|
|
28
|
+
config for your client — `.mcp.json` for Claude Code, `.cursor/mcp.json`
|
|
29
|
+
for Cursor. For Cline / Continue.dev / Zed, print the snippet instead:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
shinobi init --print-config
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Restart your editor / MCP client. Your agent now has 37 `shinobi` tools.
|
|
36
|
+
|
|
37
|
+
## 3. Teach the agent to use its memory
|
|
38
|
+
|
|
39
|
+
Memory only pays off if the agent reads it at the start and writes to it as
|
|
40
|
+
it works. Add this to your project's `CLAUDE.md` (or your client's rules
|
|
41
|
+
file):
|
|
42
|
+
|
|
43
|
+
```markdown
|
|
44
|
+
At the start of each session, call the shinobi `agent_bootstrap` tool for the
|
|
45
|
+
active project to load decisions, dead ends, context and open tasks. Before
|
|
46
|
+
implementing a new approach, call `check_dead_ends`. Log decisions and dead
|
|
47
|
+
ends as you go; call `session_closeout` before finishing.
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## 4. Your first project
|
|
51
|
+
|
|
52
|
+
Tell your agent something like:
|
|
53
|
+
|
|
54
|
+
> Create a shinobi project "Payments refactor" with subtasks for: extract
|
|
55
|
+
> the gateway interface, migrate Stripe calls, add retry logic. Log the
|
|
56
|
+
> decision that we use decimal.js for money math — floats caused rounding
|
|
57
|
+
> bugs.
|
|
58
|
+
|
|
59
|
+
From now on, in any future session, "work on the payments refactor through
|
|
60
|
+
shinobi" gives the agent the full picture: open tasks, decisions with
|
|
61
|
+
rationale, and the approaches that already failed.
|
|
62
|
+
|
|
63
|
+
## 5. The daily loop
|
|
64
|
+
|
|
65
|
+
| Moment | What happens |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| Session start | `agent_bootstrap` — decisions, dead ends, context, open tasks |
|
|
68
|
+
| Before a new approach | `check_dead_ends` — "we tried this, it broke because…" |
|
|
69
|
+
| Architectural choice made | `log_decision` with rationale |
|
|
70
|
+
| Approach failed | `log_dead_end` (optionally `never_retry`) |
|
|
71
|
+
| Session end | `session_closeout` — summary, drafts, timeline entry |
|
|
72
|
+
|
|
73
|
+
## 6. The dashboard
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
shinobi dashboard
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
→ [localhost:8765](http://localhost:8765): Kanban board, decisions, dead
|
|
80
|
+
ends, notes, plans, timeline, analytics. Auth is off on localhost and
|
|
81
|
+
automatic on any other bind.
|
|
82
|
+
|
|
83
|
+
## 7. Where to go next
|
|
84
|
+
|
|
85
|
+
- **Approvals on your phone** — the agent blocks mid-task until you tap
|
|
86
|
+
approve: see the Push page in the dashboard, and `docs/relay.md` for
|
|
87
|
+
multi-machine realtime.
|
|
88
|
+
- **One brain for every device** (desktop editor + Claude Code web/mobile
|
|
89
|
+
sessions): [remote mode](remote-mcp.md), and the field-tested
|
|
90
|
+
[GCP free tier + Cloudflare Tunnel walkthrough](deploy-gcp-free.md).
|
|
91
|
+
- **Backups / second machine**: `shinobi sync` snapshots the database to a
|
|
92
|
+
private git repo (see README → Cross-machine sync).
|
|
93
|
+
- **Plugins**: drop a `.js` file in `~/.shinobi/plugins/` —
|
|
94
|
+
`docs/plugin-development.md`.
|
|
@@ -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.
|