timps-swarm

install-mcp コマンドを 1 つ実行するだけで、あらゆるコーディングツールに 161 の AI 専門エージェントを導入できます。MCP ツールだけでなく、並列サブエージェントとして利用できます。

クイックスタート · サブエージェント · 161 のエージェント · MCP のセットアップ · CLI · アーキテクチャ

エージェント 4 つを逐次ではなく並列に実行 — 3 倍高速化（64 秒対 192 秒）

機能

• あらゆるリポジトリを 30 秒でセキュリティ監査 — npx timps-swarm audit ./ で CVE、ハードコードされたシークレット、OWASP の問題を検出します。バックエンド、設定、API キーは不要です。
• あらゆる AI ツールで 161 の専門エージェントを利用 — install-mcp コマンドを 1 つ実行すると、9 つの IDE（Claude Code、Cursor、Windsurf、Continue、Aider、Cline、Zed、VS Code、Gemini、Codex、Amp、Warp）の MCP 設定を書き込みます。さらに、すべてのエージェントをネイティブのサブエージェントとして登録するので、Claude Code／Cursor／Codex は Task(subagent_type=...) を使って並列に実行できます。
• ローカル優先、BYOK — Ollama で API コストなしに実行できます。より高い性能が必要な場合は、Gemini／Anthropic／OpenAI／Groq を接続できます。
• Python バックエンドなしでも動作 — npm install -g timps-swarm には、実行中の FastAPI サーバー（ローカル、または TIMPS_API_URL によるリモート）と通信する Node.js MCP stdio プロキシ（cli/lib/mcp-proxy.js）が含まれています。Python リポジトリは任意です。

クイックスタート

npm i -g timps-swarm

このリポジトリをコーディングエージェントに渡せば、自動でセットアップされます。 SETUP.md は単なるドキュメントではなく、手順書として書かれています。ユーザーが リポジトリをクローンし、Claude Code、opencode、Codex、Cursor、Windsurf、 その他のエージェントに「SETUP.md を読んでセットアップして」と指示すると、 エージェントがバックエンドをインストールし、実行中のツールに timps-swarm MCP サーバーを登録して、161 の専門エージェントを並列に実行します。

次に、コーディングエージェントに接続します。

npx timps-swarm install-mcp

install-mcp はマシン上の AI ツールを自動検出し、次の処理を行います。

1. 検出したすべての IDE 設定に timps-swarm MCP サーバーの項目を書き込みます（ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、GROQ_API_KEY、TIMPS_API_URL、OLLAMA_HOST、REDIS_URL を転送する env: ブロックを明示的に設定します）。
2. TIMPS ツールごとにサブエージェントの .md ファイルを 1 つずつ、~/.claude/agents/、./.claude/agents/、~/.codex/agents/ に書き込みます。

ツールを再起動すると、161 のエージェントが MCP ツールおよび並列サブエージェントとして利用可能になります。

インストールせずに実行（セットアップ不要）：

npx timps-swarm audit ./          # security scan any repo — works immediately

install が実際に行うこと

必要なコマンドは install-mcp だけです。

npx timps-swarm install-mcp                  # default: configure all detected tools
npx timps-swarm install-mcp --no-sub-agents  # MCP config only, skip the .md files
npx timps-swarm install-mcp --tool cursor    # configure one tool
npx timps-swarm install-mcp --dry-run        # preview without writing
npx timps-swarm uninstall-mcp                # remove all of the above

デフォルトでは、次の内容を書き込みます。

• MCP サーバーの項目を 9 つの IDE 設定ファイルに追加します（IDE ごとに 1 つの項目を作成し、すべて npx timps-swarm mcp を指定します）。
• 161 個のサブエージェント .md ファイルを ~/.claude/agents/、./.claude/agents/、~/.codex/agents/ に書き込みます（MCP ツールごとに 1 つ）。これにより、Claude Code の Task(subagent_type="timps_kubernetes_navigator")、Cursor Composer、Codex からエージェントを並列に実行できます。

