Timps Swarm

One npm install puts 160 AI specialists into every coding tool you use — as parallel sub-agents, not just MCP tools.

npm License: MIT Python 3.11+ MCP Protocol Discord

Quick Start · Sub-agents · 160 Agents · MCP Setup · CLI · Architecture

4 agents dispatched in parallel vs sequential — 3× speedup (64s vs 192s)

What it does

• Security audit any repo in 30 seconds — npx timps-swarm audit ./ finds CVEs, hardcoded secrets, and OWASP issues. No backend, no config, no API key.
• 160 specialist agents in every AI tool — one install-mcp command writes the MCP config for 9 IDEs (Claude Code, Cursor, Windsurf, Continue, Aider, Cline, Zed, VS Code, Gemini, Codex, Amp, Warp) and registers every agent as a native sub-agent so Claude Code / Cursor / Codex can dispatch them in parallel via Task(subagent_type=...).
• Local-first, BYOK — runs on Ollama with zero API cost; plug in Gemini/Anthropic/OpenAI/Groq when you want more power.
• Works without the Python backend — npm install -g timps-swarm ships a Node.js MCP stdio proxy (cli/lib/mcp-proxy.js) that talks to any running FastAPI server (local or remote via TIMPS_API_URL). The Python repo is optional.

Quick Start

npm i -g timps-swarm

Postinstall auto-detects every AI tool on your machine and:

1. Writes the timps-swarm MCP server entry into every detected IDE config (with an explicit env: block forwarding ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, TIMPS_API_URL, OLLAMA_HOST, REDIS_URL).
2. Writes one sub-agent .md file per TIMPS tool into ~/.claude/agents/, ./.claude/agents/, and ~/.codex/agents/.

Restart your tool — 160 agents appear as MCP tools and as parallel sub-agents.

Run without installing (zero setup):

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

What install actually does

install-mcp is the only command you need:

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

By default this writes:

• MCP server entries into 9 IDE config files (one entry per IDE, all pointing at npx timps-swarm mcp).
• 160 sub-agent .md files into ~/.claude/agents/, ./.claude/agents/, ~/.codex/agents/ (one per MCP tool) so Claude Code's Task(subagent_type="timps_kubernetes_navigator"), Cursor Composer, and Codex can dispatch them in parallel.

All writes are idempotent (re-running updates the existing file) and reversible via uninstall-mcp (which only removes the timps-swarm key and the timps-*.md files — your other config is untouched).

The killer commands

# 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 integrations

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 providers

Tries providers in priority order, uses the first available one.

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 160 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 + 160 sub-agents
  uninstall-mcp          Remove the MCP config and 160 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 160 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 (skip auto-detection)
  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

If timps-swarm mcp is invoked but no Python repo is on disk, it transparently falls back to the bundled cli/lib/mcp-proxy.js — a Node.js JSON-RPC 2.0 stdio proxy that forwards every tool call to ${TIMPS_API_URL}/mcp/tools/call. So npm install -g timps-swarm is enough to get a working MCP server, as long as a FastAPI server is reachable.

Architecture

                          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 — 160 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              │
             │              (160 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

Three transport paths converge on the same dispatch table:

1. Python MCP stdio (mcp_server/server.py) — full MCP sampling, in-process, 160 tools. Used when the Python repo is on disk.
2. Node.js MCP stdio proxy (cli/lib/mcp-proxy.js) — pure stdio JSON-RPC 2.0 that proxies tools/list + tools/call to a running FastAPI server. Used when only the npm package is installed (no Python repo).
3. FastAPI REST + WebSocket (src/main.py) — /swarm/run, /agents/*, /health, /ws, plus the bridge endpoints /mcp/tools (catalogue) and /mcp/tools/call (dispatch).

Layer 1 — Computer Manager (src/layer1_computer_manager.py) — isolated working directories, CPU/memory/disk caps per agent.

Layer 2 — Swarm Bridge (src/layer2_swarm_bridge.py) — agent lifecycle: spawning, team formation, LangGraph DAG execution, result collection.

Layer 3 — CLI (src/layer3_swarm_cli.py) — give_work.py and the 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 160-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

Full interactive docs at http://localhost:8000/docs when the server is running.

Training custom adapters

The Code Generator uses TIMPS-Coder — a 0.5B model with 20 LoRA adapters, one per bug class. Add examples and push — GitHub Actions trains new adapters automatically.

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

Set HF_TOKEN and HF_REPO_ID in repo secrets. The pipeline merges your data, trains 20 adapters in parallel on Apple Silicon (MLX), benchmarks, and publishes to HuggingFace.

The 20 bug-class adapters: 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

Hardware

Security

API key auth is off by default. Enable when sharing across a team:

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

Keys stored as SHA-256 hashes in ~/.timps/.secrets (chmod 600).

Contributing

PRs welcome against main. Conventional commits, please.

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 is currently a no-op — tests/ is empty. Existing runnable test scripts are top-level (python3 mcp_server/test_server.py, python3 test_computer_allocation.py). Add a tests/ directory and wire it into pyproject.toml before relying on pytest.

Lint: ruff check . (configured in pyproject.toml, no make lint target). Typecheck: none configured. Python ≥ 3.10, CI pins 3.11.