convez.ai
SkillDesenvolvimento WebAvançado
antonioshaman

Aura Companion — IA com Aprendizado Contínuo e Modo Conselho

antonioshaman/aura-companion

Interface multi-agente com revisão contínua e conhecimento que aprende de cada sessão

Ver no GitHub
InicialPluginScore · de 0 a 100

Interface web para múltiplas sessões Claude Code/Codex com streaming, controle de permissões e Council Mode — um padrão multi-agente que emparelha um orquestrador com um observador independente. Inclui 29 skills de aprendizado adaptativo (prime, learn, self-reflect) que evoluem a base de conhecimento ao longo do tempo.

Instalação

$npx convez-ai antonioshaman/aura-companion

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
aura-companion-v2.12.0
Issues abertas
2
Contribuidores
18

Casos de uso

  • Revisão de código em tempo real com segundo ponto de vista independente
  • Captura e evolução de padrões de código e decisões arquiteturais
  • Desenvolvimento web colaborativo com orquestrador + observador

Veredito

Solução sofisticada para fluxo de trabalho multi-agente com diferencial legítimo no Council Mode. Exige conforto com arquitetura distribuída e CLI tools, mas entrega valor real em revisão contínua e retenção de conhecimento estruturado.

README

A tradução para o português deste README ainda está na fila.


What this is

Aura Companion is a browser-based interface for running multiple Claude Code and Codex sessions with streaming output, tool-call visibility, and permission control — plus Council Mode, the headline differentiator.

Why Council Mode

Council Mode pairs your main agent (the orchestrator) with an independent observer session in one click. The orchestrator runs the work; the observer wakes on each phase checkpoint, reads only the just-changed surface, and pushes grounded findings back into your chat as a BlockerBanner you cannot miss. The multi-agent pattern that worked manually in past pipelines — catching a couple of P1 issues per phase that single-author review missed — is now reproducible without two terminals and manual coordination.

The observer is a fallible second opinion, not an oracle: STOPs are prompts to look, not verdicts to obey. The user is the final judge.

How to enable it

Toggle Council Mode on the New Session dialog and pick a pairing — claude+claude (default, lowest friction) or claude+codex (experimental, cross-model independence). See the Council Mode guide for the UI tour, keyboard shortcuts (Cmd/Ctrl+Shift+O, Cmd/Ctrl+Shift+B), and degraded-mode recovery; see the architecture reference for the .council/ filesystem protocol and the state machine.

Council Mode showing orchestrator chat alongside the observer panel surfacing a STOP finding

Quick Start

git clone https://github.com/antonioshaman/aura-companion.git
cd aura-companion
cd web && bun install && bun run dev

Open http://localhost:5174.

Requirements: Bun ≥ 1.0, Claude Code CLI or Codex CLI.

# Or install the published package globally
bun install -g aura-companion

# Or run without installing
bunx aura-companion

Self-Learning

Aura Companion ships an adaptive knowledge base under .agents/knowledge/ (JSONL: patterns, gotchas, decisions, anti-patterns, codebase-facts, api-behaviors) plus three lifecycle skills:

  • /prime [focus] — load relevant knowledge before starting work (auto-filters by branch and modified files)
  • /learn <insight> — quick-capture a learning mid-session without breaking flow
  • /self-reflect — end-of-session reflection: extracts learnings, prunes stale entries

Over time, /evolve promotes recurring patterns into CLAUDE.md rules and prunes stale entries. See SELF-LEARNING.md for the full guide.

Architecture

Browser (React 19) ←→ WebSocket ←→ Hono Server (Bun) ←→ WebSocket (NDJSON) ←→ Claude Code CLI
     :5174              /ws/browser/:id        :3456        /ws/cli/:id         (--sdk-url)
  • Backend: Hono on Bun (port 3456)
  • Frontend: React 19 + Zustand + Tailwind (port 5174)
  • Monorepo: web/ (main app), landing/, relay/, platform/
  • Council Mode: filesystem protocol under .council/ — see architecture reference
  • Testing: Vitest with axe accessibility scans
  • State: Session persistence to $TMPDIR/vibe-sessions/ (survives restarts)

Skill chain

Aura Companion ships a growing skill chain across three pillars. Counts may shift between releases — ls .agents/skills/ is authoritative.

Self-Learning

SkillDescription
/primeLoad relevant knowledge before starting work
/learnQuick-capture a learning mid-session
/self-reflectEnd-of-session reflection — extract learnings, prune stale entries
/evolveMeta-skill: promote patterns to CLAUDE.md, prune stale, find knowledge gaps
/review-with-kbCode review cross-referenced with the knowledge base

Carmack Council

Based on John Carmack's engineering philosophy. A council of domain experts reviews your work.

