timps-swarm

只需一条 install-mcp 命令，即可将 161 位 AI 专家部署到你使用的所有编码工具中——作为并行子 Agent，而不仅仅是 MCP 工具。

快速开始 · 子 Agent · 161 位 Agent · MCP 配置 · CLI · 架构

并行派遣 4 个 Agent 与顺序执行相比，速度提升 3 倍（64 秒对比 192 秒）

功能

• 30 秒内审计任意代码库 — npx timps-swarm audit ./ 可查找 CVE、硬编码密钥和 OWASP 问题。无需后端、无需配置、无需 API 密钥。
• 在所有 AI 工具中使用 161 位专家 Agent — 一条 install-mcp 命令即可为 9 款 IDE（Claude Code、Cursor、Windsurf、Continue、Aider、Cline、Zed、VS Code、Gemini、Codex、Amp、Warp）写入 MCP 配置，并且将每个 Agent 注册为原生子 Agent，让 Claude Code / Cursor / Codex 能通过 Task(subagent_type=...) 并行派遣它们。
• 本地优先，自带密钥（BYOK） — 使用 Ollama 运行，API 费用为零；需要更强性能时，可接入 Gemini/Anthropic/OpenAI/Groq。
• 无需 Python 后端也能运行 — npm install -g timps-swarm 会提供 Node.js MCP stdio 代理（cli/lib/mcp-proxy.js），可连接到任意正在运行的 FastAPI 服务（本地服务或通过 TIMPS_API_URL 指定的远程服务）。Python 代码库为可选项。

快速开始

npm i -g timps-swarm

将此代码库交给任意编码 Agent，它就会自动完成配置。 SETUP.md 是一组操作指令（而非单纯的文档）——当用户 克隆代码库并告诉 Claude Code、opencode、Codex、Cursor、Windsurf， 或任何其他 Agent“读取 SETUP.md 并帮我完成配置”时，该 Agent 会安装 后端，为其正在运行的工具注册 timps-swarm MCP 服务， 并开始并行派遣 161 位专家 Agent。

接下来，将其接入你的编码 Agent：

npx timps-swarm install-mcp

install-mcp 会自动检测你机器上的所有 AI 工具，并执行以下操作：

1. 将 timps-swarm MCP 服务条目写入每个检测到的 IDE 配置（并通过显式的 env: 块传递 ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、GROQ_API_KEY、TIMPS_API_URL、OLLAMA_HOST、REDIS_URL）。
2. 为每个 TIMPS 工具创建一个子 Agent .md 文件，写入 ~/.claude/agents/、./.claude/agents/ 和 ~/.codex/agents/。

重启工具后，161 个 Agent 将同时作为 MCP 工具和并行子 Agent 出现。

无需安装即可运行（零配置）：

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 一个条目，均指向 npx timps-swarm mcp）。
• 161 个子 Agent .md 文件：写入 ~/.claude/agents/、./.claude/agents/、~/.codex/agents/（每个 MCP 工具对应一个），这样 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——这是一个 Node.js JSON-RPC 2.0 stdio 代理，会将每次工具调用转发到 ${TIMPS_API_URL}/mcp/tools/call。因此，只要能够访问 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

三种传输路径汇聚到同一个分发表：

1. Python MCP stdio（mcp_server/server.py）——完整支持 MCP 采样，在进程内运行，包含 161 个工具。Python 仓库在磁盘上时使用。
2. Node.js MCP stdio 代理（cli/lib/mcp-proxy.js）——纯 stdio JSON-RPC 2.0 代理，将 tools/list + tools/call 转发到正在运行的 FastAPI 服务。只安装了 npm 软件包（没有 Python 仓库）时使用。
3. FastAPI REST + WebSocket（src/main.py）——/swarm/run、/agents/*、/health、/ws，以及桥接端点 /mcp/tools（目录）和 /mcp/tools/call（分发）。

第 1 层——Computer Manager（src/layer1_computer_manager.py）——隔离工作目录，并为每个 Agent 限制 CPU、内存和磁盘用量。

第 2 层——Swarm Bridge（src/layer2_swarm_bridge.py）——Agent 生命周期管理：生成、组队、执行 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 查看完整的交互式文档。

训练自定义适配器

代码生成器使用 TIMPS-Coder——一个 0.5B 模型，配备 20 个 LoRA 适配器，每种错误类型对应一个。添加示例并推送后，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。