limps

limps

Local Intelligent MCP Planning Server — AI アシスタント向けのドキュメントおよび計画レイヤーです。サブスクリプションもクラウドも不要です。任意のフォルダー（ローカル、同期済み、または Git 内）を limps に指定できます。Claude、Cursor、Codex、および MCP 互換ツール間で、共有された唯一の信頼できる情報源を利用できます。

目次

• クイックスタート
• 機能
• limps の使い方
• 健全性と自動化
• 活用方法
• limps を使う理由
• インストール
• v2 からのアップグレード
• プロジェクトのセットアップ
• クライアントのセットアップ
• トランスポート
• デーモンの管理
• CLI コマンド
• 設定
• 環境変数
• トラブルシューティング
• MCP ツール
• スキルとコマンド
• 拡張機能
• Obsidian との互換性
• 開発
• 本番環境での使用例
• 機能計画の作成
• 詳細
• MCP とは？
• ライセンス

クイックスタート

# Install globally
npm install -g @sudosandwich/limps

# Initialize in your project
cd ~/Documents/my-planning-docs
limps init

# Start the HTTP daemon
limps server start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Ready for MCP client connections

# Generate MCP client config
limps config print --client claude-code
# Copy the output to your MCP client config file

これで完了です。AI アシスタントが HTTP トランスポート経由でドキュメントにアクセスできるようになりました。フォルダーはローカル、同期済み、リポジトリ内など、どこにあってもかまいません。limps は Git リポジトリや plans/ ディレクトリを必要としません。

ヒント： limps server status には、常にシステム全体のデーモン検出結果が含まれます。プロジェクト設定が見つかった場合（または --config で渡された場合）は、設定されたプロジェクトの接続先も、システム全体の一覧と照合して調整されます。

機能

• 任意の Markdown ファイルフォルダーに対応したドキュメントの CRUD と全文検索
• ステータス追跡とタスクスコアリングを備えた計画およびエージェントのワークフロー
• スコアの内訳とバイアス調整に対応した次のタスクの提案
• process_doc(s) ヘルパーによるサンドボックス化されたドキュメント処理
• Cursor、Claude、Codex などに対応した複数クライアントのサポート
• 分野固有のツールに対応した拡張機能（例：limps-headless）
• ナレッジグラフ — エンティティ抽出、ハイブリッド検索、競合検出、グラフベースの提案
• 健全性の自動化 — 古さの検出、コードの乖離チェック、ステータスの推定、自動修正の提案
• 高度なタスクスコアリング — プランやエージェントごとの重みの上書きに対応した、依存関係を考慮した優先順位付け
• MCP レジストリ — 公式 MCP レジストリ（registry.modelcontextprotocol.io）に公開済み

始める前に知っておくこと

• ローカルのみ — データはディスク上に保存されます（SQLite インデックス＋ファイル）。クラウドもサブスクリプションも不要です。
• 変更後は再起動 — インデックス対象のフォルダーまたは設定を変更した場合は、MCP サーバーを再起動するか、ファイルウォッチャーに任せて、インデックスとツールに現在の状態を反映してください。
• デーモンの管理 — HTTP サーバーはバックグラウンドプロセスとして実行されます。limps server start、limps server stop、limps server statusを使って、デーモンのライフサイクルを管理します。PID ファイルは、システム全体で認識できるよう、OS 標準のディレクトリに保存されます。
• サンドボックス化されたユーザーコード — process_docとprocess_docsは、時間とメモリに制限を設けた QuickJS サンドボックス内で JavaScript を実行します。ネットワークや Node API は使用できません。
• 任意のネットワーク呼び出しは1回のみ — limps version --checkは npm レジストリからバージョンを取得して比較します。それ以外のすべてのコマンド（serve、init、list、search、ドキュメントの作成／更新／削除、process_doc など）はインターネットに接続しません。外部への呼び出しを一切行いたくない場合は、version --checkを省略してください。

limps の使い方

私はlimpsを、複数の AI ツールで使用するローカルな計画レイヤーとして使い、計画とタスクの作成 → 読み取り → 更新 → 完了に重点を置いています。MCP サーバーは任意のディレクトリ（git リポジトリでなくてもかまいません）を参照するため、どのクライアントも同じ信頼できる情報源を読み取り、更新できます。

一般的な流れ：

1. limps の参照先をドキュメントディレクトリ（ローカルでも同期済みでも、任意のフォルダー）に設定します。
2. CLI と MCP ツールを使って計画やドキュメントを作成し、現在の状態を読み取り、タスクを更新し、作業が終わったら完了にします。
3. 各クライアントの設定に limps の MCP エントリーを追加して、Cursor／Claude／Codex が同じ計画を参照できるようにします。

よく使うコマンドとツール：

• 作成：limps init、create_plan、create_doc
• 読み取り：list_plans、list_agents、list_docs、search_docs、get_plan_status
• 更新：update_doc、update_task_status、manage_tags
• 完了：update_task_status（例：PASS）、必要に応じてdelete_doc
• 分析：graph health、graph search、graph check、health check

