{"id":50709092,"url":"https://github.com/ArtemisAI/SWE-Squad","last_synced_at":"2026-06-26T14:00:47.123Z","repository":{"id":345080397,"uuid":"1184347894","full_name":"ArtemisAI/SWE-Squad","owner":"ArtemisAI","description":"Autonomous Software Engineering Agents — self-healing, self-diagnosing development team powered by Claude Code and A2A protocol","archived":false,"fork":false,"pushed_at":"2026-05-16T20:57:50.000Z","size":3330,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T22:42:49.216Z","etag":null,"topics":["a2a-protocol","agentic-ai","ai-agents","automation","autonomous-agents","bug-fixing","claude","claude-code","devops","llm","multi-agent","self-healing","software-engineering","supabase","swe-agent"],"latest_commit_sha":null,"homepage":"https://github.com/ArtemisAI/SWE-Squad","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ArtemisAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["ArtemisAI"]}},"created_at":"2026-03-17T13:56:58.000Z","updated_at":"2026-05-16T20:57:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ArtemisAI/SWE-Squad","commit_stats":null,"previous_names":["artemisai/swe-squad"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ArtemisAI/SWE-Squad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArtemisAI%2FSWE-Squad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArtemisAI%2FSWE-Squad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArtemisAI%2FSWE-Squad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArtemisAI%2FSWE-Squad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ArtemisAI","download_url":"https://codeload.github.com/ArtemisAI/SWE-Squad/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ArtemisAI%2FSWE-Squad/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34819597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","agentic-ai","ai-agents","automation","autonomous-agents","bug-fixing","claude","claude-code","devops","llm","multi-agent","self-healing","software-engineering","supabase","swe-agent"],"created_at":"2026-06-09T14:00:28.027Z","updated_at":"2026-06-26T14:00:47.114Z","avatar_url":"https://github.com/ArtemisAI.png","language":"Python","funding_links":["https://github.com/sponsors/ArtemisAI"],"categories":["⚙️ Implementations \u0026 Libraries"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-Control_Plane-3178c6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-Agent_Library-3776ab?logo=python\u0026logoColor=white\" alt=\"Python 3.10+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/pi--agent-SDK-blueviolet\" alt=\"pi-agent SDK\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude_Code-CLI-blueviolet?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+\" alt=\"Claude Code\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/A2A-Protocol-orange\" alt=\"A2A Protocol\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tests-6800+-brightgreen\" alt=\"Tests\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"MIT License\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSWE Squad\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAutonomous Software Engineering Agents That Fix Bugs While You Sleep\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  An always-on AI engineering manager backed by a persistent LLM session with 16 custom tools.\u003cbr\u003e\n  Scans GitHub issues, investigates root causes, delegates fixes, reviews PRs, and enforces safety gates — autonomously.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Built on \u003ca href=\"https://github.com/nichochar/pi-coding-agent\"\u003epi-agent SDK\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://docs.anthropic.com/en/docs/claude-code\"\u003eClaude Code\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://supabase.com\"\u003eSupabase\u003c/a\u003e \u0026bull;\n  \u003ca href=\"https://github.com/google/A2A\"\u003eA2A Protocol\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\nSWE Squad is an **always-on AI engineering manager** that runs as a persistent daemon. It:\n\n1. **Imports** GitHub issues as structured tickets into a Supabase store\n2. **Triages** by severity — the LLM decides priority, not hardcoded rules\n3. **Investigates** root causes by delegating to any configured coding engine\n4. **Develops** fixes on feature branches with automated test verification\n5. **Reviews** PRs with structured feedback (security, correctness, style)\n6. **Merges** approved changes and monitors for regressions\n7. **Notifies** via Telegram on critical events, PR creation, and failures\n\nThe system is built on two codebases:\n\n| Layer | Language | Purpose |\n|-------|----------|---------|\n| **Control Plane** | TypeScript | Persistent pi-agent daemon with 16 custom tools — the decision-making brain |\n| **Agent Library** | Python | Specialized agents (monitor, triage, investigate, develop), ticket store, embeddings |\n\n### Key Capabilities\n\n- **16 Custom Tools** — ticket CRUD, GitHub import, investigation/development/review delegation, PR management, workspace provisioning, safety gates, health monitoring, notifications\n- **Engine-Agnostic Delegation** — swap coding engines (Claude CLI, Gemini CLI, Copilot, OpenCode) via config\n- **Provider-Agnostic Architecture** — every external service is a swappable plugin behind an interface\n- **Persistent Sessions** — JSONL-backed session state survives daemon restarts\n- **Safety Gates** — circuit breaker, stability gate, outcome tracker, budget enforcement\n- **Semantic Memory** — pgvector embeddings surface similar past fixes at investigation time\n- **Multi-Team Support** — multiple squads share Supabase without overlap\n- **React WebUI** — management dashboard with Kanban boards, pipeline editor, team controls\n\n---\n\n## Architecture\n\nThe V2 architecture centers on a **single persistent LLM session** (via `@mariozechner/pi-coding-agent`) that decides what to do based on its persona and tool results. No hardcoded phases.\n\n```mermaid\nflowchart TD\n    subgraph daemon [\" SWE-Manager Daemon (TypeScript) \"]\n        Session[\"pi-agent Session\\nPersistent LLM + 16 tools\"]\n        HB[\"Heartbeat Loop\\n5-min interval\"]\n        HB --\u003e|\"prompt\"| Session\n    end\n\n    subgraph tools [\" Custom Tools \"]\n        direction LR\n        TL[\"ticket_list\\nticket_create\\nticket_update\"]\n        GH[\"github_issues\\ngithub_import\"]\n        DEL[\"delegate_investigation\\ndelegate_development\\ndelegate_review\"]\n        PR[\"run_tests\\napprove_pr\\nmerge_pr\"]\n        OPS[\"check_stability\\ncheck_health\\ncheck_metrics\"]\n        WS[\"manage_workspace\\nsend_notification\"]\n    end\n\n    subgraph engines [\" Coding Engines (config-resolved) \"]\n        Claude[\"Claude Code CLI\"]\n        Gemini[\"Gemini CLI\"]\n        Copilot[\"GitHub Copilot\"]\n    end\n\n    subgraph infra [\" Infrastructure \"]\n        Supa[(\"Supabase\\nTickets + pgvector\")]\n        GitHub[\"GitHub API\\nIssues + PRs\"]\n        Telegram[\"Telegram\\nNotifications\"]\n    end\n\n    Session --\u003e tools\n    DEL --\u003e|\"spawn\"| engines\n    TL \u0026 GH --\u003e Supa\n    GH --\u003e GitHub\n    WS --\u003e Telegram\n\n    classDef daemonNode fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px,rx:12\n    classDef toolNode fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:1.5px\n    classDef engineNode fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:1.5px\n    classDef infraNode fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px\n    classDef subgraphBox fill:transparent,stroke:#e5e7eb,stroke-width:1px,color:#6b7280\n\n    class Session,HB daemonNode\n    class TL,GH,DEL,PR,OPS,WS toolNode\n    class Claude,Gemini,Copilot engineNode\n    class Supa,GitHub,Telegram infraNode\n    class daemon,tools,engines,infra subgraphBox\n```\n\n### Ticket Pipeline\n\nThe daemon flushes right-to-left, completing nearest-done work first:\n\n```\nopen → investigating → investigation_complete → in_development → in_review → testing → resolved\n```\n\nEach heartbeat, the LLM picks the highest-priority ticket closest to completion and advances it one step.\n\n---\n\n## How the Fix Loop Works\n\n```mermaid\nflowchart TD\n    Start([\"New Ticket\"]):::startNode --\u003e Cache{\"Trajectory\\ncache hit?\"}:::decisionNode\n\n    Cache --\u003e|\"hit — free\"| Replay[\"Replay cached fix\\nzero cost\"]:::cacheNode\n    Replay --\u003e Tests0{\"Tests\\npass?\"}:::testNode\n    Tests0 --\u003e|\"pass\"| Keep0([\"KEEP — commit\"]):::successNode\n\n    Cache --\u003e|\"miss\"| A1\n\n    subgraph attempts [\" Escalating Fix Attempts \"]\n        A1[\"Attempt 1 — Sonnet\\nRoutine fix\"]:::sonnetNode\n        A1 --\u003e Tests1{\"Tests\\npass?\"}:::testNode\n        Tests1 --\u003e|\"pass\"| Keep1([\"KEEP\"]):::successNode\n        Tests1 --\u003e|\"fail\"| A2[\"Attempt 2 — Sonnet\\n+ error context\"]:::sonnetNode\n        A2 --\u003e Tests2{\"Tests\\npass?\"}:::testNode\n        Tests2 --\u003e|\"pass\"| Keep2([\"KEEP\"]):::successNode\n        Tests2 --\u003e|\"fail\"| A3[\"Attempt 3 — Opus\\nOrchestrates sub-agents\"]:::opusNode\n        A3 --\u003e Tests3{\"Tests\\npass?\"}:::testNode\n        Tests3 --\u003e|\"pass\"| Keep3([\"KEEP\"]):::successNode\n        Tests3 --\u003e|\"fail\"| HITL\n    end\n\n    HITL([\"HITL Escalation\\nTelegram notification\"]):::failNode\n\n    Tests0 --\u003e|\"fail\"| A1\n\n    classDef startNode fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px\n    classDef decisionNode fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px\n    classDef cacheNode fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:1.5px\n    classDef testNode fill:#64748b,stroke:#475569,color:#fff,stroke-width:1.5px\n    classDef sonnetNode fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:1.5px\n    classDef opusNode fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px\n    classDef successNode fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px\n    classDef failNode fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px\n    classDef subgraphBox fill:transparent,stroke:#e5e7eb,stroke-width:1px,color:#6b7280\n\n    class attempts subgraphBox\n```\n\nEach attempt runs on a **git branch**. Tests pass = commit + PR. Tests fail = `git reset --hard` (auto-revert). No broken code ever reaches main.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 20+** and **pnpm** (for the TypeScript control plane)\n- **Python 3.10+** (for the agent library and tests)\n- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** (coding engine)\n- **[GitHub CLI](https://cli.github.com/)** (`gh`) authenticated\n\n### 1. Install\n\n```bash\ngit clone https://github.com/ArtemisAI/SWE-Squad.git\ncd SWE-Squad\n\n# TypeScript control plane\ncd control-plane \u0026\u0026 pnpm install \u0026\u0026 cd ..\n\n# Python agent library\npip install python-dotenv pyyaml\n```\n\n### 2. Configure\n\n```bash\ncp .env.example .env\n# Edit .env with your credentials (see Configuration section)\n```\n\n### 3. Run the Daemon\n\n```bash\n# Single heartbeat (test your setup)\nnpx tsx control-plane/src/main.ts --verbose\n\n# Daemon mode (continuous 5-minute heartbeats)\nnpx tsx control-plane/src/main.ts --daemon --verbose\n\n# Fresh session (discards prior session state)\nnpx tsx control-plane/src/main.ts --daemon --fresh --verbose\n\n# Dry run (validates config and tool registration, no LLM calls)\nnpx tsx control-plane/src/main.ts --dry-run\n```\n\n### 4. Run Tests\n\n```bash\n# Python tests (5900+ tests)\npython3 -m pytest tests/ -v --tb=short\n\n# TypeScript tests (900+ tests)\ncd control-plane \u0026\u0026 pnpm test\n\n# TypeScript type checking\ncd control-plane \u0026\u0026 pnpm typecheck\n```\n\n---\n\n## The 16 Custom Tools\n\nThe daemon's LLM session has access to these tools, registered via `defineTool()` from pi-agent:\n\n| Tool | Purpose |\n|------|---------|\n| `ticket_list` | Query tickets by status, severity, repo, or pipeline view |\n| `ticket_create` | Create a new ticket with fingerprint-based deduplication |\n| `ticket_update` | Update ticket status, notes, assignee; enforces resolution audit |\n| `github_issues` | List open GitHub issues from configured repositories |\n| `github_import` | Import GitHub issues as tickets with dedup (fingerprint: `gh-issue-{repo}-{number}`) |\n| `delegate_investigation` | Claim ticket, resolve engine from config, spawn investigation, store report |\n| `delegate_development` | Claim ticket, provision workspace, spawn development, create PR |\n| `delegate_review` | Spawn code review on a PR with structured feedback |\n| `run_tests` | Execute test suite in a workspace and report results |\n| `approve_pr` | Approve a pull request via GitHub API |\n| `merge_pr` | Merge an approved PR (squash merge) |\n| `manage_workspace` | Create/cleanup/list git worktrees for isolated development |\n| `check_stability` | Evaluate safety gates: circuit breaker + open criticals + test failures |\n| `check_health` | Aggregate health snapshot: Supabase, engines, circuit breaker, uptime |\n| `check_metrics` | Pipeline metrics: throughput, cycle time, failure rates |\n| `send_notification` | Send alerts via configured provider (Telegram, Slack, webhook) |\n\n---\n\n## Configuration\n\n### Environment Variables\n\nCopy `.env.example` to `.env` and configure:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `SWE_TEAM_ENABLED` | Yes | Kill switch (`true`/`false`) |\n| `SWE_TEAM_ID` | Yes | Unique team identifier for ticket scoping |\n| `SWE_GITHUB_ACCOUNT` | Yes | Dedicated GitHub bot account |\n| `GH_TOKEN` | Yes | GitHub PAT with `repo` scope |\n| `SUPABASE_URL` | Yes | Supabase PostgREST URL |\n| `SUPABASE_ANON_KEY` | Yes | Supabase authentication key |\n| `TELEGRAM_BOT_TOKEN` | No | Telegram bot token for notifications |\n| `TELEGRAM_CHAT_ID` | No | Telegram chat ID for alerts |\n| `BASE_LLM_API_URL` | No | OpenAI-compatible proxy for embeddings |\n| `ANTHROPIC_BASE_URL` | No | Proxy URL for Claude CLI (engine delegation) |\n| `SWE_DAEMON_MODEL` | No | Override daemon LLM model (default: `claude-sonnet`) |\n| `SWE_MODEL_T2` | No | Override delegation model tier (default: `sonnet`) |\n\nSee [`.env.example`](.env.example) for the full list.\n\n### YAML Config (`config/swe_team.yaml`)\n\nThe YAML config controls:\n\n- **`delegation`** — per-role engine binding (investigator, developer, reviewer)\n- **`workspace`** — worktree provisioning settings\n- **`daemon`** — heartbeat interval, initial prompt, session lifecycle\n- **`cycle`** — max concurrent investigations/developments, severity filters\n- **`memory`** — embedding model, similarity thresholds, TTL\n- **`notification`** — provider selection (telegram/slack/webhook)\n- **`governance`** — stability gate thresholds\n- **`githubRepos`** — list of repos to scan for issues\n\n---\n\n## Engine Delegation\n\nThe daemon never implements directly. It delegates to configured **coding engines** resolved from config:\n\n```yaml\n# config/swe_team.yaml\ndelegation:\n  investigator:\n    engine: claude-cli\n    model: sonnet\n    readOnly: true\n    timeout: 1800\n  developer:\n    engine: claude-cli\n    model: sonnet\n    timeout: 3600\n  reviewer:\n    engine: claude-cli\n    model: haiku\n    readOnly: true\n    timeout: 900\n```\n\nSupported engines: Claude Code CLI, Gemini CLI, OpenCode, GitHub Copilot. Adding a new engine = new file in `providers/engine/` + config entry.\n\n---\n\n## Model Routing\n\n| Scenario | Model | Cost |\n|----------|-------|------|\n| Daemon management cycle | **Sonnet** | $$ |\n| Investigation (default) | **Sonnet** | $$ |\n| Development + PR creation | **Sonnet** | $$ |\n| PR review | **Haiku** | $ |\n| Embeddings, fact extraction | **bge-m3 / gemini-3-flash** | $ |\n| CRITICAL bugs | **Opus** | $$$ |\n| Deterministic replay (cached) | **None** | Free |\n\n```mermaid\nflowchart LR\n    Ticket([\"Incoming Ticket\"]):::startNode --\u003e Cached{\"Cached\\nfix?\"}:::decisionNode\n\n    Cached --\u003e|\"hit — free\"| Replay([\"Replay\\nzero cost\"]):::cacheNode\n    Cached --\u003e|\"miss\"| Severity{\"Severity?\"}:::decisionNode\n\n    subgraph tiers [\" Model Tiers \"]\n        direction TB\n        T1[\"T1 Haiku\\nEmbeddings, triage\\n$\"]:::t1Node\n        T2[\"T2 Sonnet\\nInvestigation + fix\\n$$\"]:::t2Node\n        T3[\"T3 Opus\\nOrchestrator only\\n$$$\"]:::t3Node\n    end\n\n    Severity --\u003e|\"LOW / MEDIUM\"| T1\n    Severity --\u003e|\"HIGH\"| T2\n    Severity --\u003e|\"CRITICAL\"| T3\n    T2 --\u003e|\"2 failures\"| T3\n\n    subgraph fallback [\" Fallback Chain \"]\n        direction LR\n        Claude[\"Claude Code\\nprimary\"]:::claudeNode\n        Gemini[\"Gemini CLI\\nfallback\"]:::geminiNode\n        OpenCode[\"OpenCode\\nlast resort\"]:::opencodeNode\n        Claude --\u003e|\"rate limited\"| Gemini --\u003e|\"unavailable\"| OpenCode\n    end\n\n    T2 -.-\u003e|\"dispatch\"| Claude\n    T3 -.-\u003e|\"dispatch\"| Claude\n\n    classDef startNode fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px\n    classDef decisionNode fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px\n    classDef cacheNode fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px\n    classDef t1Node fill:#94a3b8,stroke:#64748b,color:#fff,stroke-width:1.5px\n    classDef t2Node fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:1.5px\n    classDef t3Node fill:#ef4444,stroke:#dc2626,color:#fff,stroke-width:2px\n    classDef claudeNode fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:1.5px\n    classDef geminiNode fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:1.5px\n    classDef opencodeNode fill:#14b8a6,stroke:#0d9488,color:#fff,stroke-width:1.5px\n    classDef subgraphBox fill:transparent,stroke:#e5e7eb,stroke-width:1px,color:#6b7280\n\n    class tiers,fallback subgraphBox\n```\n\n---\n\n## Semantic Memory\n\nWhen a ticket is resolved, SWE Squad extracts structured facts and stores embeddings in pgvector. On future investigations, the top-5 most similar memories are injected as context.\n\n```mermaid\nflowchart TD\n    subgraph store [\" Storage — on ticket resolved \"]\n        Resolved([\"Ticket Resolved\"]):::successNode\n        Extract[\"extract_memory_facts\\nroot cause, fix, module, tags\"]:::extractNode\n        Embed[\"embed_ticket\\nbge-m3 — 1024 dim\"]:::embedNode\n        Dedup{\"Cosine\\n\u003e 0.92?\"}:::decisionNode\n        StoreDB[(\"Supabase\\npgvector\")]:::dbNode\n\n        Resolved --\u003e Extract --\u003e Embed --\u003e Dedup\n        Dedup --\u003e|\"new\"| StoreDB\n        Dedup --\u003e|\"duplicate\"| StoreDB\n    end\n\n    subgraph retrieve [\" Retrieval — on investigation \"]\n        NewTicket([\"New Ticket\"]):::startNode\n        Search[\"find_similar\\nTop-5, cosine \u003e= 0.75\\n180-day TTL\"]:::searchNode\n        Inject[\"Inject as\\nSemantic Memory context\"]:::injectNode\n\n        NewTicket --\u003e Search --\u003e|\"query\"| StoreDB\n        StoreDB --\u003e|\"matches\"| Inject\n    end\n\n    classDef successNode fill:#10b981,stroke:#059669,color:#fff,stroke-width:2px\n    classDef startNode fill:#6366f1,stroke:#4338ca,color:#fff,stroke-width:2px\n    classDef extractNode fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:1.5px\n    classDef embedNode fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:1.5px\n    classDef decisionNode fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px\n    classDef dbNode fill:#3ecf8e,stroke:#2da66e,color:#fff,stroke-width:2px\n    classDef searchNode fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:1.5px\n    classDef injectNode fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:1.5px\n    classDef subgraphBox fill:transparent,stroke:#e5e7eb,stroke-width:1px,color:#6b7280\n\n    class store,retrieve subgraphBox\n```\n\n---\n\n## Plugin Architecture\n\nEvery external service is a swappable plugin behind an interface:\n\n| Component | Interface | Default | Alternatives |\n|---|---|---|---|\n| Coding agent | `CodingEngine` | Claude Code CLI | Gemini CLI, OpenCode, Copilot |\n| Notifications | `NotificationProvider` | Telegram | Slack, webhook, email |\n| Issue tracker | `IssueTracker` | GitHub Issues | Jira, Linear, GitLab |\n| Embeddings | `EmbeddingProvider` | bge-m3 | OpenAI, sentence-transformers |\n| Vector store | `VectorStore` | Supabase pgvector | Qdrant, Weaviate, Chroma |\n| Task queue | `TaskQueueProvider` | In-memory (heapq) | Redis, RabbitMQ, SQS |\n| Workspace | `WorkspaceProvider` | git-worktree | Docker volume, cloud VM |\n| Sandbox | `SandboxProvider` | Local subprocess | Docker, Codespaces |\n\nNew provider = new file in `providers/\u003cdomain\u003e/` + config entry. Nothing else changes.\n\n---\n\n## Project Structure\n\n```\ncontrol-plane/                     # TypeScript V2 control plane\n  src/\n    main.ts                        # Daemon entry point — pi-agent session + heartbeat\n    config/\n      schemas.ts                   # Zod schemas for all config sections\n      loader.ts                    # YAML + env var config loader\n    tools/                         # 16 custom pi-agent tools\n      ticket-list.ts               # Query tickets by status/severity/repo\n      ticket-create.ts             # Create tickets with fingerprint dedup\n      ticket-update.ts             # Update status/notes/assignee\n      github-issues.ts             # List GitHub issues\n      github-import.ts             # Import issues as tickets\n      delegate-investigation.ts    # Spawn investigation via engine\n      delegate-development.ts      # Spawn development + PR creation\n      delegate-review.ts           # Spawn PR review\n      run-tests.ts                 # Execute test suite\n      approve-pr.ts                # Approve PR via GitHub API\n      merge-pr.ts                  # Merge approved PRs\n      manage-workspace.ts          # Git worktree provisioning\n      check-stability.ts           # Safety gate evaluation\n      check-health.ts              # System health snapshot\n      check-metrics.ts             # Pipeline metrics\n      send-notification.ts         # Notification dispatch\n    providers/                     # Provider implementations\n      supabase/                    # Supabase client + ticket store\n      notification/                # Telegram, Slack, webhook\n      engine/                      # Coding engine registry\n      memory/                      # Memory service providers\n    safety/                        # Circuit breaker, outcome tracker\n    services/                      # Memory service, workspace manager\n    shared/                        # Engine resolver, prompt builder, context\n    extensions/                    # Tool guard, RBAC, cost tracking\n  tests/                           # 900+ vitest tests (unit + integration)\n\nsrc/swe_team/                      # Python agent library\n  monitor_agent.py                 # Log scanning, error detection\n  triage_agent.py                  # Severity routing\n  investigator.py                  # Root-cause analysis via Claude CLI\n  developer.py                     # Keep/discard fix loop\n  ralph_wiggum.py                  # Stability gate\n  supabase_store.py                # Supabase ticket store\n  embeddings.py                    # bge-m3 embeddings + fact extraction\n  guardrails.py                    # Safety gate coordinator\n  cost_tracker.py                  # Budget enforcement\n  atomic_checkout.py               # Cross-VM task dedup\n  ...                              # 30+ modules total\n\nsrc/a2a/                           # A2A inter-agent protocol\n  server.py, client.py, dispatch.py\n\nui/                                # React + Vite management dashboard\n\nscripts/ops/                       # Operational scripts\n  swe_team_runner.py               # Legacy Python runner (cron/daemon)\n  swe_cli.py                       # CLI tool (status, tickets, reports)\n  propagate.sh                     # Code propagation to worker nodes\n\nconfig/\n  swe_team.yaml                    # Runtime configuration\n  swe_team/programs/               # Prompt templates (investigate.md, fix.md)\n\n.pi/\n  skills/swe-manager/SKILL.md      # LLM persona definition\n  extensions/                      # pi-agent extension stubs\n\ntests/                             # 5900+ pytest tests\n```\n\n---\n\n## Multi-Team Deployment\n\nSWE Squad supports multiple teams sharing infrastructure:\n\n| Team | VM | Role | Engine |\n|------|-----|------|--------|\n| **alpha** | `primary` | Senior: QA, merge authority, critical fixes | Claude CLI (direct) |\n| **beta** | `worker-1` | Development: bulk features, bug fixes | Claude CLI (proxy) |\n| **gamma** | `worker-2` | Economy: investigation, triage | Claude CLI (proxy) |\n\nEach team has its own `team_id` scoping all tickets, a dedicated GitHub bot account, and isolated VM.\n\n---\n\n## Safety\n\n- **Circuit Breaker** — trips at 80% failure rate, pauses daemon for 30 minutes\n- **Stability Gate** — blocks new work when critical tickets are open or tests are failing\n- **Outcome Tracker** — max 3 investigation/development attempts per ticket before HITL escalation\n- **Budget Enforcement** — per-agent cost tracking with configurable hard-stops\n- **RBAC** — role-based access control on tool invocations (bypass mode by default)\n- **Bot Containment** — each bot account is confined to its designated VM\n\n---\n\n## WebUI\n\nThe React management dashboard provides:\n\n- **Dashboard** — real-time ticket metrics, PR pipeline, severity donut, cost trends\n- **Tickets** — Kanban board with drag-and-drop, search/filter, detail views\n- **Teams** — live status indicators, VM connectivity checks, start/stop controls\n- **Engines** — coding engine management with health checks and BYOK support\n- **Pipeline Editor** — visual workflow editor built on React Flow\n- **Settings** — governance thresholds, cycle config, memory settings\n\n```bash\ncd ui \u0026\u0026 npm install \u0026\u0026 npm run dev\n# Opens at http://localhost:5173, proxies API to :8888\n```\n\n---\n\n## Requirements\n\n- **Node.js 20+** + **pnpm** — TypeScript control plane\n- **Python 3.10+** — agent library and tests\n- **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)** — coding engine\n- **[GitHub CLI](https://cli.github.com/)** (`gh`) — authenticated for issue + PR management\n- **Supabase** — ticket store + semantic memory (pgvector)\n- **Telegram bot** (optional) — notifications\n- **SSH access** to worker VMs (optional) — remote log collection\n\n---\n\n## Roadmap\n\n- [x] Persistent pi-agent daemon with 16 custom tools\n- [x] Engine-agnostic delegation (Claude CLI, Gemini CLI, Copilot, OpenCode)\n- [x] Semantic memory with pgvector embeddings + confidence tracking\n- [x] Full ticket pipeline: import, investigate, develop, review, merge\n- [x] Safety gates: circuit breaker, stability gate, outcome tracker\n- [x] React WebUI with Kanban, pipeline editor, team management\n- [x] Multi-team deployment (alpha/beta/gamma squads)\n- [x] Provider-agnostic plugin architecture\n- [ ] Interactive Telegram bot — bidirectional chatbot for remote control ([#1034](https://github.com/ArtemisAI/SWE-Squad/issues/1034))\n- [ ] Multi-VM deployment automation\n- [ ] npm package: `@swe-squad/control-plane`\n- [ ] Public repo sync and launch\n- [ ] Slack/Discord notification plugins\n- [ ] Metrics and observability (Prometheus/Grafana)\n- [ ] Automated benchmarking suite\n\n---\n\n## Contributing\n\nWe welcome contributions! Areas where help is most valuable:\n\n- Additional coding engine adapters\n- Notification channel plugins (Slack, Discord)\n- Interactive Telegram bot ([#1034](https://github.com/ArtemisAI/SWE-Squad/issues/1034))\n- New ticket store backends (Redis, SQLite)\n- Agent prompt optimization and benchmarking\n- Documentation and tutorials\n\n---\n\n## License\n\n[MIT](LICENSE) — use it, fork it, build on it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArtemisAI%2FSWE-Squad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FArtemisAI%2FSWE-Squad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FArtemisAI%2FSWE-Squad/lists"}