codesquad-ai

codesquad

Crie squads de agentes de IA que entregam software juntos — direto da sua IDE.

codesquad é um framework de orquestração multi-agente focado em desenvolvimento de software. Descreva o que você precisa em linguagem natural, e o codesquad monta uma equipe de agentes especializados — spec, arquitetura, código, teste, revisão — que trabalham em pipeline com checkpoints humanos.

Sobre esta versão: fork focado em engenharia de software, derivado do opensquad de Renato Asse. O motor de orquestração é o mesmo; o que muda é o foco — best practices, skills e squads inclusos são todos de desenvolvimento de software.

O que é um Squad?

Um squad é uma equipe de agentes de IA que colaboram em uma tarefa. Cada agente tem um papel específico e uma única responsabilidade. Eles executam em pipeline com checkpoints onde o agente pausa e pede sua aprovação antes de continuar. Os checkpoints são instruções no pipeline — o enforcement real de permissões depende da IDE host (ex: Claude Code, Cursor).

Exemplo (o squad dev-crew, instalado por padrão):

• Spec-writer transforma o pedido ou a issue numa especificação com critérios de aceite
• Architect desenha a mudança (módulos, contratos, ADR) antes de uma linha de código
• Coder implementa exatamente o escopo aprovado, em commits lógicos
• Tester escreve e roda os testes — a suíte verde é um gate obrigatório
• Reviewer revisa o diff de forma adversarial antes de liberar o PR

Squads inclusos

O npx codesquad-ai init instala um squad por padrão — o dev-crew, um time de engenharia de software de ponta a ponta — e mantém três squads especializados no registro, prontos para instalar quando precisar (npx codesquad-ai squads install <nome>).

Padrão:

Squad	Faz	Pipeline	Gate mecânico
dev-crew · Time de Engenharia de Software	Tarefa de software → análise, desenvolvimento, qualidade e testagem, ancorado em best-practices de engenharia e práticas de mercado	spec → design → implement → verify → review → entrega	Suíte verde antes da revisão; só APPROVE habilita a entrega

Os cinco papéis do dev-crew cobrem as quatro fases: Spec-writer + Architect (análise), Coder (desenvolvimento), Tester (testagem) e Reviewer (qualidade).

Especializados (opcionais — instale com npx codesquad-ai squads install <nome>):

Squad	Faz	Pipeline	Gate mecânico
bug-hunter	Relato de bug → fix verificado com teste de regressão	reproduzir → diagnosticar causa raiz → fix + teste → verificar	O teste de regressão precisa falhar no código antigo e passar no novo
refactor	Melhora a estrutura sem mudar o comportamento	alvo → rede de segurança → plano → passos pequenos → verificar	Rede de segurança verde antes; comportamento preservado depois
pr-review	Revisa um PR de terceiro e posta um veredito estruturado	contexto → revisão adversarial → veredito → (checkpoint) → postar	Regra de severidade: qualquer BLOCKER → REQUEST CHANGES

Cada squad já vem com agentes, pipeline, gates e arquivos de dados (convenções do repo, rubrica de revisão, catálogo de refactor). Use como estão ou edite com /codesquad edit <nome>.

Para gerenciá-los pelo terminal: npx codesquad-ai squads (lista instalados e disponíveis), npx codesquad-ai squads install <nome> e npx codesquad-ai squads remove <nome>.

Compondo squads (cola manual)

O codesquad roda um squad por vez — não há encadeamento automático entre squads (proposital: encadeamento ramificado tiraria a nitidez dos gates). Mas como cada squad grava artefatos em squads/{nome}/output/{run_id}/ e o intake do dev-crew aceita qualquer pedido ou arquivo, dá pra encadear na mão.

Revisão → correção (o pr-review alimenta o dev-crew):

1. Rode o pr-review num PR — ele grava os achados em squads/pr-review/output/{run_id}/findings.md (agrupados por BLOCKER/MAJOR/MINOR/NIT).
2. Rode o dev-crew apontando para eles. No pedido:

   Implemente as correções dos itens BLOCKER e MAJOR de squads/pr-review/output/{run_id}/findings.md

