Shinobi

Shinobi

AI コーディングエージェントのタスクの背骨です。Shinobi はセッションをまたいで引き継がれる決定事項を保持し、エージェントがコードを書く前に、過去の行き詰まりを意味的に積極検索し、承認をスマートフォンに送信します。ひとつの頭脳を、あらゆるデバイスで共有します。ノート PC、クラウドセッション、モバイルがすべて同じストアにつながります。

Claude Code、Cursor、Cline、Continue.dev、Zed など、MCP 互換クライアントで動作します。

ステータス： v0.3 — 自律エージェント。ホスト型 HTTP /mcp の頭脳（デフォルトのデプロイ）として実行するか、ローカルインスタンスをセルフホストできます。モバイルプッシュ、ヘッドレスのディスパッチループ、git worktree を使った並列スウォーム、リモート MCP の基盤上に構築された audit→subtask 取り込みに対応します。39 個の MCP ツール、ウェブダッシュボード、モバイル承認、プラグインシステム、オプションのセマンティックリコールを備えています。

できること

多くのツールは、メモリを後付けしようとします。Shinobi は、エージェントがそれに沿って作業するタスクの背骨です。単一のセッションが終わっても残り、あらゆるデバイスで使える、作業、決定事項、既知の失敗経路の永続的な基盤です。

• タスクの背骨 — エージェントが担当、完了、または方針転換するプロジェクトとサブタスク。複数セッションにわたる作業の永続的な骨組みです
• 引き継がれる決定事項 — 根拠とともにアーキテクチャ上の選択を記録するため、次のセッション（どのデバイスでも）で同じ議論を蒸し返さずに済みます
• 構築前に検索される行き詰まり — 失敗したアプローチはすべて記録され、エージェントが似たアプローチを計画した瞬間に意味的に照合されるため、同じ壁に再びぶつかってセッションを無駄にすることはありません。これを行うツールはほかにありません
• スマートフォンでの承認 — request_approval が判断をスマートフォンに送信します。どこにいても、はい／いいえをタップするまでエージェントは待機します
• ひとつの頭脳を、あらゆるデバイスで共有 — ノート PC のエディター、Claude Code のクラウドセッション、モバイルチャットが、すべてリモート MCP 経由で同じストアを利用します。同期作業も、デバイスごとの情報のずれもありません
• 計画 — バージョン管理された計画のスナップショットを、タスクの途中で取得できます
• コンテキスト — プロジェクトごとの規約、「触らない」ルール、テストパターン、デプロイに関するメモ、ファイル注釈
• リコール — デフォルトでは全文検索（FTS5）、埋め込みプロバイダーを設定した場合はセマンティック検索（埋め込みベース）
• メモ — 自由形式の注釈と音声メモ（audio_path フィールド）
• アクティビティのタイムライン — すべての書き込みがタイムラインに記録され、何が起きたかを再確認できます
• Git 連携 — link_commit は [SHI-N] タグ、または target_path による帰属を使って、コミットをサブタスクに関連付けます
• ウェブダッシュボード — Hono が提供するカンバン、決定事項、行き詰まり、メモ、計画、コンテキスト、タイムライン、分析
• プラグインシステム — ~/.shinobi/plugins/ に .js ファイルを配置するか、@shinobi/plugin-* npm パッケージをインストールして、カスタムの plugin_* ツールを登録します

ホスト型とセルフホスト、どちらにするかは選べます。 デフォルトのデプロイでは、HTTP /mcp エンドポイントの背後にひとつのリモートの頭脳を置きます（当社では shinobi.shinobi-apps.com で運用しています）。すべてを自分のマシンに置きたい場合、同じバイナリを完全ローカルの単一マシンインスタンスとして実行することもできます。セマンティックリコールを使う場合に限り、埋め込みプロバイダーを用意してください。

🚀 初めてですか？はじめ方に沿って、10 分で使える頭脳をセットアップできます。複数デバイスで使いますか？リモートモードと月額 $0 のクラウドデプロイをご覧ください。

インストール

必要条件：

• PATH 上に Node.js 18 以降
• better-sqlite3 のネイティブビルドに必要な C++ ビルドツールチェーン（多くのシステムにはビルド済みバイナリがあります。Windows では代替手段としてVisual Studio Build Toolsが必要になることがあります）

npm から（推奨）

npm install -g @shinobiapps/shinobi

バイナリ名は shinobi です（例：shinobi serve、shinobi dashboard）。

GitHub から（最新、未リリース）

npm install -g github:numbererikson/shinobi