一覧は「CLI Commands」と「MCP Tools」を参照してください。

利用方法

limpsは汎用的で、さまざまな環境に移植できるよう設計されています。Markdown ファイルを含む任意のフォルダーを参照先に設定し、MCP 対応クライアントから利用できます。git リポジトリは不要です。 計画だけに限定されません—計画（計画、エージェント、タスクの状態）は用途の1つです。同じレイヤーで、インデックス対象の任意のフォルダーに対するドキュメントの CRUD、全文検索、プログラム可能な処理も行えます。

一般的な構成：

• 単一プロジェクト：製品ごとに1つのドキュメントフォルダーを使用します。
• 複数プロジェクト：各プロジェクトに独自の.limps/config.jsonを用意し、特定のプロジェクトを対象にするには--configを指定します。
• チーム共有フォルダー：共有の場所に計画を置き、コードと同じように変更をレビューします。
• ローカルファースト：すべてをディスク上に保持でき、ホスト型サービスは不要です。

主な考え方：

• 任意のフォルダー — パスは自由に選べます。plans/サブディレクトリがない場合は、ディレクトリ全体がインデックス化されます。汎用ツール（list_docs、search_docs、create_doc、update_doc、delete_doc、process_doc、process_docs）または計画専用ツール（create_plan、list_plans、list_agents、get_plan_status、update_task_status、get_next_task）を使います。
• 信頼できる情報源は1つ — MCP ツールによって構造化されたアクセスが可能になり、複数のクライアントで同じドキュメントを共有できます。

limps を選ぶ理由

課題： AI アシスタントごとに独自のコンテキストを保持しています。計画ドキュメント、タスクの状態、決定事項が、Claude、Cursor、ChatGPT、Copilot での会話に分散してしまいます。

解決策： limps は、どのツールからもアクセスできる標準化された MCP インターフェースを提供します。ドキュメントは、選択した1か所のフォルダーに保存されます。バージョン管理が必要であれば git（または任意の同期手段）を使えます。limps はリポジトリに依存しません。

インストール

npm install -g @sudosandwich/limps

v2 からのアップグレード

v3 では大幅な変更が導入されます：

HTTP トランスポート（破壊的変更）

v3 ではHTTP トランスポートのみを使用します。stdio トランスポートは削除されました。

移行手順：

1. 各プロジェクトでHTTP デーモンを起動します：

   limps server start --config /path/to/.limps/config.json
   

2. MCP クライアントの設定を更新します — stdio の設定を HTTP トランスポートに置き換えます：

   {
     "mcpServers": {
       "limps-planning-myproject": {
         "transport": {
           "type": "http",
           "url": "http://127.0.0.1:4269/mcp"
         }
       }
     }
   }
   

   limps config print を使って、正しいスニペットを生成してください。

プロジェクトごとの設定（破壊的変更）

v3 では一元管理されたプロジェクトレジストリが削除されます。以前 limps config add、config use、または --project フラグを使用していた場合は、次の手順に従ってください。

1. 各プロジェクトのディレクトリで limps init を実行し、.limps/config.json を作成します。
2. MCP クライアントの設定を更新します — --project <name> を HTTP トランスポート設定に置き換えます（上記を参照）。
3. 環境変数を削除します — LIMPS_PROJECT は存在しなくなりました。設定パスを上書きするには MCP_PLANNING_CONFIG を使用してください。

削除されたコマンド： config list、config use、config add、config remove、config set、config discover、config migrate、config sync-mcp、serve。

置き換え後： limps init + limps server start + limps config print。

プロジェクトのセットアップ

新しいプロジェクトを初期化する

cd ~/Documents/my-planning-docs
limps init

これにより、現在のディレクトリに .limps/config.json が作成され、MCP クライアントのセットアップ手順が表示されます。

パスを指定することもできます：

limps init ~/Documents/my-planning-docs

ディレクトリに plans/ サブディレクトリがある場合、limps はそれを使用します。ない場合は、ディレクトリ全体をインデックス化します。

複数のプロジェクト

各プロジェクトには独自の .limps/config.json があります。特定のプロジェクトを対象にするには --config を使用してください：

limps plan list --config ~/docs/project-b/.limps/config.json

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

limps init を実行した後、MCP クライアントの設定ファイルに limps のエントリを追加する必要があります。limps config print を使用してクライアントに合ったスニペットを生成し、適切な設定ファイルに貼り付けてください：

limps config print --client cursor
limps config print --client claude-code
limps config print --client claude

出力には、追加する JSON（または TOML）の内容と設定ファイルの場所が示されます。

クライアントごとの例

すべてのクライアントは HTTP デーモンに接続します。まず limps server start でデーモンを起動してから、クライアントを設定してください。

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

[mcp_servers.limps-planning-myproject.transport]
type = "http"
url = "http://127.0.0.1:4269/mcp"

