@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.
@@ -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.