Shinobi

Name: Shinobi
Author: numbererikson

@numbererikson

关于 Shinobi

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

#mcp #task-spine #dead-ends #mobile-approvals #remote-mcp #task-management #memory

基本信息

分类

AI 与智能体

传输方式

stdio

发布者

numbererikson

提交者

Sung Jin-woo

配置

使用下面的配置,将此服务器添加到你的 MCP 客户端。

{
  "mcpServers": {
    "shinobi": {
      "command": "npx",
      "args": [
        "-y",
        "@shinobiapps/shinobi",
        "mcp"
      ]
    }
  }
}

工具

List Shinobi projects with progress. Filter by status, workspace, or include archived. Pass brief=true for a token-light listing (truncated descriptions, no summary blobs) and use get_project for full detail.

Get a single project by id, including its summary fields.

Create a new project. Tag with workspace (e.g. shinobi / shinobiapps / sitesnap) so cross-codebase work stays organised.

Patch a project. Only fields present in the patch are modified.

Mark a project as archived (sets archived_at timestamp).

Restore an archived project (clears archived_at).

Permanently delete a project (cascades to subtasks, decisions, plans, etc.).

List subtasks. Filter by project_id, status, or claude session id.

Get a single subtask by id.

Create a subtask. project_id is optional (null = unrouted inbox task). Title+description are embedded for semantic recall when SHINOBI_EMBED_PROVIDER is configured.

Create multiple subtasks in a single transaction. Useful when seeding a project plan.

Patch a subtask. Rejects circular dependencies. Use status="todo" to reset an in-progress task.

Permanently delete a subtask.

Mark a subtask as in_progress and link the current session. Call BEFORE starting work so resume knows where you left off.

Mark a subtask as done. Optionally pass a summary that will be attached to the linked session. Set notify:true to fire a "task done" mobile push (best-effort, never fails the completion) — meant for headless / dispatch-loop agents; leave false for interactive completes so you do not buzz your own phone.

Pick the highest-priority todo subtask whose dependencies are met. Optionally scoped to a project. Also returns matched dead-end warnings (semantic when SHINOBI_EMBED_PROVIDER is configured).

Record a decision in the durable decision log. Architectural choices, library picks, tradeoffs, workarounds. Embeds summary+rationale for semantic recall when SHINOBI_EMBED_PROVIDER is configured.

Return every decision whose files_touched contains the given path. Useful when opening a file you have not touched in months.

Move a decision through its lifecycle (open / fix_now / fix_later / wontfix / fixed / false_positive). Stamps decided_at automatically on closing states.

Log an approach that demonstrably failed so future sessions do not re-try. Embeds approach+failure_reason for semantic match when SHINOBI_EMBED_PROVIDER is configured.

Preventive search BEFORE implementing an approach. Pass a description and optional file paths. Uses semantic similarity when SHINOBI_EMBED_PROVIDER is configured; otherwise FTS5 + filename overlap. Returns matching past failures.

Add a free-form note. Used for things that do not fit decision/dead_end/task. Body is fulltext-searched by recall(), and embedded for semantic recall when SHINOBI_EMBED_PROVIDER is configured.

List notes ordered newest-first, optionally scoped to a project.

Persist an approved plan as a new versioned snapshot. Auto-increments version per project.

Return the latest plan for a project, or a specific version. Optionally include version history.

Get a project living context: conventions, dont_touch, test_patterns, deploy_notes, file_annotations. Returns null when no context row exists yet.

Patch a project's context. Only fields present in the patch are modified — others preserve their prior value.

Search across decisions, dead ends, notes, and subtask titles/descriptions for a query string. Uses semantic similarity when SHINOBI_EMBED_PROVIDER is configured; otherwise FTS5-backed fulltext. Use this when you have lost the thread on an old project.

Return activity timeline (claim/complete/log_decision/log_dead_end/save_plan/...) ordered newest-first. Optionally scoped to a project, entity, or session.

Link a git commit to a subtask (when commit message contains [SHI-N] tag) or attribute to projects via target_path match. Records to the activity timeline so 'history' shows commits next to claims/completions.

Extract decision drafts from a conversation transcript via LLM (Groq Llama 3.3 by default, free tier). Drafts land in the decision_drafts table with status=pending — the user reviews them in the dashboard and approves to create real decisions via log_decision. Use at session boundaries when you want auto-capture of decisions you may have forgotten to log explicitly. Requires SHINOBI_LLM_PROVIDER + GROQ_API_KEY (or OPENAI_API_KEY).

Compress a project's recent activity + decisions + dead ends into a terse 3-paragraph markdown summary via LLM (Groq Llama 3.3 by default, free tier). When persist=true (default), stores on projects.recent_summary_md so next agent_bootstrap surfaces it as signal instead of raw 270-row noise. Requires SHINOBI_LLM_PROVIDER + GROQ_API_KEY (or OPENAI_API_KEY).

Start an agent work session for a project. Returns project context, latest plan, selected/next task, open decisions, relevant dead ends, recent activity, and file-specific decisions. Optionally claims the task.

Finish an agent work session in one call. Records summary, changed files, completed tasks, decisions, dead ends, optional plan snapshot, and follow-up tasks.

Return guardrail context for files an agent is about to inspect or edit: project context annotations, decisions for each file, relevant dead ends, and recent activity.

List discovered plugins and their registered tools. Use this to verify the plugin system loaded correctly. Plugins are loaded from ~/.shinobi/plugins/*.{js,mjs} (user tier) and node_modules/@shinobi/plugin-* (npm tier).

Block waiting for the user to approve a decision via mobile push notification. Creates an approval row, fires web push to all subscribed devices with action buttons, and polls until the user responds (or timeout). Use when the agent hits a decision point that requires human judgment ("ship to prod?", "drop this feature?", "pick library X or Y?").

Fire-and-forget mobile push to every subscribed device. Unlike request_approval, this does NOT block waiting for a response — use it from a headless / dispatch-loop agent to signal "done while you slept" (kind:"task_completed") or "I am stuck, come look" (kind:"blocked"). Returns a delivery summary; push failures never throw.

Turn a list of audit / linter / code-review findings into a subtask graph the swarm can drain. Severity maps to priority (critical→urgent, high→high, medium→medium, low/info→low). Findings on the same file are chained (depends_on) so they run sequentially — agents never edit one file in parallel — while different files stay independent and fan out. Closes the loop: an AI review generates findings, the swarm fixes them, the dashboard reports done.

概览

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_approval pushes decisions to your phone
One brain, every device: laptop, cloud session, and mobile share the same store
Plugin system: drop-in custom tools via .js files 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.