limps config print --client chatgpt

トランスポート

limps v3 では、永続的なデーモンを介したHTTP トランスポートのみを使用します。これにより、複数の MCP クライアントで単一のサーバーインスタンスを共有でき、stdio プロセスの複数起動によるファイルディスクリプターの増加を防げます。

HTTP デーモンを起動する

# Start the daemon
limps server start

# Check status (shows uptime, sessions, PID)
limps server status

# Stop the daemon
limps server stop

デーモンはデフォルトで http://127.0.0.1:4269/mcp で実行されます。limps config print を使って、正しい MCP クライアント設定を生成してください：

limps config print --client claude-code

ライフサイクルの詳細については、デーモンの管理を参照してください。

MCP クライアントの設定

すべてのクライアントで HTTP トランスポートを使用します。設定例：

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

サーバー設定オプション

config.json に "server" セクションを追加して、HTTP サーバーをカスタマイズします。

カスタムサーバー設定の例：

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

注： PID ファイルは、OS 標準のアプリケーションディレクトリに保存されます。

• macOS：~/Library/Application Support/limps/pids/
• Linux：$XDG_DATA_HOME/limps/pids/ または ~/.local/share/limps/pids/
• Windows：%APPDATA%/limps/pids/

これにより、limps server status はどのディレクトリからでもシステム全体のデーモンを検出できます。現在のディレクトリに limps の設定が見つかった場合（または --config で指定された場合）、CLI はそのプロジェクトで設定されたターゲットも報告し、調整します。

• リモートクライアント：リモートクライアント（例：ChatGPT）には、MCP 互換の HTTPS プロキシを使用してください。

デーモン管理

limps v3 は、システム全体を認識する永続的な HTTP デーモンを使用します。PID ファイルは OS 標準のディレクトリに保存されるため、システム内のどのディレクトリからでもデーモンを管理、検出できます。

PID ファイルの保存場所

PID ファイルは、プラットフォーム固有のアプリケーションデータディレクトリに保存されます。

macOS：

~/Library/Application Support/limps/pids/

Linux：

$XDG_DATA_HOME/limps/pids/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/pids/

Windows：

%APPDATA%/limps/pids/

各 PID ファイルにはポート番号が付けられ（limps-{port}.pid）、システム全体から検出できるようになっています。PID ファイルの構造例：

{
  "pid": 12345,
  "port": 4269,
  "host": "127.0.0.1",
  "startedAt": "2026-02-08T12:00:00.000Z",
  "configPath": "/path/to/project/.limps/config.json",
  "logPath": "/Users/you/Library/Application Support/limps/logs/limps-4269.log"
}

ポート番号に基づくこの命名により、設定ファイルがなくても limps server status ですべてのプロジェクトにまたがる実行中のデーモンを検出できます。

デーモンログは、OS 標準のアプリケーションログディレクトリに書き込まれます。

macOS：

~/Library/Application Support/limps/logs/

Linux：

$XDG_DATA_HOME/limps/logs/
# or if XDG_DATA_HOME is not set:
~/.local/share/limps/logs/

Windows：

%APPDATA%/limps/logs/

デーモンログには意図的に運用情報のみが記録されます。limps は捕捉されなかった例外や拒否のペイロードを編集し、生の AI プロンプト／応答の内容は保存しません。 デーモンログファイルは追記専用で、自動ローテーションされません。長時間稼働するデーモンを使用する場合は、システムのツールでこれらのファイルをローテーションするか、内容を切り詰めてください。

デーモンの起動

バックグラウンドモード（デフォルト）：

limps server start
# → Daemon starts on http://127.0.0.1:4269/mcp
# → PID file written to OS-standard location
# → Logs written to OS-standard log file (append mode)
# → Process detaches and runs in background

フォアグラウンドモード（デバッグ用）：

limps server start --foreground
# → Runs in foreground (blocks terminal)
# → Logs appear in stderr
# → Useful for debugging startup issues
# → Still creates PID file for discovery

カスタムポート／ホスト（設定による指定）：

.limps/config.json で server.port と server.host を設定します。

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0"
  }
}

次に、通常どおり起動します。

limps server start
# → Starts using server.port/server.host from config
# → PID file: limps-8080.pid

start コマンドは /health エンドポイントに対して HTTP リクエストを繰り返し送信し、最大 5 秒間ポーリングしてヘルスチェックを行います。ヘルスチェックの各リクエストには、それぞれ短いタイムアウト（例：約 1000ms）が設定されています。この間にいずれかのリクエストが失敗すると、次のいずれかのエラーコードが表示されます。

