{ "markdown": "
\n\n\"TIMPS\n\n**One `install-mcp` command puts 161 AI specialists into every coding tool you use — as parallel sub-agents, not just MCP tools.**\n\n[![npm](https://img.shields.io/badge/npm-timps--swarm-CB3837?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/timps-swarm)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)\n[![MCP Protocol](https://img.shields.io/badge/Protocol-MCP-7C3AED?style=flat-square)](https://modelcontextprotocol.io)\n[![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/MmsTNm8WF6)\n\n[Quick Start](#quick-start) · [Sub-agents](#what-install-actually-does) · [161 Agents](#the-161-agents) · [MCP Setup](#mcp-integrations) · [CLI](#cli) · [Architecture](#architecture)\n\n
\n\n---\n\n![TIMPS Swarm Parallel Agent Demo](demo/swarm-demo.gif)\n*4 agents dispatched in parallel vs sequential — 3× speedup (64s vs 192s)*\n\n## What it does\n\n- **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.\n- **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=...)`.\n- **Local-first, BYOK** — runs on Ollama with zero API cost; plug in Gemini/Anthropic/OpenAI/Groq when you want more power.\n- **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.\n\n---\n\n## Quick Start\n\n```bash\nnpm i -g timps-swarm\n```\n\n> **Hand this repo to any coding agent and it will set itself up.**\n> `SETUP.md` is written as an instruction set (not just docs) — when a user\n> clones the repo and tells Claude Code, opencode, Codex, Cursor, Windsurf,\n> or any other agent to \"read SETUP.md and set me up\", the agent installs the\n> backend, registers the `timps-swarm` MCP server for whatever tool it's\n> running in, and starts dispatching the 161 specialist agents in parallel.\n\nThen wire it into your coding agents:\n\n```bash\nnpx timps-swarm install-mcp\n```\n\n`install-mcp` auto-detects every AI tool on your machine and:\n1. 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`).\n2. Writes one sub-agent `.md` file per TIMPS tool into `~/.claude/agents/`, `./.claude/agents/`, and `~/.codex/agents/`.\n\nRestart your tool — 161 agents appear as MCP tools **and** as parallel sub-agents.\n\n**Run without installing (zero setup):**\n\n```bash\nnpx timps-swarm audit ./ # security scan any repo — works immediately\n```\n\n---\n\n## What install actually does\n\n`install-mcp` is the only command you need:\n\n```bash\nnpx timps-swarm install-mcp # default: configure all detected tools\nnpx timps-swarm install-mcp --no-sub-agents # MCP config only, skip the .md files\nnpx timps-swarm install-mcp --tool cursor # configure one tool\nnpx timps-swarm install-mcp --dry-run # preview without writing\nnpx timps-swarm uninstall-mcp # remove all of the above\n```\n\nBy default this writes:\n\n- **MCP server entries** into 9 IDE config files (one entry per IDE, all pointing at `npx timps-swarm mcp`).\n- **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.\n\nAll 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).\n\n---\n\n## The killer commands\n\n```bash\n# Security audit — secrets + CVEs + SAST, no backend, no API key\nnpx timps-swarm audit ./\n\n# Full 10-agent SDLC pipeline on any codebase\nnpx timps-swarm fix ./src --language python\n\n# Generate a complete OpenAPI spec from plain English\nnpx timps-swarm api-design \"billing API with metered usage and Stripe webhooks\"\n\n# Design a DB schema with DDL, ER diagram, and migrations\nnpx timps-swarm db-design \"multi-tenant SaaS with usage-based billing\"\n\n# Diagnose your machine (12 specialist agents)\nnpx timps-swarm health\n```\n\n---\n\n## MCP integrations\n\n```bash\nnpx timps-swarm install-mcp # auto-detect and configure all installed tools\nnpx timps-swarm install-mcp --tool cursor # single tool only\nnpx timps-swarm install-mcp --dry-run # preview without writing files\n```\n\n| Tool | Config written |\n|------|----------------|\n| Claude Code | `~/.claude/mcp.json` |\n| Cursor | `~/.cursor/mcp.json` |\n| Windsurf | `~/.windsurf/mcp.json` |\n| Continue | `~/.continue/config.json` |\n| Zed | `~/.config/zed/settings.json` |\n| Aider | `~/.aider.conf.yml` |\n| Goose | `~/.config/goose/config.yaml` |\n| Gemini CLI | `~/.gemini/settings.json` |\n| Codex CLI | `~/.codex/config.json` |\n| Amp | `~/.amp/mcp.json` |\n| Warp | `~/.warp/mcp_servers.json` |\n| VS Code / Cline / Copilot | `.vscode/mcp.json` (workspace) |\n\n
\nManual config snippets (all tools)\n\n`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).\n\n**Claude Code** — `~/.claude/mcp.json`\n```json\n{\n \"mcpServers\": {\n \"timps-swarm\": {\n \"command\": \"npx\",\n \"args\": [\"timps-swarm\", \"mcp\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"...\",\n \"ANTHROPIC_API_KEY\": \"...\"\n }\n }\n }\n}\n```\n\n**Cursor / Windsurf / Gemini CLI / Codex CLI / Amp** — same format as above, different path.\n\n**VS Code / Cline / Roo Code / GitHub Copilot** — `.vscode/mcp.json`\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"timps-swarm\": { \"type\": \"stdio\", \"command\": \"npx\", \"args\": [\"timps-swarm\", \"mcp\"] }\n }\n }\n}\n```\n\n**Continue** — `~/.continue/config.json`\n```json\n{ \"mcpServers\": [{ \"name\": \"timps-swarm\", \"command\": \"npx\", \"args\": [\"timps-swarm\", \"mcp\"] }] }\n```\n\n**Aider** — `~/.aider.conf.yml`\n```yaml\nmcp-servers:\n timps-swarm:\n command: npx\n args: [timps-swarm, mcp]\n type: stdio\n```\n\n**Zed** — `~/.config/zed/settings.json`\n```json\n{\n \"assistant\": {\n \"mcp_servers\": {\n \"timps-swarm\": { \"command\": \"npx\", \"args\": [\"timps-swarm\", \"mcp\"] }\n }\n }\n}\n```\n\n**Goose** — `~/.config/goose/config.yaml`\n```yaml\nextensions:\n - name: timps-swarm\n type: stdio\n cmd: npx timps-swarm mcp\n enabled: true\n```\n\n**GitHub Actions** — reusable workflow\n```yaml\njobs:\n generate:\n uses: Sandeeprdy1729/timps-swarm/.github/workflows/timps-swarm.yml@main\n with:\n task: \"Build a microservice for JWT authentication\"\n language: python\n secrets:\n GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}\n```\n\n
\n\n---\n\n## LLM providers\n\nTries providers in priority order, uses the first available one.\n\n| Priority | Provider | Env var | Notes |\n|----------|----------|---------|-------|\n| 1 | MCP Sampler | *(auto)* | Uses the host tool's model |\n| 2 | Gemini 2.5 Flash | `GEMINI_API_KEY` | Recommended — fast + generous free tier |\n| 3 | Anthropic Claude | `ANTHROPIC_API_KEY` | Best for complex reasoning |\n| 4 | OpenAI GPT-4o | `OPENAI_API_KEY` | |\n| 5 | Groq Llama 3.3 70B | `GROQ_API_KEY` | Fastest API inference |\n| 6 | Ollama | *(auto-detected)* | Fully offline, no API key |\n| 7 | TIMPS-Coder 0.5B | *(built-in)* | Always available |\n\n```bash\nexport GEMINI_API_KEY=... # free tier, fastest start\nexport ANTHROPIC_API_KEY=... # optional\n```\n\n---\n\n
\nThe 161 agents — full list\n\nThe MCP server exposes **161 specialist agents** across 9 categories. Every one is also registered as a native Claude Code / Cursor / Codex sub-agent.\n\n| Category | Count | Examples |\n|----------|------:|----------|\n| **Priority** | 68 | research_agent, ab_testing_agent, abdm_agent, agent_composer, browser_automation, churn_predictor, demand_forecaster, dependency_agent, digilocker_agent, dpdp_act_auditor, federated_learning, finetuning_agent, fssai_compliance_agent, gst_compliance, indiehacker_agent, model_evaluator, model_perf_monitor, podcast_show_notes_writer, prompt_injection_scanner, quantum_ready, rag_designer, rag_evaluator, red_team_agent, release_manager, sbom_generator, security_remediation, service_mesh_configurator, sprint_planning_agent, storybook_story_generator, threat_intel_analyst, upi_agent, vector_db_agent, voice_agent_designer, wearable_health_coach, web3_agent, win_loss_analyst, … |\n| **Expert Diagnostics** | 51 | dependency_rebel, kubernetes_navigator, docker_compose_architect, pipeline_healer, compliance_auditor, incident_response_coordinator, accessibility_tester, mcp_server_generator, observability_cost_optimizer, license_compliance_scanner, container_image_scanner, adr_writer, contract_reviewer, court_case_summarizer, data_pipeline, db_migration_pilot, disaster_recovery, game_day_facilitator, git_workflow_automator, graphql_agent, iac_drift_detector, load_testing, local_rag_builder, log_pattern_analyzer, phishing_simulator, postmortem_agent, test_intelligence, visual_regression_detective, web_scraping, web_search, … |\n| **Computer Health** | 12 | system_optimizer, file_organizer, environment_doctor, security_guard, network_medic, battery_analyst, update_manager, log_interpreter, privacy_cleaner, media_librarian, backup_sentinel, context_switcher |\n| **Developer Workflow** | 12 | issue_triager, boilerplate_architect, pr_reviewer, dependency_sentinel, unit_test_writer, docstring_generator, log_detective, sql_optimizer, sprint_reporter, flaky_test_hunter, api_contract_auditor, content_multiplier |\n| **Knowledge Worker** | 7 | inbox_gatekeeper, meeting_condenser, research_scout, trend_monitor, data_wrangler, competitor_tracker, agri_commodity_forecaster |\n| **Meta** | 6 | list_agents, dispatch, full_checkup, list_providers, connect_tools, tool_status |\n| **Context / Kernel** | 3 | context_briefing, delegate, kernel_status |\n| **SDLC Pipeline** | 1 | run_task (the 10-node LangGraph orchestrator: PM → Architect → Code → Review → QA → Security → Perf → Docs → DevOps) |\n\n```bash\n# Trigger the full SDLC pipeline\npython3 give_work.py \"Build a rate-limited REST API for user authentication\"\n# PM → Architect → Code → Review → QA → Security → Perf → Docs → DevOps\n\n# Run a computer health checkup\nnpx timps-swarm health\npython3 give_work.py \"My laptop fan is always running\"\n\n# Delegate a multi-step goal\nnpx timps-swarm delegate \"fix the auth bug and ensure 80% test coverage\"\n\n# Call any of the 161 directly from the CLI\nnpx timps-swarm mcp # then use any MCP client\n```\n\nThe **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.\n\n> 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_connect_tools` and `timps_tool_status`; those are not part of the 161.\n\n
\n\n---\n\n## CLI\n\n```bash\nnpm install -g timps-swarm # or: npx timps-swarm \n```\n\n```\nCOMMANDS\n audit Security audit — secrets + CVEs + SAST (works offline)\n fix Run the full 10-agent SDLC pipeline\n research Research a topic before writing code\n api-design Generate an OpenAPI 3.1 spec from plain English\n db-design Design a database schema with DDL + ER diagram\n n8n Generate a complete n8n workflow JSON\n refactor [path] Detect code smells + produce refactored version\n test-data Generate realistic seed / fixture data\n monitor Prometheus + Grafana + alerting config\n ui UI component spec + code + accessibility audit\n cost Cloud cost estimate + savings recommendations\n critique Score output 1-10, auto-improve until threshold\n health Computer health checkup (12 agents)\n providers Show configured LLM providers\n install-mcp Auto-configure TIMPS in 9 AI tools + 161 sub-agents\n uninstall-mcp Remove the MCP config and 161 sub-agent .md files\n start [--repo ] Start the TIMPS Swarm API server (port 8000)\n mcp [--repo ] Start the MCP stdio server (Python or Node.js fallback)\n\nFLAGS (install-mcp)\n --tool Only configure one IDE (claude-code, cursor, codex-cli, …)\n --no-sub-agents Skip writing 161 sub-agent .md files (MCP config only)\n --dry-run Preview without writing anything\n --silent Suppress output (postinstall)\n\nENV VARS\n TIMPS_API_URL API server URL (default http://localhost:8000)\n Set to a remote URL to point every tool call at it.\n TIMPS_REPO Explicit path to the Python repo for backend commands\n GEMINI_API_KEY Free tier — fastest start\n ANTHROPIC_API_KEY Optional\n OPENAI_API_KEY Optional\n GROQ_API_KEY Optional\n OLLAMA_HOST Default http://localhost:11434\n REDIS_URL Default redis://localhost:6379/0\n```\n\nIf `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.\n\n---\n\n## Architecture\n\n```\n User / AI coding tool\n (Claude Code, Cursor, Codex, …)\n │\n ┌────────────────────────┼────────────────────────┐\n │ stdio JSON-RPC 2.0 │ │\n ▼ ▼ ▼\n ┌──────────────────────┐ ┌──────────────────────┐ ┌────────────────────┐\n │ mcp_server/server.py │ │ cli/lib/mcp-proxy.js │ │ src/main.py │\n │ Python — 161 tools, │ │ Node.js fallback │ │ FastAPI + WS │\n │ full MCP sampling │ │ (npm-only path) │ │ /swarm/run, │\n │ │ │ │ │ /agents/*, │\n │ │ │ │ │ /mcp/tools, │\n │ │ │ │ │ /mcp/tools/call, │\n │ │ │ │ │ /health, /ws │\n └──────────┬───────────┘ └──────────┬───────────┘ └──────────┬─────────┘\n │ │ │\n │ TOOLS / dispatch │ POST /mcp/tools/call │\n │ ◀───────────────────────┴──────────────────────────▶│\n │ │\n │ mcp_server/server._TOOL_HANDLERS │\n │ (161 tools, in-process) │\n └─────────────────────────┬───────────────────────────┘\n │\n Swarm Bridge\n │\n ┌───────────────────┬──────────┴──────────┬───────────────────┐\n ▼ ▼ ▼ ▼\n SDLC DAG Health Graph Specialist Agents Context / Kernel\n (10 nodes) (12 nodes) (120 direct calls) (3 nodes)\n │ │ │ │\n └───────────────────┴─────────────────────┴───────────────────┘\n │\n LLM Router\n ┌─────────────┬─────────────────┼─────────────┬───────────────┐\n ▼ ▼ ▼ ▼ ▼\n Gemini Anthropic OpenAI Groq Ollama\n 2.5 Flash Claude GPT-4o Llama 3.3 (local)\n + TIMPS-Coder 0.5B\n```\n\nThree transport paths converge on the same dispatch table:\n\n1. **Python MCP stdio** (`mcp_server/server.py`) — full MCP sampling, in-process, 161 tools. Used when the Python repo is on disk.\n2. **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).\n3. **FastAPI REST + WebSocket** (`src/main.py`) — `/swarm/run`, `/agents/*`, `/health`, `/ws`, plus the bridge endpoints `/mcp/tools` (catalogue) and `/mcp/tools/call` (dispatch).\n\n**Layer 1 — Computer Manager** (`src/layer1_computer_manager.py`) — isolated working directories, CPU/memory/disk caps per agent.\n\n**Layer 2 — Swarm Bridge** (`src/layer2_swarm_bridge.py`) — agent lifecycle: spawning, team formation, LangGraph DAG execution, result collection.\n\n**Layer 3 — CLI** (`src/layer3_swarm_cli.py`) — `give_work.py` and the npm CLI.\n\n---\n\n## REST API\n\n```bash\ncurl http://localhost:8000/health\ncurl http://localhost:8000/health/full # deep check with provider status\n\ncurl -X POST http://localhost:8000/swarm/run \\\n -H \"Content-Type: application/json\" \\\n -d '{\"request\": \"Fix SQL injection in my FastAPI endpoint\", \"language\": \"python\"}'\n\ncurl -X POST http://localhost:8000/agents/refactor \\\n -d '{\"code\": \"...\", \"language\": \"python\", \"goals\": [\"reduce_complexity\"]}'\n\ncurl http://localhost:8000/providers\n\n# MCP bridge (used by cli/lib/mcp-proxy.js)\ncurl http://localhost:8000/mcp/tools # full 161-tool catalogue\ncurl -X POST http://localhost:8000/mcp/tools/call \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"timps_list_agents\", \"arguments\": {}}' # call any tool over HTTP\n\nwscat -c ws://localhost:8000/ws # real-time stream\n```\n\nFull interactive docs at `http://localhost:8000/docs` when the server is running.\n\n---\n\n## Training custom adapters\n\nThe 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.\n\n```bash\ncp my_bugs.jsonl datasets/custom/\ngit add datasets/custom/my_bugs.jsonl\ngit commit -m \"feat: 40 new Python async bug examples\"\ngit push origin main\n```\n\nSet `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.\n\n**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`\n\n---\n\n## Hardware\n\n| Setup | RAM | Notes |\n|-------|-----|-------|\n| Minimum | 8 GB | One Ollama model at a time |\n| Recommended | 16 GB | All models loaded simultaneously |\n| Fine-tuning | 8 GB Apple Silicon | MLX on M1/M2/M3/M4 |\n\n---\n\n## Security\n\nAPI key auth is off by default. Enable when sharing across a team:\n\n```bash\nTIMPS_AUTH=1 make up-local\npython3 give_work.py --keygen \"sandeep-laptop\" # generate key (shown once)\npython3 give_work.py --revoke timps-sk-xxxx # revoke a key\n```\n\nKeys stored as SHA-256 hashes in `~/.timps/.secrets` (chmod 600).\n\n---\n\n## Contributing\n\nPRs welcome against `main`. Conventional commits, please.\n\n```bash\ngit clone https://github.com/Sandeeprdy1729/timps-swarm\ncd timps-swarm && pip install -e \".[dev]\"\nmake up-local # starts the FastAPI server on :8000\n```\n\n> `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.\n\nLint: `ruff check .` (configured in `pyproject.toml`, no `make lint` target). Typecheck: none configured. Python ≥ 3.10, CI pins 3.11.\n\n---\n\n
\n\nBuilt on [TIMPS-Coder](https://github.com/Sandeeprdy1729/timps-coder) — a 0.5B model fine-tuned with 20 LoRA adapters for specific bug patterns.\n\nMIT License · [Discord](https://discord.gg/MmsTNm8WF6) · [npm](https://www.npmjs.com/package/timps-swarm)\n\n
\n", "bytes": 21501, "sha": "87f86cac7713891c7779254af7e2059a501eeb951886e0f46e52f5f5c9039a06", "repo_slug": "sandeeprdy1729/timps-swarm", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_sandeeprdy1729_timps_swarm_deb79097/readme" }