Shinobi
@numbererikson
Shinobi gives every AI coding agent on your machine — and every cloud Claude session — one shared task spine, decision log, and searched dead-ends ledger. Every failed approach is logged and semantically checked before an agent proposes a similar one, so agents stop repeating mis
Overview
What is Shinobi?
Shinobi is a task spine for AI coding agents that persists decisions, tracks work across sessions, and searches past dead ends semantically before the agent writes code. It works with any MCP-compatible client (Claude Code, Cursor, Cline, Continue.dev, Zed) and can run as a local instance or a hosted remote brain accessible from every device.
How to use Shinobi?
Install the npm package globally, run shinobi init in your project root to bootstrap the local database and config, then start the web dashboard with shinobi dashboard. The init command automatically writes .mcp.json for Claude Code and Cursor; other clients require manual configuration using the same command/args values. For multi-device setups, deploy shinobi serve as an HTTP MCP endpoint with bearer token auth.
Key features of Shinobi
- Task spine: projects and subtasks that persist across sessions
- Decisions that survive: record architectural choices with rationale
- Semantic dead-end search: matches similar failed approaches before new code
- Mobile approvals:
request_approvalpushes decisions to your phone - One brain, every device: laptop, cloud session, and mobile share the same store
- Plugin system: drop-in custom tools via
.jsfiles or npm packages
Use cases of Shinobi
- Multi-session coding projects where context must survive between work sessions
- Multi-device workflows: switch between laptop editor, cloud agent, and mobile approvals seamlessly
- Avoiding repeated mistakes by semantically checking logged dead ends before each task
- Collaborative approvals: a blocking tool pushes a yes/no request to a developer’s phone
- Audit and ingestion: extract past decisions and compress session summaries into the brain
FAQ from Shinobi
How is Shinobi different from a memory tool?
Shinobi is a task spine, not just a memory bolt-on. It actively searches past dead ends semantically before the agent writes code, holds multi-session decisions, and routes approvals to your phone—capabilities no other tool provides.
What are the installation requirements?
Node.js 18+ and a C++ build toolchain for better-sqlite3 (most systems have prebuilt binaries; Windows may need Visual Studio Build Tools). Optional: an embedding provider (OpenAI, Voyage, or Ollama) for semantic recall.
Where does Shinobi store its data?
All project, task, decision, dead-end, and context data is stored locally in ~/.shinobi/shinobi.db (SQLite, WAL mode). The database can be moved by copying the entire ~/.shinobi/ folder or using shinobi sync.
What transports and authentication does Shinobi support?
Shinobi runs as a stdio MCP server (for local clients) or as a streamable HTTP MCP server (for remote access) with bearer token authentication. The serve command exposes both the MCP endpoint at /mcp and the web dashboard on the same process.
Can I run Shinobi both locally and as a hosted service?
Yes. The default deploy is a remote brain behind an HTTP /mcp endpoint (e.g., shinobi.shinobi-apps.com). The same binary runs as a fully local single-machine instance when you prefer to keep everything on your own box.