main から取得します。未リリースの修正を試すのに便利です。Windows では、これを実行する前に Node のディレクトリをシステムの PATH に追加する必要がある場合があります。これは、prepare ビルドスクリプトがサブシェルで実行され、セッションごとの PATH が常に引き継がれるとは限らないためです（Laragon、ポータブルインストール）。'node' is not recognized というエラーでインストールに失敗する場合は、上記の npm インストールをおすすめします。

クローンしたソースフォルダーから（開発／コントリビューション用）

git clone https://github.com/numbererikson/shinobi.git
cd shinobi
npm install            # triggers `prepare` → builds dist/
npm install -g .

次に、初期設定を実行します

MCP クライアントで Shinobi を利用するプロジェクトのルートで、次を実行します。

shinobi init
shinobi dashboard

init は次の処理を行います。

1. config.json、.env テンプレート、shinobi.db（マイグレーション適用済み）を含む ~/.shinobi/ を作成します
2. 現在のプロジェクト用の .mcp.json スニペットを作成します
3. 次の手順を表示します

shinobi init は、初期状態でワークスペースローカルの MCP 方式に従って、次の 2 つのクライアントの設定を書き込みます。

• Claude Code — <workspace>/.mcp.json
• Cursor — <workspace>/.cursor/mcp.json

クライアントを再起動すると、mcp__shinobi__* ツールが利用可能になります。

その他の MCP クライアント（Cline、Continue.dev、Zed）については、以下の MCP クライアントのセットアップセクションを参照してください。

次に、以下を開きます。

http://127.0.0.1:8765

Windows PowerShell でスクリプトの実行がブロックされて shinobi を使えない場合は、.cmd シムを使用します。

shinobi.cmd dashboard

Node をアップグレードした場合や、古い node_modules をコピーした場合は、ネイティブ依存関係を再ビルドしてください。

npm rebuild better-sqlite3

重要：コードは Shinobi フォルダーにありますが、ローカルのメモリデータベースは次の場所にあります。

~/.shinobi/shinobi.db

ツールのみを移動するには、Shinobi フォルダーをコピーまたはクローンして、上記のインストールコマンドを実行してください。既存のプロジェクト、タスク、決定事項、メモ、コンテキストも移動するには、~/.shinobi/ をコピーするか、shinobi sync を使用してください。

MCP クライアントのセットアップ

以下のすべてのスニペットで、同じ JSON 形式を使用します。command は Shinobi を実行している Node バイナリへのパス、args は [<absolute path to dist/cli.js>, "mcp"] です。ご利用の環境で正確な値を表示するには、次を実行します。

shinobi init --print-config

（または、すでに shinobi init を実行した任意のプロジェクトから .mcp.json を読み取ってください。値は同じです。）

Claude Code

自動的に作成されます。shinobi init が <workspace>/.mcp.json に書き込みます。 サーバーを読み込むには Claude Code を再起動してください。

Cursor

自動的に作成されます。shinobi init が <workspace>/.cursor/mcp.json に書き込みます。 Cursor 0.43 以降で動作します。Cursor を再起動するか、ワークスペースを再読み込みしてください。

グローバルな Cursor 設定（すべてのプロジェクトから Shinobi を利用可能にする設定）にするには、同じスニペットを ~/.cursor/mcp.json に貼り付けるか、Cursor Settings → MCP を使用してください。

Cline（VS Code 拡張機能）

Cline の設定ファイルを開きます。

• Windows：%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• macOS：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux：~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

プロジェクトの .mcp.json の内容を、ファイルの mcpServers オブジェクトに統合します。VS Code を再起動してください。

Continue.dev

~/.continue/config.json を編集します。Shinobi を mcpServers 配列に追加してください （注：Continue は他のクライアントのようなオブジェクトではなく、配列を使用します）。

{
  "mcpServers": [
    {
      "name": "shinobi",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/dist/cli.js", "mcp"]
    }
  ]
}

command と args には、プロジェクトの .mcp.json にある値を使用してください。

Zed

~/.config/zed/settings.json を編集します。Zed では MCP サーバーは context_servers の下にネストされます。

{
  "context_servers": {
    "shinobi": {
      "command": {
        "path": "/absolute/path/to/node",
        "args": ["/absolute/path/to/dist/cli.js", "mcp"]
      }
    }
  }
}

Zed を再起動してください。

汎用／その他のクライアント

標準の { command, args } サーバー仕様に対応する MCP クライアントであれば、動作するはずです。.mcp.json にあるのと同じ値を使用してください。

• command：Shinobi を実行している Node バイナリへの絶対パス
• args：[<absolute path to dist/cli.js>, "mcp"]

MCP 設定では、単独の shinobi コマンドを使用しないでください。多くのクライアントは shell: false でサーバーを起動するため、ターミナルで shinobi を実行可能にしている OS の PATH 解決が行われません。

