Timps Swarm

[TIMPS Swarm Parallel Agent Demo] 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.
• 161 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

Hand this repo to any coding agent and it will set itself up. SETUP.md is written as an instruction set (not just docs) — when a user clones the repo and tells Claude Code, opencode, Codex, Cursor, Windsurf, or any other agent to "read SETUP.md and set me up", the agent installs the backend, registers the timps-swarm MCP server for whatever tool it's running in, and starts dispatching the 161 specialist agents in parallel.

Then wire it into your coding agents:

npx timps-swarm install-mcp

install-mcp 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 — 161 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 toolsnpx timps-swarm install-mcp --no-sub-agents  # MCP config only, skip the .md filesnpx timps-swarm install-mcp --tool cursor    # configure one toolnpx timps-swarm install-mcp --dry-run        # preview without writingnpx 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).
• 161 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 keynpx timps-swarm audit ./
# Full 10-agent SDLC pipeline on any codebasenpx timps-swarm fix ./src --language python
# Generate a complete OpenAPI spec from plain Englishnpx timps-swarm api-design "billing API with metered usage and Stripe webhooks"
# Design a DB schema with DDL, ER diagram, and migrationsnpx 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 toolsnpx timps-swarm install-mcp --tool cursor    # single tool onlynpx 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 startexport ANTHROPIC_API_KEY=...   # optional

# Trigger the full SDLC pipelinepython3 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 checkupnpx timps-swarm healthpython3 give_work.py "My laptop fan is always running"
# Delegate a multi-step goalnpx timps-swarm delegate "fix the auth bug and ensure 80% test coverage"
# Call any of the 161 directly from the CLInpx 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

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 — 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

Three transport paths converge on the same dispatch table:

1. Python MCP stdio (mcp_server/server.py) — full MCP sampling, in-process, 161 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/healthcurl 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 cataloguecurl -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.jsonlgit 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-localpython3 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-swarmcd 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.