Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alanpcf/cocada

Banca de LLMs que conversa pra entregar — qualidade alta, token baixo. · A chat-driven LLM crew that ships outcomes — high quality, token-thin. · Crafted Orchestration of Coding Agents for Delivery Automation.
https://github.com/alanpcf/cocada

agent ai-tools autonomous-agents claude code-generation codex delivery-rooms desktop-app developer-tools gemini llm mac mcp model-context-protocol multi-agent multi-llm oss python tauri worktree

Last synced: 13 days ago
JSON representation

Banca de LLMs que conversa pra entregar — qualidade alta, token baixo. · A chat-driven LLM crew that ships outcomes — high quality, token-thin. · Crafted Orchestration of Coding Agents for Delivery Automation.

Awesome Lists containing this project

README 

          
# Cocada



> **Uma banca de LLMs que conversa pra entregar — qualidade alta, token baixo.**

> *Crafted Orchestration of Coding Agents for Delivery Automation.*



[![CI](https://github.com/alanpcf/cocada/actions/workflows/ci.yml/badge.svg)](https://github.com/alanpcf/cocada/actions/workflows/ci.yml)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

![Python](https://img.shields.io/badge/python-3.12+-blue.svg)

![Version](https://img.shields.io/badge/version-0.103.3-D9A872.svg)

![Platform](https://img.shields.io/badge/platform-macOS%20arm64-C68B3E.svg)



Manda um pedido no chat. A banca conversa entre si pra resolver.

**🔭 Bruno + 🛠️ Thiago + 🔍 Mariana + ⚖️ Lúcia** — cada persona liga

no LLM que faz mais sentido pro trabalho dela.



**Plugou só o Claude?** Funciona — toda a banca conversa nele.

**Plugou ChatGPT + Gemini junto?** Aí a mágica começa: Bruno (Claude)

planeja, Thiago (Gemini) codifica, Mariana (GPT) revisa, e os três

cruzam ideias entre eles. **Diversidade de modelo pega bug que um sozinho ignora.**



Roteamento per-call escolhe o modelo certo pra cada passo: tarefa

trivial vai pro modelo barato, arquitetura vai pro modelo forte. Você

paga só o que cada papo pediu — não a conta de "premium em tudo".



Resultado sai como diff, PR ou patch local. Conversa rolando enquanto trabalham.



> **Status v0.103.3** (loop de aprendizado completo): a banca **aprende e se

> corrige a cada rodada** — memória do projeto ponderada por efetividade (o que

> ajuda sobe no ranking, o que atrapalha é podado sozinho), **skills externas e

> aprendidas no mesmo selector** (skill que correlaciona com falha deixa de ser

> ativada), **causa de falha recorrente vira regra de planning** que o

> coordinator lê no próximo job, e **padrão de um repo beneficia outro da mesma

> stack**. Tudo por repo+papel, cross-modelo (Claude/Gemini/Codex), atrás de

> flags `default OFF` — comportamento inalterado até graduar (gate objetivo via

> `scripts/learning_readiness.py` + `/analytics/learning-kpis`; ligue localmente

> com `~/.cocada/flags.env`). Base sólida: QualityHarness pós-job (6 gates) + 11

> gates inline em 3 camadas. 3170+ testes Python, auto-updater LIVE pra users

> v0.85.1+. Veja o [CHANGELOG](CHANGELOG.md)

> e o [roadmap](#roadmap).



## O nome — COCADA



**COCADA = Crafted Orchestration of Coding Agents for Delivery Automation.**



| C | O | C | A | D | A |

|:-:|:-:|:-:|:-:|:-:|:-:|

| **C**rafted | **O**rchestration | **C**oding | **A**gents | **D**elivery | **A**utomation |



Cocada é doce brasileiro feito à mão (coco + açúcar) — **"Crafted"** ancora

essa etimologia no inglês. O resto descreve com precisão (orchestration +

agents + delivery automation) sem perder o calor do artesanal. Coerente com

a persona **Thiago "Artesão Cocada"** que codifica no chat.



## Por que faz sentido



- **🔌 Qualquer LLM, dos principais.** Claude, ChatGPT, Gemini. CLI subscription (Max/Plus/Pro) **ou** API key nativa. Tem 1? Tudo funciona. Tem os 3? Cross-talk entre modelos vira o diferencial.

- **💬 Papo entre modelos.** Bruno fala com Thiago, Mariana revisa Thiago, Lúcia checa Mariana. Cada um na LLM que cabe melhor — diversidade pega cego de modelo único.

- **🪙 Token barato sem perder qualidade.** Roteamento per-call: tarefa trivial no modelo cheap, arquitetura no modelo premium, fallback automático quando um provider cai. Cap de custo configurável por job.

- **🏗️ Banca de verdade.** 4 personas com responsabilidades distintas. Bruno não codifica; Thiago não decide arquitetura; Mariana valida; Lúcia ⚖️ gate sensível (auth/billing/migrations).

- **📦 Entrega de verdade.** Diff aplicado no seu projeto, PR aberto no GitHub, ou patch local pra revisar. Não cospe markdown.

- **🔒 Roda local, sem nuvem nossa.** Sua máquina, seu DB, seus tokens. Telemetria opt-in.

- **🆓 Free OSS, MIT.** Sem trial, sem cartão, sem upgrade.



---



### English



> **A chat-driven LLM crew that ships outcomes — high quality, token-thin.**

> *Crafted Orchestration of Coding Agents for Delivery Automation.*



Drop a brief into the chat. The crew talks it out.

**🔭 Bruno + 🛠️ Thiago + 🔍 Mariana + ⚖️ Lúcia** — each persona plugs

into whichever LLM fits their job best.



**Plugged only Claude?** Works — the whole crew runs on it.

**Plugged ChatGPT + Gemini alongside?** That's where the magic kicks in:

Bruno (Claude) plans, Thiago (Gemini) codes, Mariana (GPT) reviews, and

the three cross-check each other. **Model diversity catches bugs a

single-model assistant misses.**



Per-call routing picks the right model for each step: trivial goes to

the cheap one, architecture goes to the strong one. You pay only what

each conversation actually asked for — not the "premium-everywhere" bill.



Outcomes ship as a diff, a PR, or a local patch. Conversation keeps flowing.



**The name — COCADA**



**COCADA = Crafted Orchestration of Coding Agents for Delivery Automation.**



| C | O | C | A | D | A |

|:-:|:-:|:-:|:-:|:-:|:-:|

| **C**rafted | **O**rchestration | **C**oding | **A**gents | **D**elivery | **A**utomation |



"Cocada" is a handcrafted Brazilian coconut sweet — **"Crafted"** anchors

that etymology in English. The rest names what it does (orchestration +

agents + delivery automation) without losing the warmth of something made

by hand. Mirrors the **Thiago "Artesão" (Cocada)** persona who codes inside

the chat.



**Why it works**



- **🔌 Any of the major LLMs** — Claude, ChatGPT, Gemini. One available? Everything still runs. All three plugged? Cross-model talk becomes the edge.

- **💬 Models talking to models** — Bruno hands off to Thiago, Mariana reviews Thiago, Lúcia gates Mariana. Diversity catches blind spots single-model crews miss.

- **🪙 Cheap tokens without cheap output** — per-call routing, auto-failover, configurable cost caps.

- **🏗️ An actual crew** — four personas with distinct responsibilities, not a single chatbot wearing four hats.

- **📦 Actual delivery** — a diff applied to your repo, a PR opened, or a local patch. Not markdown soup.

- **🔒 Runs local, no cloud of ours** — your machine, your DB, your tokens.

- **🆓 Free OSS, MIT** — no trial, no card, no upgrade.



---



## Quick start



### App desktop (recomendado)



1. Baixe a versão Mac arm64 mais recente da [página de Releases](https://github.com/alanpcf/cocada/releases) — `Cocada__aarch64.dmg`.

2. Arraste pra `Applications/` e abra. A Cocada confere o ambiente, te leva por um onboarding de 4 telas e tá pronta.

3. **Aba Salas → + Novo pedido**, descreve o que quer e despacha. Cada pedido vira uma sala — você acompanha em tempo real, e quando terminar pode clicar **Continuar nesta sala** pra encadear a próxima entrega no mesmo contexto.

4. A partir daí, atualizações chegam automaticamente — banner no topo do app quando tiver versão nova.



### CLI



```bash

# 1. Instale (PyPI)

pipx install cocada                     # ou: pip install --user cocada



# 2. Configure

cd ~/seus/projetos/seu-repo

sf init                                 # interativo: detecta LLMs, escolhe perfil

sf doctor                               # confere tudo OK



# 3. Dispare um job

sf run --brief "adiciona logging estruturado no main loop"

```



Pronto. A Cocada abre PR no GitHub quando terminar.



## Pré-requisitos



Cocada precisa de pelo menos **uma** LLM e do **GitHub CLI**.



**GitHub CLI** (obrigatório, pra abrir PRs):

```bash

brew install gh && gh auth login

```



**LLM** — escolha pelo menos uma:



| Provider | Como autenticar | Custo |

|---|---|---|

| [Claude CLI](https://docs.claude.com/en/docs/claude-code) | `claude login` | Subscription Max/Pro |

| [Gemini CLI](https://google-gemini.github.io/gemini-cli/) | `gemini auth login` | Google AI Pro/Ultra |

| [Codex CLI](https://developers.openai.com/codex/cli) | `codex auth login` | ChatGPT Plus/Pro |

| Anthropic API | `pip install 'cocada[api]'` + `ANTHROPIC_API_KEY` | Pay-per-token |

| OpenAI API | `pip install 'cocada[api]'` + `OPENAI_API_KEY` | Pay-per-token |

| Google API | `pip install 'cocada[api]'` + `GOOGLE_API_KEY` | Pay-per-token |



`sf doctor` mostra status de cada um. `sf init` te ajuda a configurar.



## Como funciona



```

você manda brief

       │

       ▼

   sala criada (worktree próprio em ~/.cocada/worktrees//)

       │

       ▼

   ┌─────────┐

   │ Bruno 🔭│  planeja: tasks + dependências + test plan

   └────┬────┘

        │

        ▼  🧐 plan_reviewer (Sonnet) revisa o plano antes do Dev

        │

        ▼

   ┌────────┐  ┌────────┐  ┌────────┐

   │Thiago 1│  │Thiago 2│  │Thiago N│  🛠️ paralelo via DAG

   └────┬───┘  └────┬───┘  └────┬───┘

        └───────────┴───────────┘

                    │

                    ▼

              ┌──────────┐

              │Mariana 🔍│  roda test plan; reprova → retry

              └─────┬────┘

                    │

                    ▼  ⚖️ Lúcia (validator) checa policy_risk + sensitive areas

                    │

                    ▼

                  ┌────┐

                  │ PR │  no GitHub via `gh` · OU branch local · OU sandbox _outputs/

                  └────┘

                    │

                    ▼

            Continuar nesta sala → próxima entrega herda worktree + contexto

```



Você pode escolher **provider+modelo por papel** (Bruno/Thiago/Mariana) via **perfis**:



```

Perfis disponíveis:

  1. Padrão Cocada [oficial]

     A combinação que entrega resultado rápido com baixo custo.

  2. Premium

     Modelos top em todos os papéis. Mais caro, mais robusto.

  3. Econômico

     Modelos baratos pra exploração rápida.

  4. Velocidade

     Modelos rápidos pra iterações curtas.

  5. Em branco

     Sem defaults. Você preenche tudo.

```



## Comandos



```bash

sf init                     # bootstrap interativo do repo

sf doctor                   # diagnóstico do ambiente



sf run --brief "..."        # dispara um job

sf status               # status sem rodar nada

sf abort                # encerra job (mata processos)

sf resume               # força replan + retoma



sf tui                      # dashboard interativo (mesmo de `sf` sem args)

sf watch                # abre TUI focado num job



sf serve                    # sobe API REST FastAPI em :8765

sf worker                   # consome job_queue (multi-worker via SQL queue)

```



## Estrutura



```

cocada/

├── apps/

│   ├── cli/                 # sf init + sf doctor (voz da marca)

│   ├── api/                 # FastAPI REST :8765 (JWT single-user auto-gerado)

│   ├── orchestrator/        # Bruno → Thiago → Mariana pipeline + DAG scheduler

│   ├── tui/                 # Textual: dashboard + new job + detail

│   └── worker/              # poll job_queue, processar

├── packages/

│   ├── providers/           # registry + adapters (claude/gemini/codex CLI + anthropic/openai/google API)

│   ├── profiles/            # perfis (Padrão Cocada + templates)

│   ├── db/                  # SQLAlchemy 2.0 (SQLite default ou Postgres opt-in)

│   ├── llm/providers/       # adapters CLI legados (referenciados pelo registry)

│   ├── executor/            # git worktree, file ops, setup hooks

│   └── github/              # gh CLI wrapper (PRs)

└── scripts/spike.py         # entry point CLI (sf / cocada)

```



## Configuração



**DB.** Default SQLite local em `~/.cocada/cocada.db` (zero setup). Postgres opcional:



```bash

DATABASE_URL=postgresql://user:pass@host/db sf run ...

```



**Credenciais.** Username/senha/JWT secret auto-gerados no primeiro start, salvos no keychain do OS (ou `~/.cocada/auth.json` chmod 600 como fallback).



**Por repositório.** `sf init` cria `.factory/factory.toml` com perfil ativo + overrides finos. Versione no git.



**API keys.** `sf init` te ajuda; ou cole em Settings → LLMs (Fase 3, app desktop); ou exporte `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY`.



## Privacidade



A Cocada vem com telemetria **desligada** por padrão. Brief/código/repos nunca saem da sua máquina. Detalhes do que é enviado *se você optar-in* em [`docs/telemetry.md`](docs/telemetry.md).



## Limitações conhecidas



- **Sem notarização Apple** — primeiro open no Mac pede "Open Anyway" em System Settings → Privacy & Security. Free OSS, sem certificado de developer pago.

- **Só Mac arm64** — Linux/Windows builds chegam quando houver demanda.

- **Sem terminal embutido** — usa o terminal nativo do OS. xterm.js fica em backlog.



Roadmap: notarização Apple e suporte multi-OS conforme demanda da comunidade.



## Roadmap



| Fase | Entrega | Estado |

|---|---|---|

| 1 | Backend (DB dual, providers, perfis, auth, CLI) | ✅ |

| 2 | App desktop Tauri 2 + tema Cocada + "Cocada Queimada" (dark) | ✅ |

| 3 | Dashboard + JobDetail + NewJob + Settings (LLMs/Perfis) | ✅ |

| 4 | Lifecycle (Tauri sobe API), onboarding wizard, telemetria opt-in | ✅ |

| 5 | Build .dmg Mac arm64 + auto-updater assinado + 63 releases shipped | ✅ |

| 6 | Onda 4.5: PromptCompiler + Lúcia ⚖️ validator + Chat entity + Worktrees | ✅ |

| 7 | Multi-chat + Salas como home + WS livestream + N jobs por sala | ✅ |

| 8 | Onda 4 técnica (auto-repair plano, snapshot pré/pós, failure_kind, plan_reviewer, drift detector) | ✅ |

| 9 | Onda 4 fatia 4 (DiffSnapshot canônico, QA brief determinístico, policy navegável, Lúcia fail-closed, base_sha imutável, repo_id forte) | ✅ |

| 10 | Rename físico cto/dev/qa → coordinator/builder/reviewer (F0–F8, F9 drop legacy em v0.70+) | ✅ |

| 11 | Notarização Apple + smoke E2E externo + eval suite (10 briefs) | **em curso** |

| 12 | Loop de aprendizado completo: efetividade de memória+skills, taxonomia de falha→planning, meta-aprendizado entre repos (4 estágios, atrás de flags `default OFF`, graduação por dogfood) | ✅ |

| 13 | TUI Textual completo, Linux/Win builds, terminal embutido | backlog |



## Contribuir



Cocada é free OSS, MIT. PRs, issues, ideias bem-vindas. Antes de mergulhar, lê [CONTRIBUTING.md](CONTRIBUTING.md) e [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Discussões abertas em GitHub Discussions.



## Licença



[MIT](LICENSE). Bom proveito.