リモートモード（デフォルトのデプロイ）

サーバー上で Shinobi のブレインを 1 つホストし、デスクトップエディター、Claude Code の Web／モバイルセッション、リモート MCP に対応する任意のクライアントなど、すべてのデバイスを接続します。shinobi serve はダッシュボードとともに、/mcp に MCP エンドポイント（ストリーミング可能な HTTP、ステートレス、ベアラートークン認証）を公開します。

claude mcp add --transport http shinobi https://your-host/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

これは Shinobi の実行に推奨される方法です。1 つのブレインに、すべてのデバイスからアクセスできます。すべてを自分のマシンでセルフホストしたい場合は、同じバイナリを単一マシンのローカルインスタンスとして実行することもできます。デプロイガイドの全文（Docker、Cloudflare Tunnel、GCP Always Free、クライアント設定）： docs/remote-mcp.md。

CLI

shinobi <command> [options]

Commands:
  init                            Bootstrap ~/.shinobi/ and drop .mcp.json in the current directory
  mcp                             Run the MCP server over stdio (invoked by the MCP client)
  migrate                         Apply pending SQL migrations
  dashboard                       Start the web dashboard on localhost (default port 8765)
  serve [--host H] [--port P]     Dashboard + MCP HTTP endpoint (/mcp) in one process — see docs/remote-mcp.md
  sync init <path> [branch]       Configure a local git repo as the cross-machine sync target
  sync push                       Snapshot the DB and commit it to the sync repo
  sync pull                       Restore the DB from the sync repo's snapshot
  sync status                     Show last push/pull timestamps and git status
  dispatch [--once|--drain]       Autonomous loop: pull next_task → run worker → complete/unblock → repeat
           [--project N] [--interval S] [--max-failures N]   Worker via SHINOBI_WORKER_CMD (e.g. 'claude -p "$SHINOBI_TASK_PROMPT"'); unset → dry-run
  swarm --agents N                N dispatch loops in parallel, each in its own git worktree/branch, one shared
        [--project N] [--drain]   brain. Atomic claim → no two agents take the same task. --no-worktree / --keep-worktrees

MCP ツール（39）

グループ	ツール
プロジェクト	list_projects, get_project, create_project, update_project, archive_project, unarchive_project, delete_project
サブタスク	list_tasks, get_task, create_task, bulk_create_tasks, update_subtask, delete_subtask, claim_task, complete_task, next_task
決定事項	log_decision, decisions_for_file, update_decision_status
行き詰まり	log_dead_end, check_dead_ends
メモ	add_note, list_notes
プラン	save_plan, get_plan
コンテキスト	get_context, update_context
再検索	recall (FTS5 またはセマンティック)
タイムライン	history, link_commit
ワークフロー	agent_bootstrap, session_closeout, file_context
抽出	extract_decisions, compress_session_summary
承認	request_approval
通知	notify
発見事項	ingest_findings
プラグイン	plugin_hello

アーキテクチャ

レイヤー	技術
言語	TypeScript（strict モード、ES2022、NodeNext）
ランタイム	Node 18+
MCP	@modelcontextprotocol/sdk 1.x
ストレージ	better-sqlite3 経由の SQLite（WAL モード）
ダッシュボード	Hono + @hono/node-server（同一プロセス、localhost:8765）
埋め込み（オプション）	OpenAI text-embedding-3-small / Voyage voyage-3-lite / Ollama nomic-embed-text
マイグレーション	前方のみ、sha256 チェックサム、schema_migrations テーブル

リクエストのライフサイクルとモジュール構成については、docs/architecture.md を参照してください。

ダッシュボード認証

ダッシュボードはループバックバインド（127.0.0.1、localhost、::1）では認証なしで利用でき、ループバック以外のバインドではトークンで保護されます。トークンは SHINOBI_DASHBOARD_TOKEN から読み込まれ、未設定の場合は ~/.shinobi/dashboard-token から読み込まれ、それもない場合は自動生成されてその場所に保存されます。プローブ用の /health は常に認証なしで利用できます。

ブラウザーでの操作 — トークンを付けてダッシュボードを一度開けば、Cookie が保持されます。

http://192.168.1.10:8765/?token=YOUR_TOKEN

Curl／スクリプト — 以下のどれでも使用できます。

curl -H "Authorization: Bearer $SHINOBI_DASHBOARD_TOKEN" http://192.168.1.10:8765/api/projects/1/snapshot
curl -H "X-Shinobi-Token: $SHINOBI_DASHBOARD_TOKEN"      http://192.168.1.10:8765/api/projects/1/snapshot
curl --cookie "shinobi_token=$SHINOBI_DASHBOARD_TOKEN"   http://192.168.1.10:8765/api/projects/1/snapshot