• TIMEOUT — 1 回のヘルスチェック HTTP リクエストが、そのリクエストに設定されたタイムアウト（例：約 1000ms）を超えました。デーモンの起動が遅いか、システムリソースが不足している可能性があります。ログを確認するには、limps server start --foreground を試してください。
• NETWORK_ERROR — デーモンに接続できません。ポートがブロックされているか、別のプロセスによってすでに使用されている可能性があります。
• NON_200_STATUS — ヘルスエンドポイントが 200 以外のステータスコードを返しました。フォアグラウンドモードでデーモンログを確認してください。
• INVALID_RESPONSE — ヘルスエンドポイントは応答しましたが、応答が無効であるか、想定どおりに解析できませんでした（例：形式が不正、または必須フィールドが欠落）。

デーモンの状態を確認する

プロジェクト設定あり（グローバル検出と照合）：

# From within a project directory with .limps/config.json
limps server status
# Project target:
# limps server is running
# PID: 12345 | 127.0.0.1:4269
# Uptime: 2h 15m
# Sessions: 3
# Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# Project target is present in system-wide daemon discovery.
# System-wide daemons:
# 127.0.0.1:4269 (PID 12345) [project target]
#   Uptime: 2h 15m | Sessions: 3
#   Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log

# Or specify config explicitly
limps server status --config /path/to/.limps/config.json

プロジェクト設定なし（グローバル検出のみ）：

# From a directory without a limps config
cd /tmp
limps server status
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
#   Log: /Users/you/Library/Application Support/limps/logs/limps-4269.log
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1
#   Log: /Users/you/Library/Application Support/limps/logs/limps-8080.log

現在のディレクトリで limps server status が設定ファイルを解決できず（かつ --config が指定されていない場合）、グローバルデーモンの検出結果のみを報告します。設定ファイルが見つかった場合は、設定済みのプロジェクトの接続先とグローバルデーモンの一覧の両方を報告します。

デーモンを停止する

# From the project directory (where your .limps config lives):
limps server stop
# → Gracefully shuts down daemon
# → Closes all MCP sessions
# → Stops file watchers
# → Removes PID file
# → Process exits

# Or from any directory, by specifying the config explicitly:
limps server stop --config /path/to/.limps/config.json

stop コマンドはプロジェクト固有で、停止するデーモンを特定するために設定を解決します。デーモンは以下の手順で正常にシャットダウンします。

1. アクティブな MCP セッションをすべて閉じます
2. ファイルウォッチャーをシャットダウンします
3. PID ファイルを削除します
4. プロセスを終了します

ポートの競合

すでに使用中のポートでデーモンを起動しようとすると、limps が競合を検出し、解決方法を案内します。

limps server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)
# Command: /usr/local/bin/node /usr/local/bin/limps server start
#
# To stop the process: kill 12345
# Or use a different port: limps server start --port <port>

lsof が利用可能なシステム（macOS、Linux）では、limps はポートを使用しているプロセスを特定し、そのコマンドラインを表示できます。lsof が利用できない場合は、別のポートを指定するよう案内する簡潔なエラーメッセージが表示されます。

フォアグラウンドモード

デバッグ、Docker デプロイ、CI/CD パイプラインでは、フォアグラウンドモードを使用してください。

limps server start --foreground

使用例：

• デバッグ — サーバーのログをリアルタイムで確認し、起動時の問題を診断します
• Docker — デーモンをメインプロセスとして実行し、コンテナーを起動状態に保ちます
• CI/CD — バックグラウンドプロセスを使わずに、limps デーモンに対してテストを実行します

バックグラウンドモードとの動作の違い：

• ログを出力せずに実行する代わりに、stderr にログを出力します
• ターミナルを占有します（停止するには Ctrl+C を押します）
• 他のプロセスが検出できるよう、PID ファイルも作成します
• SIGINT（Ctrl+C）と SIGTERM を受け取り、正常にシャットダウンします

ヘルスエンドポイント

HTTP デーモンは、監視とヘルスチェック用に /health エンドポイントを公開します。

curl http://127.0.0.1:4269/health

レスポンスの例：

{
  "status": "ok",
  "sessions": 3,
  "uptime": 8145,
  "pid": 12345,
  "sessionTimeoutMs": 1800000
}

HTTP ステータスコード：

• 200 — デーモンは正常で、接続を受け付けています
• 429 — レート制限を超過しました（リクエストが /health に到達する前に、レートリミッターがこのステータスを返す場合があります）

セッション管理と再接続

セッションは、30 分間操作がないと自動的に期限切れになります（sessionTimeoutMs で設定可能）。セッションが期限切れになると、MCP クライアントは再接続が必要であることを示す特定のエラーレスポンスを受け取ります。

セッション期限切れのレスポンス：

セッションが期限切れになるか閉じられた場合、そのセッション ID を使った後続のリクエストは次の内容を返します。

{
  "error": "Session expired",
  "code": "SESSION_EXPIRED",
  "message": "Session expired due to timeout. Please reconnect without session ID.",
  "expiredAt": "2026-02-11T10:30:00.000Z"
}

ヘッダー：

• X-Session-Expired: true
• X-Session-Expired-Reason: timeout（または closed、deleted）

MCP クライアントの再接続フロー：