SkillDescription
/council-planArchitect features with domain experts before writing code
/council-reviewDeep multi-perspective code review
/council-implementExecute council plans task-by-task with per-task expert guidance
/spec-writerGenerate structured specs with Job Stories + Gherkin acceptance criteria
/test-architectAudit test quality, detect AI shortcut patterns, specify tests before implementation
/self-improvementContinuous learning: log errors, corrections, and feature requests

Council experts include: Troy Hunt (security), Martin Fowler (refactoring), Kent Beck (testing), Brandur Leach (databases), Simon Willison (LLM pipelines), Karri Saarinen (UI), Vitaly Friedman (UX), plus stack-specific Backend, Realtime, Subprocess, a11y, and Deploy experts.

v2 expert catalog (22 seats, Phase 3β complete). A person-named v2 catalog lives on feat/council-v2-pipeline: 14 v1-carryover seats plus 8 Phase 3β additions seated as ideological-tension pairs (Fowler ↔ Uncle Bob, Ritchie ↔ Torvalds, Beck ↔ Hickey, Hunt ↔ Willison, Evans ↔ Fowler, Majors ↔ Hashimoto, Sridharan ↔ Majors) so synthesis becomes resolution rather than aggregation. EC-34 codifies the wire-format (paired_with + tension_axis per meta.yaml). v1 remains production default until atomic-swap promotion (Phase 6). See Expert Catalog v2 Roadmap for the full inventory and rationale; opt into v2 explicitly via -v2 skill variants (/council-plan-v2, /council-review-v2, etc.).

Design & UX

Eighteen skills from impeccable: /frontend-design, /adapt, /animate, /audit, /bolder, /clarify, /colorize, /critique, /delight, /distill, /extract, /harden, /normalize, /onboard, /optimize, /polish, /quieter, /teach-impeccable.

Recommended workflow

Feature development with Council Mode

                          (toggle Council Mode on New Session)
/council-plan          # Plan with domain experts in the orchestrator
/prime                 # Load relevant knowledge
                       # ... implement ...
                       # Observer wakes on each phase checkpoint,
                       # surfaces STOPs as BlockerBanner
/learn <insight>       # Capture learnings as you go
/review-with-kb        # Knowledge-informed review
/council-review        # Deep expert review
/self-reflect          # Capture session learnings

Bug fix

/prime <area>          # What do we know about this area?
                       # ... fix ...
/learn <gotcha>        # Why did this break?
/self-reflect          # Store for next time

Monthly maintenance

/evolve all            # Promote patterns, prune stale, find gaps
/test-architect audit  # Check test quality

Knowledge base format

Each knowledge entry is a JSONL line:

{
  "id": "pat-001",
  "type": "pattern",
  "fact": "WebSocket bridge must handle both NDJSON and JSON-RPC protocols",
  "recommendation": "Always test protocol changes against both backends",
  "confidence": "high",
  "provenance": [{"source": "codebase", "reference": "web/server/ws-bridge.ts"}],
  "tags": ["websocket", "protocol"],
  "affectedFiles": ["web/server/ws-bridge.ts"],
  "createdAt": "2026-04-24T00:00:00Z"
}

Development

# Dev server (backend + frontend)
make dev

# Type check
cd web && bun run typecheck

# Run tests
cd web && bun run test

# Build for production
cd web && bun run build && bun run start

File structure

.agents/
├── knowledge/              # Self-learning knowledge base (JSONL)
└── skills/                 # Skill catalog
web/
├── server/                 # Hono + Bun backend (Council Mode pipeline)
│   ├── session-group-coordinator.ts
│   ├── group-state-machine.ts
│   ├── checkpoint-watcher.ts
│   ├── review-watcher.ts
│   ├── observer-prompt.ts
│   └── ...
└── src/                    # React 19 frontend
    ├── components/council/ # BlockerBanner, ObserverPanel, ProviderBadges, ...
    └── ...
.council/                   # Council Mode runtime artefacts (per workspace)
├── prompts/observer-system.md
├── checkpoints/<phase>.json
└── reviews/<phase>-<provider>-observer.md

Contributing

  1. Fork the repo
  2. Create a feature branch (git checkout -b feat/your-feature)
  3. Use commitizen format for commits
  4. Run tests before pushing (cd web && bun run typecheck && bun run test)
  5. Open a PR

The knowledge base (.agents/knowledge/) is project-specific — fork it and let it grow with your codebase.

Attribution

Aura Companion is a fork of The-Vibe-Company/companion by The Vibe Company (MIT License) — the original web UI for Claude Code & Codex session bridging, published at thecompanion.sh. Council Mode pairing, the adaptive knowledge base, and the Carmack Council skill chain are Aura-specific extensions on top of that foundation. (Note: nikolaiklein/Vibe-Companion is a separate sibling fork of the same upstream, not an ancestor of Aura.)

Other credits:

License

MIT

Ver o original no GitHub

Bom para

Relacionados