環境変数の詳細については、docs/configuration.md を参照してください。

マシン間同期

Shinobi はプライベートな git リポジトリを使用して、ローカルの SQLite データベースを同期します。マシンごとに一度セットアップしてください。

# Once: clone a private GitHub repo to act as the sync repo
git clone [email protected]:USER/shinobi-sync.git ~/shinobi-sync

# Once per machine: tell shinobi about it
shinobi sync init ~/shinobi-sync main

# Push from the writer machine:
shinobi sync push

# Pull on the reader machine:
shinobi sync pull

DB ファイルは main ブランチにバイナリとして保存されます。復元前に、既存のローカル DB は <path>.bak-<timestamp> にバックアップされます。

設定

shinobi mcp の実行前に、~/.shinobi/.env を編集するか、環境変数を設定してください。

変数	デフォルト	用途
SHINOBI_DB_PATH	~/.shinobi/shinobi.db	SQLite の保存先
SHINOBI_CONFIG_DIR	~/.shinobi	設定とプラグインのディレクトリ
SHINOBI_PLUGINS_DIR	${configdir}/plugins	プラグインの検索ディレクトリ
SHINOBI_DASHBOARD_PORT	8765	ダッシュボードのポート
SHINOBI_DASHBOARD_HOST	127.0.0.1	ダッシュボードのバインド先ホスト。ループバックの場合は認証が省略され、ループバック以外の場合はトークン認証が自動的に有効になります。
SHINOBI_DASHBOARD_TOKEN	(自動)	ダッシュボードのトークンを上書きします。必要に応じて ~/.shinobi/dashboard-token に自動生成されます。
SHINOBI_EMBED_PROVIDER	none	openai / voyage / ollama / none
SHINOBI_EMBED_API_KEY	—	OpenAI / Voyage の認証に使用します（設定されていない場合は OPENAI_API_KEY / VOYAGE_API_KEY にフォールバックします）
SHINOBI_EMBED_MODEL	プロバイダーのデフォルト	モデル ID を上書きします
SHINOBI_EMBED_DIMS	プロバイダーのデフォルト	次元数を上書きします
SHINOBI_OLLAMA_URL	http://localhost:11434	Ollama エンドポイント
SHINOBI_MIGRATIONS_DIR	<package>/migrations	マイグレーションの参照元を上書きします

全項目については、docs/configuration.md を参照してください。

プラグイン

~/.shinobi/plugins/ に単一の .js ファイルを作成します。

// ~/.shinobi/plugins/my-plugin.js
export default function register(registry, api) {
  registry.registerTool({
    name: 'plugin_count_open',
    description: 'Count open decisions across all projects',
    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
    handler: (_args, api) => {
      const projects = api.listProjects();
      let total = 0;
      for (const p of projects) {
        total += api.listDecisions({ projectId: p.id, status: 'open' }).length;
      }
      return { open_decisions: total };
    },
  });
}

MCP クライアントを再起動すると、mcp__shinobi__plugin_count_open が使用可能になります。docs/plugin-development.md を参照してください。

ロードマップ

• v0.2 — リモート MCP の基盤：ステートレスな HTTP /mcp エンドポイント、 Docker と GCP Always Free によるデプロイ、Cloudflare Tunnel、クラウドセッション向けの 環境変数で設定する .mcp.json。ノート PC、クラウド、モバイルで 1 つの脳を共有します。
• v0.3（現在） — 自律型エージェント：プッシュ通知（タスク完了／ エージェントのブロック）→ ディスパッチループ（ヘッドレスエージェントが next_task を取得し、 あなたが眠っている間に作業）→ Shinobi Swarm（並列で動作する N 個のエージェント、ワークツリーによる分離、 行き詰まりの共有）。さらに、v0.4 から前倒しした ingest_findings（監査 → サブタスクグラフ → スウォーム）。
• v0.4 — tools/* の単体テストカバレッジを拡充し、ingest_findings に より充実した修正テンプレートと検出元アダプターを追加します。
• v1.0 — 安定性の向上、セキュリティ監査、パフォーマンス改善。チームモード／ ホスト型 SaaS は、要望があった場合にのみ提供します。

変更履歴

リリースノートについては、CHANGELOG.md を参照してください。

コントリビューション

CONTRIBUTING.md を参照してください。Issue や PR を歓迎します。

参加することで、行動規範に同意したものとみなされます。

セキュリティ

脆弱性の報告については、SECURITY.md を参照してください。セキュリティに関する問題を 公開 Issue として報告しないでください。

ライセンス

MIT — LICENSE を参照してください。