すべての書き込みは冪等です（再実行すると既存のファイルが更新されます）。また、uninstall-mcp で元に戻せます（削除されるのは timps-swarm キーと timps-*.md ファイルだけで、ほかの設定には影響しません）。

注目のコマンド

# Security audit — secrets + CVEs + SAST, no backend, no API key
npx timps-swarm audit ./

# Full 10-agent SDLC pipeline on any codebase
npx timps-swarm fix ./src --language python

# Generate a complete OpenAPI spec from plain English
npx timps-swarm api-design "billing API with metered usage and Stripe webhooks"

# Design a DB schema with DDL, ER diagram, and migrations
npx timps-swarm db-design "multi-tenant SaaS with usage-based billing"

# Diagnose your machine (12 specialist agents)
npx timps-swarm health

MCP 連携

npx timps-swarm install-mcp            # auto-detect and configure all installed tools
npx timps-swarm install-mcp --tool cursor    # single tool only
npx timps-swarm install-mcp --dry-run        # preview without writing files

{
  "mcpServers": {
    "timps-swarm": {
      "command": "npx",
      "args": ["timps-swarm", "mcp"],
      "env": {
        "GEMINI_API_KEY": "...",
        "ANTHROPIC_API_KEY": "..."
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "timps-swarm": { "type": "stdio", "command": "npx", "args": ["timps-swarm", "mcp"] }
    }
  }
}

{ "mcpServers": [{ "name": "timps-swarm", "command": "npx", "args": ["timps-swarm", "mcp"] }] }

mcp-servers:
  timps-swarm:
    command: npx
    args: [timps-swarm, mcp]
    type: stdio

{
  "assistant": {
    "mcp_servers": {
      "timps-swarm": { "command": "npx", "args": ["timps-swarm", "mcp"] }
    }
  }
}

extensions:
  - name: timps-swarm
    type: stdio
    cmd: npx timps-swarm mcp
    enabled: true

jobs:
  generate:
    uses: Sandeeprdy1729/timps-swarm/.github/workflows/timps-swarm.yml@main
    with:
      task: "Build a microservice for JWT authentication"
      language: python
    secrets:
      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

LLM プロバイダー

優先順位に従ってプロバイダーを試し、利用可能な最初のものを使用します。

export GEMINI_API_KEY=...      # free tier, fastest start
export ANTHROPIC_API_KEY=...   # optional

# Trigger the full SDLC pipeline
python3 give_work.py "Build a rate-limited REST API for user authentication"
# PM → Architect → Code → Review → QA → Security → Perf → Docs → DevOps

# Run a computer health checkup
npx timps-swarm health
python3 give_work.py "My laptop fan is always running"

# Delegate a multi-step goal
npx timps-swarm delegate "fix the auth bug and ensure 80% test coverage"

# Call any of the 161 directly from the CLI
npx timps-swarm mcp   # then use any MCP client

CLI

npm install -g timps-swarm   # or: npx timps-swarm <command>

COMMANDS
  audit <path>           Security audit — secrets + CVEs + SAST (works offline)
  fix <path>             Run the full 10-agent SDLC pipeline
  research <topic>       Research a topic before writing code
  api-design <desc>      Generate an OpenAPI 3.1 spec from plain English
  db-design <desc>       Design a database schema with DDL + ER diagram
  n8n <desc>             Generate a complete n8n workflow JSON
  refactor [path]        Detect code smells + produce refactored version
  test-data <schema>     Generate realistic seed / fixture data
  monitor <service>      Prometheus + Grafana + alerting config
  ui <desc>              UI component spec + code + accessibility audit
  cost <arch>            Cloud cost estimate + savings recommendations
  critique <content>     Score output 1-10, auto-improve until threshold
  health                 Computer health checkup (12 agents)
  providers              Show configured LLM providers
  install-mcp            Auto-configure TIMPS in 9 AI tools + 161 sub-agents
  uninstall-mcp          Remove the MCP config and 161 sub-agent .md files
  start [--repo <path>]  Start the TIMPS Swarm API server (port 8000)
  mcp   [--repo <path>]  Start the MCP stdio server (Python or Node.js fallback)

FLAGS (install-mcp)
  --tool <id>            Only configure one IDE (claude-code, cursor, codex-cli, …)
  --no-sub-agents        Skip writing 161 sub-agent .md files (MCP config only)
  --dry-run              Preview without writing anything
  --silent               Suppress output (postinstall)

ENV VARS
  TIMPS_API_URL          API server URL (default http://localhost:8000)
                         Set to a remote URL to point every tool call at it.
  TIMPS_REPO             Explicit path to the Python repo for backend commands
  GEMINI_API_KEY         Free tier — fastest start
  ANTHROPIC_API_KEY      Optional
  OPENAI_API_KEY         Optional
  GROQ_API_KEY           Optional
  OLLAMA_HOST            Default http://localhost:11434
  REDIS_URL              Default redis://localhost:6379/0

timps-swarm mcp が呼び出されたときにディスク上に Python リポジトリがない場合は、同梱の cli/lib/mcp-proxy.js に透過的にフォールバックします。これは、すべてのツール呼び出しを ${TIMPS_API_URL}/mcp/tools/call に転送する Node.js 製の JSON-RPC 2.0 stdio プロキシです。そのため、FastAPI サーバーに接続できる環境であれば、npm install -g timps-swarm だけで動作する MCP サーバーを利用できます。

アーキテクチャ

                          User / AI coding tool
                          (Claude Code, Cursor, Codex, …)
                                       │
              ┌────────────────────────┼────────────────────────┐
              │ stdio JSON-RPC 2.0     │                        │
              ▼                        ▼                        ▼
  ┌──────────────────────┐   ┌──────────────────────┐   ┌────────────────────┐
  │ mcp_server/server.py │   │ cli/lib/mcp-proxy.js │   │     src/main.py    │
  │  Python — 161 tools, │   │  Node.js fallback    │   │  FastAPI + WS      │
  │  full MCP sampling   │   │  (npm-only path)     │   │  /swarm/run,       │
  │                      │   │                       │   │  /agents/*,        │
  │                      │   │                       │   │  /mcp/tools,       │
  │                      │   │                       │   │  /mcp/tools/call,  │
  │                      │   │                       │   │  /health, /ws      │
  └──────────┬───────────┘   └──────────┬───────────┘   └──────────┬─────────┘
             │                          │                          │
             │      TOOLS / dispatch   │   POST /mcp/tools/call    │
             │ ◀───────────────────────┴──────────────────────────▶│
             │                                                     │
             │      mcp_server/server._TOOL_HANDLERS              │
             │              (161 tools, in-process)                │
             └─────────────────────────┬───────────────────────────┘
                                       │
                              Swarm Bridge
                                       │
       ┌───────────────────┬──────────┴──────────┬───────────────────┐
       ▼                   ▼                     ▼                   ▼
  SDLC DAG          Health Graph          Specialist Agents      Context / Kernel
  (10 nodes)        (12 nodes)            (120 direct calls)     (3 nodes)
       │                   │                     │                   │
       └───────────────────┴─────────────────────┴───────────────────┘
                                       │
                                  LLM Router
       ┌─────────────┬─────────────────┼─────────────┬───────────────┐
       ▼             ▼                 ▼             ▼               ▼
   Gemini        Anthropic         OpenAI         Groq          Ollama
   2.5 Flash      Claude           GPT-4o       Llama 3.3       (local)
                                                            + TIMPS-Coder 0.5B

次の 3 つのトランスポート経路は、同じディスパッチテーブルに集約されます。

1. Python MCP stdio（mcp_server/server.py）— MCP サンプリングに完全対応し、プロセス内で動作する 161 個のツールを提供します。Python リポジトリがディスク上にある場合に使用されます。
2. Node.js MCP stdio プロキシ（cli/lib/mcp-proxy.js）— tools/list と tools/call を実行中の FastAPI サーバーに転送する、純粋な stdio JSON-RPC 2.0 プロキシです。npm パッケージのみがインストールされている場合（Python リポジトリがない場合）に使用されます。
3. FastAPI REST + WebSocket（src/main.py）— /swarm/run、/agents/*、/health、/ws に加え、ブリッジ用エンドポイントの /mcp/tools（カタログ）と /mcp/tools/call（ディスパッチ）を提供します。

レイヤー 1 — コンピューターマネージャー（src/layer1_computer_manager.py）— 隔離された作業ディレクトリと、エージェントごとの CPU／メモリ／ディスクの上限を管理します。

レイヤー 2 — Swarm ブリッジ（src/layer2_swarm_bridge.py）— エージェントのライフサイクルを管理します。起動、チーム編成、LangGraph DAG の実行、結果の収集を行います。

レイヤー 3 — CLI（src/layer3_swarm_cli.py）— give_work.py と npm CLI を提供します。

REST API

curl http://localhost:8000/health
curl http://localhost:8000/health/full   # deep check with provider status

curl -X POST http://localhost:8000/swarm/run \
  -H "Content-Type: application/json" \
  -d '{"request": "Fix SQL injection in my FastAPI endpoint", "language": "python"}'

curl -X POST http://localhost:8000/agents/refactor \
  -d '{"code": "...", "language": "python", "goals": ["reduce_complexity"]}'

curl http://localhost:8000/providers

# MCP bridge (used by cli/lib/mcp-proxy.js)
curl http://localhost:8000/mcp/tools                                       # full 161-tool catalogue
curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "timps_list_agents", "arguments": {}}'                      # call any tool over HTTP

wscat -c ws://localhost:8000/ws   # real-time stream

サーバーの実行中は、http://localhost:8000/docs で対話型のドキュメントをすべて確認できます。

カスタムアダプターのトレーニング

コード生成ツールは、バグクラスごとに 1 つ、計 20 個の LoRA アダプターを備えた 0.5B モデル TIMPS-Coder を使用します。サンプルを追加してプッシュすると、GitHub Actions が新しいアダプターを自動的にトレーニングします。

cp my_bugs.jsonl datasets/custom/
git add datasets/custom/my_bugs.jsonl
git commit -m "feat: 40 new Python async bug examples"
git push origin main

リポジトリのシークレットに HF_TOKEN と HF_REPO_ID を設定してください。パイプラインはデータを統合し、Apple Silicon（MLX）上で 20 個のアダプターを並列トレーニングして、ベンチマークを実行し、HuggingFace に公開します。

20 個のバグクラス別アダプター： java_npe · java_ioob · java_concurrent · python_keyerror · python_typeerror · python_recursion · python_async · python_logic · javascript_null · javascript_scope · javascript_async · cpp_memory · cpp_bounds · go_routine · rust_borrow · sql_injection · xss_vuln · auth_bypass · performance_slow · api_design

ハードウェア

セキュリティ

API キー認証はデフォルトで無効です。チームで共有する場合は有効にしてください。

TIMPS_AUTH=1 make up-local
python3 give_work.py --keygen "sandeep-laptop"   # generate key (shown once)
python3 give_work.py --revoke timps-sk-xxxx       # revoke a key

キーは SHA-256 ハッシュとして ~/.timps/.secrets に保存されます（chmod 600）。

コントリビューション

main ブランチへの PR を歓迎します。Conventional Commits に従ってください。

git clone https://github.com/Sandeeprdy1729/timps-swarm
cd timps-swarm && pip install -e ".[dev]"
make up-local    # starts the FastAPI server on :8000

現在、make test は何も実行しません。tests/ が空のためです。実行可能な既存のテストスクリプトはトップレベルにあります（python3 mcp_server/test_server.py、python3 test_computer_allocation.py）。pytest に頼る前に、tests/ ディレクトリを追加し、pyproject.toml に接続してください。

Lint：ruff check .（pyproject.toml で設定済み。make lint ターゲットはありません）。型チェック：設定されていません。Python ≥ 3.10、CI では 3.11 に固定されています。