How-to: work with the framework inside VS Code (Claude Code)¶

The mult-agentes framework's primary execution mode is Claude Code in VS Code as the executor + the framework as a passive observability layer. You drive the work in VS Code; I (Claude) register progress through a thin bridge module; the dashboard renders everything in real time.

Mental model¶

You (humano)
    │  asks for work in VS Code
    ▼
Claude Code (eu — o executor)
    │  edits files, runs commands, writes tests
    │  calls bridge helpers to record progress
    ▼
src.bridge.Recorder
    │  writes to:
    ├─ events.jsonl       (EventBus stream)
    ├─ capsules.jsonl     (capsule state log)
    ├─ audit/chain.jsonl  (HMAC-signed Rule-24 log)
    ├─ memory/episodic/   (MirrorLearner feed)
    ├─ memory/procedural/ (skill execution patterns)
    └─ observability/agent_metrics.jsonl
    ▼
Dashboard (http://localhost:8000)
    auto-wires to the Recorder → real-time view

There is no Anthropic API key required. The model that's doing the work is the Claude session you're already paying for through VS Code.

Quickstart¶

Terminal 1 — start the dashboard:

make dashboard-real

Open http://localhost:8000. A red banner ("Backend desconectado") shows if the backend isn't reachable; a brief green flash confirms successful connection.

Then in VS Code: ask Claude to do work normally. When I (Claude) make significant progress, I'll call the bridge helpers in a Bash tool block. The dashboard refreshes instantly via WebSocket.

What I (Claude) record via the bridge¶

Every meaningful unit of work in VS Code maps to a bridge call:

Moment	Bridge call
User asks for a feature	`bridge.cli start --intent build_feature --specialist X --description "..."`
Done planning	`bridge.cli advance --capsule cap_X --phase planning`
Created a file/diff	`bridge.cli artifact --capsule cap_X --path path/to/file`
Tests passed	`bridge.cli hormone --name dopamine --magnitude 0.2`
Tests failed	`bridge.cli hormone --name cortisol --magnitude 0.15`
Capsule done	`bridge.cli complete --capsule cap_X --status success --summary "..."`

Each call is JSON in / JSON out, idempotent within a process, and persists to _framework/ so a fresh dashboard reload picks it up.

CLI reference¶

# Start a capsule (returns {"capsule_id": "cap_..."})
python -m src.bridge.cli start \
    --intent build_feature \
    --specialist backend-python-specialist \
    --description "Implementar autenticação JWT com refresh"

# Advance the phase (reception → reality_anchor → planning → gates → execution → review → handoff)
python -m src.bridge.cli advance --capsule cap_abc123 --phase planning

# Record an artifact (file, diff, command, url)
python -m src.bridge.cli artifact --capsule cap_abc123 --path src/auth.py
python -m src.bridge.cli artifact --capsule cap_abc123 --path "git commit abc" --kind command

# Nudge a hormone (cortisol/oxytocin/dopamine/adrenaline/serotonin/melatonin/insulin; magnitude ∈ [-1,1])
python -m src.bridge.cli hormone --name dopamine --magnitude 0.2

# Emit a custom event
python -m src.bridge.cli event --type capsule.received --capsule cap_X --payload '{"foo": "bar"}'

# Record an agent invocation (per AgentMetrics)
python -m src.bridge.cli invocation \
    --agent backend-python-specialist --skill jwt-auth \
    --success --duration-ms 4200

# Finalize
python -m src.bridge.cli complete --capsule cap_abc123 --status success \
    --summary "JWT implementado, 12/12 testes passando"

# Listing
python -m src.bridge.cli list                    # all capsules
python -m src.bridge.cli list --active           # active only
python -m src.bridge.cli show cap_abc123         # detail one capsule

All commands accept --framework-dir PATH to override _framework/. Otherwise they use $FRAMEWORK_DIR env var or default _framework/.

Programmatic usage (rare)¶

For tests or one-off scripts:

from src.bridge import Recorder

rec = Recorder.singleton(framework_dir="_framework")
handle = rec.start_capsule(
    intent="build_feature",
    specialist="frontend-specialist",
    description="Criar landing page com hero + features",
)
rec.advance_phase(handle.capsule_id, "execution")
rec.record_artifact(handle.capsule_id, "src/Landing.tsx")
rec.emit_hormone("dopamine", 0.2)
rec.complete_capsule(handle.capsule_id, status="success",
                     summary="Landing page entregue + 4 testes E2E")

What the dashboard shows¶

When the bridge writes anything, the dashboard reacts within ~100ms (WebSocket) or ~3-5s (SSE/poll fallback). Visible signals:

Vitals — heart rate, budget %, error rate (derived from WorldState)
Hormones — 7 levels with active flag at >0.5
Pixel agents — telemetry per specialist (invocations, success rate, last seen)
Timeline — recent significant events promoted from AgentMetrics
Events marquee — capsule.received → phase.started → ... → capsule.completed
Project tab — story progress, health score (set via agg.set_project(...))

Connection banner at the top: - 🟢 Green flash on successful connect (1.5s) - 🟡 Yellow while connecting - 🔴 Red persistent if backend down

Why this design¶

No API key needed. Claude in VS Code is the LLM.
No mock data. Phase 4 mock executor was removed; /api/chat returns 503 without a chat_invoker; the dashboard banner reflects real connection state.
Single source of truth. The same _framework/ directory that the bridge writes to is auto-wired into the dashboard via Recorder.singleton().
Audit trail intact. Every bridge call appends to the HMAC-chained audit log (Rule 24) — you can prove what happened, when, by whom, with cryptographic detection of tampering.

What this does NOT do¶

❌ Drive Claude to do work. (You drive Claude through VS Code chat.)
❌ Replace the Pipeline gates for autonomous LLM flows. (When you want headless LLM execution, see run-end-to-end.md — needs API key.)
❌ Call any external API on its own.
❌ Auto-classify or auto-route. (I, Claude, do that in conversation.)