SESSION_EXPIRED を受け取った場合、クライアントは次の手順を実行してください。

1. 保存済みのセッション ID を消去する — キャッシュされた mcp-session-id を削除します
2. 新しいセッションを作成する — セッション ID ヘッダーを付けずに /mcp に POST を送信します
3. 新しいセッション ID を保存する — レスポンスヘッダーから新しい mcp-session-id を保存します
4. 元のリクエストを再試行する — 新しいセッション ID を付けて再送信します

設定：

.limps/config.json でセッションのタイムアウトを調整します。

{
  "server": {
    "sessionTimeoutMs": 3600000  // 1 hour (default: 1800000 = 30 min)
  }
}

0 に設定すると、タイムアウトが無効になり（サーバーが再起動するまでセッションが維持されます）。

期限切れセッションの追跡：

サーバーは、クライアントが「セッションが期限切れになった」場合と「セッションが一度も存在しなかった」場合を区別できるよう、期限切れセッションを 24 時間追跡します。

• SESSION_EXPIRED — セッションは以前存在していましたが、タイムアウトしました（クライアントは再接続してください）
• SESSION_NOT_FOUND — セッション ID は一度も有効ではありませんでした（サーバーの再起動または無効な ID の可能性があります）

このエンドポイントは、次の用途に使用します。

• スクリプトやダッシュボードでデーモンの状態を監視する
• MCP クライアントの接続前にデーモンが実行中であることを確認する
• オーケストレーションツール（Kubernetes、Docker Compose）で自動ヘルスチェックを行う

複数のデーモン

各プロジェクトの設定で異なるポートを指定することで、異なるプロジェクト用に複数の limps デーモンを別々のポートで実行できます。

# Project A with default port (4269)
cd ~/projects/project-a
# .limps/config.json has server.port: 4269 (or uses default)
limps server start
# → Running on http://127.0.0.1:4269/mcp

# Project B with custom port (8080)
cd ~/projects/project-b
# .limps/config.json has server.port: 8080
limps server start
# → Running on http://127.0.0.1:8080/mcp

各デーモンには、それぞれ独自の PID ファイルがあります。

• limps-4269.pid — プロジェクト A
• limps-8080.pid — プロジェクト B

実行中のすべてのデーモンを検出します（limps の設定がないディレクトリから実行してください）。

cd /tmp
limps server status
# Found 2 running daemons:
# 127.0.0.1:4269 (PID 12345)
#   Uptime: 2h 15m | Sessions: 3
# 127.0.0.1:8080 (PID 67890)
#   Uptime: 45m 30s | Sessions: 1

各 MCP クライアントは、設定ファイルで異なる URL を指定することで、異なるデーモンに接続できます。

CLI コマンド

推奨されるグループ化コマンド

limps plan list                              # List all plans with status
limps plan agents <plan>                     # List agents in a plan
limps plan status <plan>                     # Show plan progress summary
limps plan next <plan>                       # Get highest-priority available task
limps plan score --plan <plan> --agent <n>  # Score a single task
limps plan scores --plan <plan>              # Score all available tasks in a plan
limps docs list [path]                       # List files/directories
limps docs search <query>                    # Search indexed docs
limps docs process [path] --code "<js>"      # Process docs with JavaScript
limps server start                           # Start HTTP daemon
limps server status                          # Show daemon status
limps server stop                            # Stop HTTP daemon

プロジェクト管理

limps init [path]             # Initialize new project
limps config show             # Display current config
limps config print            # Print MCP client config snippets
limps completion zsh          # Generate Zsh tab-completion script

ヘルスチェックと自動化

limps health check              # Aggregate all health signals
limps health staleness [plan]   # Find stale plans/agents
limps health inference [plan]   # Suggest status updates
limps proposals [plan]           # List auto-fix proposals
limps proposals apply <id>       # Apply a proposal
limps proposals apply-safe       # Apply all safe proposals

ナレッジグラフ

limps graph reindex              # Build/rebuild graph
limps graph health               # Graph stats and conflicts
limps graph search <query>       # Search entities
limps graph trace <entity>       # Trace relationships
limps graph entity <id>          # Entity details
limps graph overlap              # Find overlapping features
limps graph check [type]         # Run conflict detection
limps graph suggest <type>       # Graph-based suggestions
limps graph watch                # Watch and update incrementally

スコアリングと修復

limps plan scores --plan <plan>                # Score all agents in a plan
limps plan score --plan <plan> --agent <n>   # Score a single task
limps plan repair [--fix]                   # Check/fix agent frontmatter

設定

設定はプロジェクトディレクトリ内の .limps/config.json にあり、limps init によって作成されます。

設定オプション

{
  "plansPath": "./plans",
  "docsPaths": ["."],
  "fileExtensions": [".md"],
  "dataPath": ".limps/data",
  "extensions": ["@sudosandwich/limps-headless"],
  "tools": {
    "allowlist": ["list_docs", "search_docs"]
  },
  "scoring": {
    "weights": { "dependency": 40, "priority": 30, "workload": 30 },
    "biases": {}
  }
}