O dev-crew transforma os achados numa spec e segue spec → design → implement → test → review.

Mesmo padrão para os outros especializados:

• bug-hunter → dev-crew: o root-cause.md (diagnóstico) vira o brief de uma correção ou evolução maior.
• refactor → dev-crew: o refactor-plan.md (plano/alvo) orienta uma mudança estrutural mais ampla.

É cola humana: você referencia o caminho do arquivo (ou cola o conteúdo). O spec-writer do dev-crew reinterpreta os achados numa spec nova — confira essa spec no primeiro checkpoint antes de aprovar.

Para quem?

Para quem escreve, mantém ou revisa software e quer automatizar o trabalho repetitivo de engenharia com agentes — sem abrir mão do controle humano nos pontos que importam.

• Devs individuais — transforme uma issue em PR pronto, cace bugs com teste de regressão, refatore com rede de segurança
• Times de engenharia — pipelines reutilizáveis com checkpoints e gates que impõem testes verdes e revisão antes do merge
• Tech leads / mantenedores — revisão adversarial padronizada de PRs (inclusive de dependabot e contribuidores externos)
• Times de plataforma/DevOps — squads para auditar CI/CD, revisar segurança e documentar runbooks e ADRs

O que dá pra fazer?

• Entregar uma feature — da spec ao PR, com testes e revisão adversarial no caminho
• Caçar um bug — reproduzir, achar a causa raiz (não o sintoma) e corrigir com teste de regressão
• Refatorar com segurança — testes de caracterização primeiro, depois passos pequenos e reversíveis, comportamento preservado
• Revisar PRs — findings por severidade com file:line, passada de segurança e veredito por regra mecânica
• Projetar APIs e arquitetura — modelagem de recursos, versionamento, ADRs antes da implementação
• Revisão de segurança — checklist estilo OWASP sobre o diff (injeção, authz, segredos, dependências)
• Documentação técnica — READMEs, docs de API, runbooks, guias de migração, changelogs
• E muito mais — qualquer fluxo de engenharia que envolva especificar, construir, verificar ou revisar

Instalação

Pré-requisito: Node.js 20+

npx codesquad-ai init

Funciona tanto num projeto novo quanto num projeto já existente — o comando adiciona o _codesquad/, os squads, o dashboard e os arquivos da sua IDE na pasta atual, sem tocar no seu código. Os quatro squads inclusos são instalados automaticamente; para adicionar ou remover um depois, use npx codesquad-ai squads install <nome> (veja Comandos).

Nota: rode sua IDE de IA de dentro do diretório do projeto onde você executou npx codesquad-ai init. O comando /codesquad só fica disponível quando a IDE é aberta nessa pasta.

Para atualizar uma instalação existente:

npx codesquad-ai update

IDEs Suportadas

IDE	Status
Claude Code	Disponível
Cursor	Disponível
VS Code + Copilot	Disponível
Codex (OpenAI)	Disponível
Open Code	Disponível
Antigravity	Disponível
Gemini CLI	Disponível
Qwen Code	Disponível
Trae	Disponível

Escritório Virtual

O Escritório Virtual é uma interface visual 2D que mostra seus agentes trabalhando — ele se atualiza a cada passo do pipeline (não token a token).

O dashboard já é instalado pelo npx codesquad-ai init, na pasta dashboard/ do projeto. Para rodá-lo ao vivo (no terminal, dentro do projeto):

cd dashboard
npm install   # primeira vez
npm run dev

