Timps Swarm

One `install-mcp` command puts 161 AI specialists into every coding tool you use — as parallel sub-agents, not just MCP tools.

Quick Start · Sub-agents · 161 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.
• 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 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).
• 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 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

Manual config snippets (all tools)

install-mcp writes the snippet below into each IDE config. The env: block forwards whichever API keys you have set in your shell; it's optional (the IDE usually inherits env, but explicit is safer for sandboxed hosts).

Claude Code — ~/.claude/mcp.json

{

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

Cursor / Windsurf / Gemini CLI / Codex CLI / Amp — same format as above, different path.

VS Code / Cline / Roo Code / GitHub Copilot — .vscode/mcp.json

{

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

Continue — ~/.continue/config.json

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

Aider — ~/.aider.conf.yml

mcp-servers:

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

Zed — ~/.config/zed/settings.json

{

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

Goose — ~/.config/goose/config.yaml

extensions:

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

GitHub Actions — reusable workflow

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

---

The 161 agents — full list

The MCP server exposes 161 specialist agents across 9 categories. Every one is also registered as a native Claude Code / Cursor / Codex sub-agent.

# 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

The Self-Critic Agent is the most valuable one — it scores any output 1–10 and re-runs the originating agent until the threshold is met, closing the quality loop across the entire swarm.

The 161 includes Phase 3 (12 priority), Phase 5 (7 more), Phase 6 nextgen (21 — security/DevOps/MLOps/emerging), Phase 7 (32 — India verticals, compliance, content, sales/voice, research), and timps_batch for parallel delegation. The src/tool_connectors module has a separate TOOLS dict (24 IDE config shortcuts — claude_code, cursor, etc.) used at runtime by `timps_