環境変数

優先順位： config.tools は環境変数を上書きします。許可リストが設定されている場合、拒否リストは無視されます。

トラブルシューティング

デーモンが起動しない

「ポートはすでに使用されています」エラー：

このエラーが表示された場合、別のプロセスがそのポートを使用しています。

limps server start
# Error: Port 4269 is already in use.
# Process using port: node (PID 12345)

解決方法：

1. 既存のプロセスを終了する： kill 12345
2. または、別のポートを使用する： limps server start --port 8080
3. 別の limps デーモンかどうかを確認する： limps server status（該当する場合は、先に limps server stop を実行してください）

「デーモンの起動に失敗した可能性があります」エラー：

デーモンが起動しても、ヘルスチェックに応答しない場合：

limps server start
# Error: Daemon may have failed to start. Check logs or try: limps server start --foreground

解決方法：

1. デーモンのログパスを確認する： limps server status（またはフォアグラウンドモードで実行する：limps server start --foreground）
2. 権限の問題を確認する： PID ディレクトリへの書き込み権限があることを確認します
3. ポートにアクセスできることを確認する： curl http://127.0.0.1:4269/health を試します
4. デバッグログを有効にする： DEBUG=1 limps server start --foreground

PID ディレクトリの権限に関する問題：

PID ファイルを作成できない場合：

# macOS
ls -la ~/Library/Application\ Support/limps/pids/

# Linux
ls -la ~/.local/share/limps/pids/

# Windows
dir %APPDATA%\limps\pids

ディレクトリが存在し、書き込み権限があることを確認してください。そうでない場合は、手動で作成します。

# macOS
mkdir -p ~/Library/Application\ Support/limps/pids

# Linux
mkdir -p ~/.local/share/limps/pids

# Windows
mkdir %APPDATA%\limps\pids

ヘルスチェックの失敗

TIMEOUT エラー：

デーモンが、設定されたタイムアウト時間内に応答しませんでした。ヘルスチェックの各リクエストには、それぞれタイムアウト時間が設定されています（たとえば、最終的な limps server start の確認時は1000ms、limps server status では3000msです）。起動中、limps は「Daemon may have failed to start」と報告するまで、約5秒間ポーリングします。

よくある原因：

• システムリソースの不足（CPU／メモリ使用率が高い）
• ファイルシステムの処理が遅い（特にインデックスの初期化時）
• インデックス作成が必要なドキュメントコーパスが大きい

解決方法：

1. システムリソースを確認します：top または Activity Monitor
2. 少し待ってから再試行します：limps server status
3. フォアグラウンドで実行して進行状況を確認します：limps server start --foreground

NETWORK_ERROR：

デーモンへの接続を確立できません。

よくある原因：

• ファイアウォールによってポートがブロックされている
• 起動後にデーモンがクラッシュした
• ホスト／ポートの設定が正しくない

解決方法：

1. デーモンが実行中か確認します：limps server status
2. ポート4269のファイアウォール設定を確認します
3. curl http://127.0.0.1:4269/health を手動で実行してみます
4. デーモンのログを確認します：limps server status の出力にある Log: のパスを参照してください

古い PID ファイル

limps は、次の場合に古い PID ファイルを自動的に削除します：

• limps server status の実行時（古いファイルを検出して削除します）
• limps server start の実行時（対象ポートの古いファイルを削除します）
• limps server stop によってデーモンが正常にシャットダウンしたとき

PID ファイルを手動で削除する必要がある場合：

# macOS
rm ~/Library/Application\ Support/limps/pids/limps-*.pid

# Linux
rm ~/.local/share/limps/pids/limps-*.pid

# Windows
del %APPDATA%\limps\pids\limps-*.pid

手動で削除する場合：

• システムのクラッシュまたは強制終了の後
• limps server start がデーモンの実行中と報告するものの、実際には実行されていない場合
• limps をアンインストールする前

複数のデーモンの競合

同じポートで2つ目のデーモンを誤って起動しようとした場合：

limps server start
# Error: limps daemon already running (PID 12345 on 127.0.0.1:4269). Run 'limps server stop' first.

これは想定される動作です。limps は PID ベースのロックを使用して、同じポートで複数のデーモンが起動するのを防ぎます。

解決方法：

1. 実行中のすべてのデーモンを確認します：limps server status
2. 既存のデーモンを停止します：limps server stop
3. または、別のポートで起動します：limps server start --port 8080

接続の問題のデバッグ

MCP クライアントがデーモンに接続できない場合は、次の手順で接続を確認します：

1. デーモンの状態を確認します：

limps server status
# Should show daemon running with healthy status

2. ヘルスエンドポイントを確認します：

curl http://127.0.0.1:4269/health
# Should return JSON with status "ok"

3. MCP エンドポイントを確認します：