Abra o endereço mostrado (padrão http://localhost:5173). O dashboard observa os state.json dos squads e atualiza ao vivo enquanto eles trabalham — com linha do tempo, replay e painel de checkpoint.

Modo produção (build + servidor ao vivo):

cd dashboard
npm run build
npm run serve   # http://localhost:4173

Use npm run serve, não um servidor estático comum: o build sozinho (ex.: npx serve) não recebe atualizações ao vivo, pois não expõe o WebSocket nem o watcher de arquivos.

Criando seu Squad

Abra o menu:

/codesquad

Para criar um novo squad, selecione a opção e o Arquiteto faz algumas perguntas, projeta o squad e configura tudo automaticamente. Você aprova o design antes de qualquer execução.

Executando um Squad

/codesquad rode o squad <nome-do-squad>

O squad executa automaticamente, pausando nos checkpoints onde o agente pede sua aprovação.

Exemplos

/codesquad
/codesquad rode o squad dev-crew
/codesquad rode o squad bug-hunter
/codesquad crie um Squad que audita um pipeline de CI e propõe gates de qualidade
/codesquad crie um Squad que projeta uma API REST a partir de um documento de requisitos
/codesquad crie um Squad que gera testes de caracterização para um módulo legado sem cobertura

Comandos

Comando	O que faz
/codesquad	Abre o menu principal
/codesquad help	Mostra todos os comandos
/codesquad create	Cria um novo squad
/codesquad run <nome>	Executa um squad
/codesquad list	Lista seus squads
/codesquad edit <nome>	Modifica um squad
/codesquad skills	Navega pelas skills instaladas
/codesquad install <nome>	Instala uma skill do catálogo
/codesquad uninstall <nome>	Remove uma skill instalada

Esses são os comandos dentro da IDE. No terminal, a CLI npx codesquad-ai cuida da instalação e do gerenciamento:

Comando (terminal)	O que faz
npx codesquad-ai init	Instala o codesquad no projeto atual (novo ou existente)
npx codesquad-ai update	Atualiza o core
npx codesquad-ai squads	Lista squads instalados e disponíveis
npx codesquad-ai squads install <nome>	Instala um squad incluso (ex.: bug-hunter)
npx codesquad-ai squads remove <nome>	Remove um squad instalado
npx codesquad-ai install <skill>	Instala uma skill do catálogo
npx codesquad-ai uninstall <skill>	Remove uma skill
npx codesquad-ai skills	Lista skills instaladas
npx codesquad-ai agents · agents install <nome>	Lista / instala agentes predefinidos
npx codesquad-ai runs [squad]	Histórico de execuções

Custo de Tokens

O codesquad é open source e gratuito como software. É possível usá-lo de forma 100% gratuita com stacks como Google Antigravity (free tier com Gemini) ou OpenCode com LLMs locais (Ollama, LM Studio, etc.).

Stacks como Claude Code (Claude Pro/Max) e API da OpenAI consomem tokens pagos:

• Cada execução de squad consome tokens — a quantidade depende do número de agentes, da complexidade do pipeline e do modelo escolhido.
• Investigação de codebase (mapear convenções do repo antes do primeiro run) e suítes de teste grandes são operações mais intensivas.
• O framework carrega prompts de sistema, best practices e instruções de agentes no contexto — o que contribui para o consumo base de cada execução.

Se estiver usando uma stack paga, recomendamos monitorar seu consumo na sua IDE ou no dashboard do provedor de IA.

Investigação de Codebase e Privacidade

Antes do primeiro run, um squad pode rodar uma investigação opcional do repositório-alvo para que os agentes sigam as convenções reais do projeto (módulo ESM/CJS, estilo de erro, comandos de teste) em vez de defaults genéricos.

• Escopo local: a investigação lê o código do repositório que você apontar (caminho local ou git URL).
• Sem segredos no contexto: os agentes não devem ler nem commitar .env, segredos ou saída de build — isso está nas convenções e nos anti-patterns de cada squad.
• Artefatos versionados com cuidado: memória e investigações ficam em _codesquad/ e respeitam o .gitignore do projeto.

Sobre

Fork focado em desenvolvimento de software do opensquad, projeto open source criado por Renato Asse. O motor de orquestração multi-agente é mantido; o foco foi reorientado para engenharia — best practices, skills e squads inclusos são de desenvolvimento de software.

Contribuições são bem-vindas. Veja o CONTRIBUTING.md para saber como participar.

Licença

MIT — use como quiser.

---

codesquad (English)

Create AI squads that ship software together — right from your IDE.

codesquad is a multi-agent orchestration framework focused on software development. Describe what you need in plain language, and codesquad assembles a team of specialized agents — spec, architecture, code, test, review — that run in a pipeline with human checkpoints.

About this version: a software-engineering-focused fork derived from Renato Asse's opensquad. The orchestration engine is the same; the focus is what changed — the bundled best practices, skills, and squads are all software development.

What is a Squad?

A squad is a team of AI agents that collaborate on a task. Each agent has one clear responsibility. They run in a pipeline with checkpoints where the agent pauses and asks for your approval before continuing. Checkpoints are instructions in the pipeline — actual permission enforcement depends on the host IDE (e.g., Claude Code, Cursor).

Example (the dev-crew squad, installed by default):

• Spec-writer turns the request or issue into a spec with acceptance criteria
• Architect designs the change (modules, contracts, ADR) before any code
• Coder implements exactly the approved scope, in logical commits
• Tester writes and runs the tests — a green suite is a hard gate
• Reviewer reviews the diff adversarially before a PR is allowed

Built-in squads

npx codesquad-ai init installs one squad by default — dev-crew, an end-to-end software engineering team — and keeps three specialized squads in the registry, ready to install when you need them (npx codesquad-ai squads install <name>).

Default:

Squad	Does	Pipeline	Mechanical gate
dev-crew · Software Engineering Team	A software task → analysis, development, quality, and testing, grounded in engineering best practices and market practice	spec → design → implement → verify → review → ship	Green suite before review; only APPROVE unlocks delivery

dev-crew's five roles cover the four phases: Spec-writer + Architect (analysis), Coder (development), Tester (testing), Reviewer (quality).

Specialized (optional — install with npx codesquad-ai squads install <name>):

Squad	Does	Pipeline	Mechanical gate
bug-hunter	Bug report → verified fix with a regression test	reproduce → root cause → fix + test → verify	The regression test must fail on the old code and pass on the new
refactor	Improves structure without changing behavior	target → safety net → plan → small steps → verify	Safety net green first; behavior preserved after
pr-review	Reviews someone's PR and posts a structured verdict	context → adversarial review → verdict → (checkpoint) → post	Severity rule: any BLOCKER → REQUEST CHANGES

Each squad ships with agents, pipeline, gates, and data files (repo conventions, review rubric, refactor catalog). Use them as-is or edit with /codesquad edit <name>.

Composing squads (manual handoff)

codesquad runs one squad per execution — there's no automatic squad-to-squad chaining (by design: branchy chaining would blunt the gates). But since each squad writes artifacts to squads/{name}/output/{run_id}/ and dev-crew's intake accepts any request or file, you can hand off by hand.

Review → fix (pr-review feeds dev-crew):

1. Run pr-review on a PR — it writes findings to squads/pr-review/output/{run_id}/findings.md (grouped by BLOCKER/MAJOR/MINOR/NIT).
2. Run dev-crew pointing at them. In the request:

   Implement the fixes for the BLOCKER and MAJOR items in squads/pr-review/output/{run_id}/findings.md

dev-crew turns the findings into a spec, then runs spec → design → implement → test → review.

Same pattern for the other specialized squads:

• bug-hunter → dev-crew: root-cause.md (the diagnosis) becomes the brief for a larger fix or evolution.
• refactor → dev-crew: refactor-plan.md (the plan/target) drives a broader structural change.

It's human glue: you reference the file path (or paste the content). dev-crew's spec-writer reinterprets the findings into a fresh spec — review it at the first checkpoint before approving.

Who is it for?

For people who write, maintain, or review software and want to automate the repetitive parts of engineering with agents — without giving up human control at the points that matter.

• Individual devs — turn an issue into a ready PR, hunt bugs with a regression test, refactor with a safety net
• Engineering teams — reusable pipelines with checkpoints and gates that enforce green tests and review before merge
• Tech leads / maintainers — standardized adversarial PR review (including dependabot and outside contributors)
• Platform/DevOps teams — squads to audit CI/CD, review security, and document runbooks and ADRs

Installation

Prerequisite: Node.js 20+

npx codesquad-ai init

Note: Always run your AI IDE from inside the project directory where you ran npx codesquad-ai init. The /codesquad command is only available when the IDE is opened in that folder.

To update an existing installation:

npx codesquad-ai update

Supported IDEs

IDE	Status
Claude Code	Available
Cursor	Available
VS Code + Copilot	Available
Codex (OpenAI)	Available
Open Code	Available
Antigravity	Available
Gemini CLI	Available
Qwen Code	Available
Trae	Available

Virtual Office

The Virtual Office is a 2D visual interface that shows your agents working — it refreshes on each pipeline step (not token by token).

The dashboard is installed by npx codesquad-ai init, in the project's dashboard/ folder. To run it live (in the terminal, inside the project):

cd dashboard
npm install   # first time
npm run dev

Open the address shown (default http://localhost:5173). The dashboard watches each squad's state.json and updates live as they work — with a timeline, replay, and checkpoint panel.

Production mode (build + live server):

cd dashboard
npm run build
npm run serve   # http://localhost:4173

Use npm run serve, not a plain static server: the build alone (e.g. npx serve) gets no live updates, since it exposes neither the WebSocket nor the file watcher.

Creating your Squad

Describe what you need:

/codesquad create "A squad that designs a REST API from a requirements doc"

The Architect asks a few questions, designs the squad, and sets everything up automatically. You approve the design before any execution begins.

Running a Squad

/codesquad run <squad-name>

The squad runs automatically, pausing at checkpoints where the agent asks for your approval.

Examples

/codesquad run dev-crew
/codesquad run bug-hunter
/codesquad create "Squad that audits a CI pipeline and proposes quality gates"
/codesquad create "Squad that designs a REST API from a requirements document"
/codesquad create "Squad that generates characterization tests for an uncovered legacy module"

Commands

Command	What it does
/codesquad	Open the main menu
/codesquad help	Show all commands
/codesquad create	Create a new squad
/codesquad run <name>	Run a squad
/codesquad list	See all your squads
/codesquad edit <name>	Modify a squad
/codesquad skills	Browse installed skills
/codesquad install <name>	Install a skill from catalog
/codesquad uninstall <name>	Remove an installed skill

Those run inside the IDE. In the terminal, the npx codesquad-ai CLI handles install and management:

Command (terminal)	What it does
npx codesquad-ai init	Install Codesquad into the current project (new or existing)
npx codesquad-ai update	Update the core
npx codesquad-ai squads	List installed + available squads
npx codesquad-ai squads install <name>	Install a built-in squad (e.g. bug-hunter)
npx codesquad-ai squads remove <name>	Remove an installed squad
npx codesquad-ai install <skill>	Install a skill from the catalog
npx codesquad-ai uninstall <skill>	Remove a skill
npx codesquad-ai skills	List installed skills
npx codesquad-ai agents · agents install <name>	List / install predefined agents
npx codesquad-ai runs [squad]	Execution history

Token Cost

codesquad is open source and free as software. You can use it completely free with stacks like Google Antigravity (free tier with Gemini) or OpenCode with local LLMs (Ollama, LM Studio, etc.).

Stacks like Claude Code (Claude Pro/Max) and OpenAI API consume paid tokens:

• Every squad run consumes tokens — the amount depends on the number of agents, pipeline complexity, and the model chosen.
• Codebase investigation (mapping repo conventions before the first run) and large test suites are the more intensive operations.
• The framework loads system prompts, best practices, and agent instructions into context — contributing to the base token consumption of every run.

If using a paid stack, we recommend monitoring your usage in your IDE or your AI provider's dashboard.

Codebase Investigation & Privacy

Before the first run, a squad can run an optional investigation of the target repository so agents follow the project's real conventions (ESM/CJS module system, error style, test commands) instead of generic defaults.

• Local scope: the investigation reads the code of the repo you point it at (local path or git URL).
• No secrets in context: agents must not read or commit .env, secrets, or build output — this is encoded in each squad's conventions and anti-patterns.
• Carefully versioned artifacts: memory and investigations live under _codesquad/ and respect the project's .gitignore.

About

A software-development-focused fork of opensquad, an open source project created by Renato Asse. The multi-agent orchestration engine is preserved; the focus was reoriented toward engineering — the bundled best practices, skills, and squads are all software development.

Contributions are welcome. See CONTRIBUTING.md to learn how to participate.

License

MIT — use it however you want.