How-to: iniciar um novo projeto no framework¶
Fluxo simplificado: 1 instalação + 1 abertura do VS Code = tudo armado. Sem terminal, sem comandos manuais.
Pré-requisitos (uma vez)¶
# Clone + venv + deps
git clone https://github.com/Claudinoinsights/mult-agentes.git
cd mult-agentes
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Mac/Linux
pip install -e ".[dev,test,dashboard,observability]"
# .env mínimo
cp .env.example .env
# Instala a extension VS Code (uma vez por máquina)
code --install-extension vscode-extension/mult-agentes-organismo-0.2.0.vsix
Dia-a-dia — 3 passos¶
1. Abrir VS Code¶
Da primeira vez VS Code pergunta: - "Trust the authors?" → Yes - "Install recommended extensions?" → Install (se ainda não instalou)
A extension fica ativa. Status bar (canto inferior direito) mostra:
A extension auto-boota o dashboard quando o VS Code abre. Em segundos:
2. Clicar no widget → menu de ações¶
Clique no ● Organismo (ou Ctrl+Alt+O). Aparece:
┌──────────────────────────────────────────────┐
│ 🚀 Start new capsule… iniciar trabalho │
│ 📋 List capsules histórico recente │
│ 🌐 Open Dashboard in browser http://localhost:8000 │
│ 🔄 Refresh status │
│ ⏹ Stop Dashboard │
└──────────────────────────────────────────────┘
Clica "Start new capsule" (ou Ctrl+Alt+N direto).
VS Code abre 3 prompts em sequência:
1. Descrição (≥10 chars): Implementar checkout com Stripe
2. Intent: build_feature / fix_bug / refactor / ...
3. Specialist: backend-python-specialist / frontend-specialist / ...
Pronto. Status bar atualiza:
3. Pedir trabalho pro Claude¶
No chat do VS Code:
"Implementa um checkout com Stripe."
Eu (Claude) sigo o flow normalmente, registrando cada arquivo via mag artifact. Você não precisa fazer nada — apenas observa o status bar e o dashboard.
Quando terminar, eu chamo mag done automaticamente, OU você clica no widget → "Complete current capsule" (ou Ctrl+Alt+D).
Status bar widget — 4 estados¶
| Visual | Significa |
|---|---|
● Organismo (sem cor) |
Backend rodando, sem capsule ativa |
● a3a44033 · execution · 2📎 |
Capsule ativa: id curto, phase atual, artifacts |
🟡 ● Organismo (amarelo) |
Backend down (warning) — clique pra startar |
🔴 ● a3a44033 · ... (vermelho) |
Backend down COM capsule ativa (perigo) |
Hover → tooltip com capsule_id completo, phase, artifacts, backend status.
Atalhos de teclado¶
| Atalho | Ação |
|---|---|
Ctrl+Alt+O (Cmd+Alt+O) |
Abre o menu (= clique no widget) |
Ctrl+Alt+N (Cmd+Alt+N) |
Start new capsule (prompts) |
Ctrl+Alt+A (Cmd+Alt+A) |
Record artifact (sugere arquivo aberto) |
Ctrl+Alt+D (Cmd+Alt+D) |
Complete current capsule |
Command palette (Cmd+Shift+P)¶
Todas as ações disponíveis lá. Digite "Organismo:" pra ver tudo:
Organismo: Show action menu (status bar)
Organismo: Open Dashboard
Organismo: Start Backend (uvicorn)
Organismo: Stop Backend
Organismo: Start new capsule…
Organismo: Record artifact (current file)…
Organismo: Advance phase…
Organismo: Nudge hormone…
Organismo: Complete current capsule…
Organismo: Show status
Organismo: List capsules
Organismo: Refresh status
Configuração (opcional)¶
Settings → Search "organismo":
| Setting | Default | Pra que serve |
|---|---|---|
organismo.backendUrl |
http://127.0.0.1:8000 |
URL onde o dashboard escuta |
organismo.pythonPath |
autodetect .venv/ |
Override do interpreter Python |
organismo.frameworkRoot |
primeira workspace folder | Override do path do repo |
organismo.autoStartBackend |
true |
Boota dashboard ao ativar |
Fallback (sem a extension)¶
Se não tem ou não quer a extension, ainda pode usar via terminal:
python -m src.mag dashboard # Boota dashboard manualmente
python -m src.mag start "..." # Inicia capsule
python -m src.mag artifact <path> # Registra artifact
python -m src.mag done --summary "..." # Finaliza
python -m src.mag status # Estado
Ou rode a task "Organismo: Start Dashboard (fallback)" via Ctrl+Shift+P → "Tasks: Run Task".
Troubleshooting¶
Status bar mostra 🟡 amarelo (backend down)¶
Clique no widget → "Start Dashboard". Ou Ctrl+Shift+P → "Organismo: Start Backend".
Status bar não atualiza¶
Clique no widget → "Refresh status". Output channel "Organismo" pra logs.
Extension não aparece¶
code --list-extensions | grep organismo
# Esperado: claudinoinsights.mult-agentes-organismo
# Se não mostrou:
code --install-extension vscode-extension/mult-agentes-organismo-0.2.0.vsix
"WARNING: capsule X is still active"¶
Você esqueceu de fechar a capsule anterior. Opções: - Clique no widget → "Complete current capsule" - Cmd+Shift+P → "Organismo: Complete current capsule…"
Atalho de teclado conflita¶
Settings → Keyboard Shortcuts → busque "organismo" → reassign
Como funciona por baixo¶
┌─────────────────────────────────────────────────┐
│ VS Code (com extension) │
│ ┌──────────────────────────────────────────┐ │
│ │ Status bar widget │ │
│ │ Commands (12) │ │
│ │ Webview dashboard │ │
│ │ Keyboard shortcuts │ │
│ └─────────────────┬────────────────────────┘ │
│ │ spawn subprocess │
│ ┌─────────────────┴────────────────────────┐ │
│ │ python -m src.mag <subcommand> │ │
│ │ (auto-loads .env via src._settings) │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ┌─────────────────┴────────────────────────┐ │
│ │ uvicorn (dashboard backend) │ │
│ │ + src.bridge.cli (capsule registration) │ │
│ └─────────────────┬────────────────────────┘ │
│ │ writes │
│ ┌─────────────────┴────────────────────────┐ │
│ │ _framework/ │ │
│ │ ├── current_capsule.txt │ │
│ │ ├── audit/chain.jsonl │ │
│ │ ├── events.jsonl │ │
│ │ ├── capsules.jsonl │ │
│ │ └── memory/ + observability/ │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
A extension lê current_capsule.txt + capsules.jsonl direto (fast path). Backend HTTP só pra healthcheck + dashboard webview.
Próximos passos¶
- Daily usage — manual completo com modos avançados (Docker, headless LLM)
- Tutorial 02 — passo-a-passo com explicações
- Architecture — como tudo se conecta