curl -X POST http://127.0.0.1:4269/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
# Should return MCP initialize response

4. デバッグログを有効にします：

DEBUG=1 limps server start --foreground
# Watch for connection attempts and errors

5. MCP クライアントの設定を確認します：

クライアントの設定にある URL がデーモンと一致していることを確認してください：

{
  "mcpServers": {
    "limps-planning-myproject": {
      "transport": {
        "type": "http",
        "url": "http://127.0.0.1:4269/mcp"
      }
    }
  }
}

設定の解決に関する問題

問題：limps が誤った設定ファイルを使用している

limps config path に予期しない設定ファイルが表示される場合は、診断コマンドを使用して原因を確認します：

limps config show-resolution

このコマンドでは、設定の解決における3つの優先順位がすべて表示されます：

1. CLI の --config 引数（最優先）
2. MCP_PLANNING_CONFIG 環境変数（2番目の優先順位）
3. ローカルの .limps/config.json（cwd から上位ディレクトリを検索）

よくある原因：

• 環境変数が設定されている：シェルまたは IDE で MCP_PLANNING_CONFIG が設定されているか確認してください。この環境変数はローカルの設定ファイルより優先されます。

  # Check if set
  echo $MCP_PLANNING_CONFIG
  
  # Unset if needed
  unset MCP_PLANNING_CONFIG
  

• 作業ディレクトリが正しくない：設定ファイルの検索は、現在の作業ディレクトリから始まります。limps コマンドを実行するときに、正しいディレクトリにいることを確認してください。

  # Check current directory
  pwd
  
  # Navigate to your project
  cd /path/to/your/project
  

• .limps/config.json が存在しない：設定ファイルはプロジェクトのルートではなく、.limps サブディレクトリ内にある必要があります。

  # Correct location
  /path/to/project/.limps/config.json
  
  # Wrong - won't be found
  /path/to/project/config.json
  

簡単な解決方法：

# Override with explicit path
limps plan list --config /path/to/project/.limps/config.json

# Or set environment variable
export MCP_PLANNING_CONFIG=/path/to/project/.limps/config.json

# Or initialize a new config in current directory
limps init

MCP ツール

limps は AI アシスタント向けに MCP ツールを公開しています。

ナレッジグラフ

ナレッジグラフは、計画ドキュメントを構造化し、クエリ可能な表現にします。6 種類のエンティティ（プラン、エージェント、機能、ファイル、タグ、概念）と、それらの関係（所有、依存、変更、タグ付け、概念上のリンク）を抽出します。競合の特定、依存関係の追跡、グラフに基づく提案の取得に利用できます。

# Build the graph from plan files
limps graph reindex

# Check graph health and conflicts
limps graph health --json

# Search entities
limps graph search "auth" --json

# Trace relationships
limps graph trace plan:0042 --direction down

# Detect conflicts (file contention, circular deps, stale WIP)
limps graph check --json

# Get graph-based suggestions
limps graph suggest dependency-order

詳細は、ナレッジグラフのアーキテクチャとCLI リファレンスをご覧ください。

ヘルスチェックと自動化

limps には、問題を検出して修正を提案する自動ヘルスチェックが含まれています。

• 古さ — 設定可能なしきい値を超えて更新されていないプランやエージェントにフラグを付けます
• コードの乖離 — エージェントのフロントマターが、存在しなくなったファイルを参照している場合に検出します
• ステータスの推定 — 依存関係の完了状況と本文の内容に基づいて、ステータスの変更を提案します
• 提案 — すべての提案を集約し、レビューして適用できる修正として提示します

limps health check --json        # Run all checks
limps proposals apply-safe       # Auto-apply safe fixes

スキルとコマンド

このリポジトリには、.claude/commands/ に Claude Code のスラッシュコマンドと、skills/limps-planning に Vercel Skills のスキルが含まれています。

Claude Code コマンド（limps が作業ディレクトリの場合、自動的に使用できます）：

Vercel Skills（他の AI IDE 向け）：

limps の計画作成、エージェントのワークフロー、タスク管理に関する AI によるガイダンスを利用するには、limps planning スキルをインストールしてください。

# Install only the limps planning skill (recommended for consumers)
npx skills add https://github.com/sudosandwich/limps/tree/main/.claude/skills/limps-plan-operations

# Or install all available skills
npx skills add sudosandwich/limps

利用可能なスキル：

上記の npx skills add でインストールされる .claude/skills パッケージの完全なマニフェストは skills.yaml を参照してください。このリポジトリにある別個の skills/limps-planning/ パッケージはレガシーな配布方法であり、新しい利用者には .claude/skills 方式を推奨します。

拡張機能

拡張機能は MCP ツールとリソースを追加します。npm からインストールしてください。

npm install -g @sudosandwich/limps-headless

設定に追加します。

{
  "extensions": ["@sudosandwich/limps-headless"],
  "limps-headless": {
    "cacheDir": "~/Library/Application Support/limps-headless"
  }
}

利用可能な拡張機能：

• @sudosandwich/limps-headless — ヘッドレス UI の契約抽出、セマンティック分析、ドリフト検出（Radix UI および Base UI の移行）。

Obsidian 連携

@sudosandwich/limps-obsidian-plugin パッケージは、Obsidian との高度な連携機能を提供します。

• limps デーモンへの 永続的な MCP セッション。自動再接続、キープアライブ、CLI フォールバックに対応
• ドキュメント管理 — Obsidian 内から計画ドキュメントを作成、更新、削除
• タスク管理 — 次のタスクの取得、タスクのステータス（GAP／WIP／PASS／BLOCKED）の更新
• 検索と提案 — 全文検索、提案のレビュー、安全な修正タイプの自動適用
• ヘルスハブ — デーモン、グラフ、リンク、MCP のステータスを表示するサイドバービュー
• 有向グラフビュー — クリック可能なノードを備えた、インタラクティブな 2D／3D 力学的グラフ
• スケジュールされたヘルスチェック — 定期的な陳腐化、ドリフト、競合の検出
• Vault の自動化 — 計画ファイルの変更時に自動で再インデックスし、イベント駆動で更新
• エディター診断 — インラインリンクの検証
• Obsidian の形式（.md、.canvas、.base）への グラフ同期

YAML フロントマターの完全なサポート、タグ管理（フロントマターとインラインの #tag）、.obsidian/、.git/、node_modules/ の自動除外に対応しています。

セットアップ手順、コマンド、設定のリファレンスについては、packages/limps-obsidian-plugin/README.md を参照してください。

開発

git clone https://github.com/paulbreuler/limps.git
cd limps
npm install
npm run build
npm test

これは、次のパッケージを含むモノレポです。

• packages/limps — コア MCP サーバー
• packages/limps-headless — ヘッドレス UI 拡張機能（Radix/Base UI コントラクトの抽出と監査）

本番環境での使用

limps は、計画用に別のフォルダー（この場合は git リポジトリ）を使って、runi の計画を管理します。

機能計画の作成

最も手早い方法は、/create-feature-plan スラッシュコマンド（Claude Code）を使うことです。番号付け、ドキュメントの作成、MCP ツールを介したエージェント向けの自動要約を処理します。仕様全体については、.claude/commands/create-feature-plan.md をご覧ください。

同じ手順を MCP ツールで手動実行することもできます。

1. list_plans → 次の計画番号を確認
2. create_plan → 計画ディレクトリをひな形から作成
3. create_doc → 計画、インターフェース、README、エージェントファイルを追加
4. update_task_status → 進捗を追跡

計画は次のレイアウトに従います。

NNNN-descriptive-name/
├── README.md
├── NNNN-descriptive-name-plan.md
├── interfaces.md
└── agents/
    ├── 000_agent_infrastructure.agent.md
    ├── 001_agent_feature-a.agent.md
    └── ...

番号付きのプレフィックスにより、計画とエージェントは辞書順に並びます。get_next_task は、エージェント番号（および依存関係と作業量のスコア）を使って、次に取り組むタスクを提案します。

詳細

plans/
├── 0001-feature-name/
│   ├── 0001-feature-name-plan.md    # Main plan with specs
│   ├── interfaces.md                 # Interface contracts
│   ├── README.md                     # Status index
│   └── agents/                       # Task files
│       ├── 000-setup.md
│       ├── 001-implement.md
│       └── 002-test.md
└── 0002-another-feature/
    └── ...

---
status: GAP | WIP | PASS | BLOCKED
persona: coder | reviewer | pm | customer
depends_on: ["000-setup"]
files:
  - src/components/Feature.tsx
---

{
  "scoring": {
    "biases": {
      "plans": { "0030-urgent-feature": 20 },
      "personas": { "coder": 5, "reviewer": -10 },
      "statuses": { "GAP": 5, "WIP": -5 }
    }
  }
}

await process_doc({
  path: "plans/0001-feature/plan.md",
  code: `
    const features = extractFeatures(doc.content);
    return features.filter(f => f.status === 'GAP');
  `,
});

await process_doc({
  path: "plans/0001/plan.md",
  code: "extractFeatures(doc.content)",
  sub_query: "Summarize each feature",
  allow_llm: true,
  llm_policy: "force", // or 'auto' (skips small results)
});

# Run Agent

Start work on the next available task.

## Instructions

1. Use `get_next_task` to find the highest-priority task
2. Use `process_doc` to read the agent file
3. Use `update_task_status` to mark it WIP
4. Follow the agent's instructions

MCP とは？

Model Context Protocol は、AI アプリケーションが外部システムに接続するための標準化されたプロトコルです。2024 年 11 月に Anthropic が発表し、現在は Linux Foundation の Agentic AI Foundation の一部となっています。

• MCP の仕様
• MCP のドキュメント

ライセンス

MIT