Basou — Camada de Proveniência para Agentes de IA
basou-dev/basou
Registro estruturado, replay e rastreabilidade para sessões de agentes de IA
Ver no GitHubBasou registra e reproduz o trabalho de agentes de código (como Claude Code) em trilhas estruturadas e reutilizáveis. Captura sessões, decisões, snapshots git e saída de comandos em JSONL, oferecendo visualização em Markdown e cockpit web local para análise e auditoria completa.
Instalação
npx convez-ai basou-dev/basou1 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
Casos de uso
- Auditar e reproduzir trabalho executado por agentes de código
- Manter trilha estruturada de decisões e aprovações em projetos de IA
- Revisar histórico de mudanças e snapshots git com contexto de agente
Veredito

Ferramenta madura e honestamente posicionada como projeto pessoal do autor (v0.7.0). Excelente para quem trabalha intensivamente com Claude Code e precisa auditoria e rastreabilidade rigorosa; não recomendado para quem busca produto com suporte estável ou integração com múltiplos agentes.
README
A tradução para o português deste README ainda está na fila.
Basou
Provenance layer for AI development.
Today: Basou live-wraps Claude Code only (basou run claude-code) and
imports native logs from both Claude Code and Codex (basou import ...).
Roadmap (no dates): live-wrap for more agent CLIs (OpenCode) that fit the
same process-wrap model. OpenRouter / Ollama are tracked separately as a
per-request capture mode, not yet designed.
Status: personal tool, v0.7.0. Built by one author for their own Claude
Code sessions and updated occasionally — not a supported product. The CLI
surface is frozen for the 0.x line; internal @basou/core APIs may still
change between minor releases. Bug reports are welcome; feature requests are
evaluated against the author's own use case.
What is Basou?
Basou records what AI coding agents do — sessions, decisions, approvals, git snapshots, and command output — into a structured, replayable trail that lives next to your code.
- JSONL as the source of truth. Every observable event (command run, file
changed, decision recorded, approval resolved) is appended to
.basou/sessions/<session_id>/events.jsonl. - Markdown as the human view.
.basou/handoff.mdand.basou/decisions.mdare regenerated from the event log and may be hand-edited; both forms can be reviewed in any text editor or PR. - Tasks as the goal unit. A task may span multiple sessions; the
task.mdsnapshot stays in sync with the event log viabasou task reconcile/basou task refresh-linkage. - Claude Code is the one live-run adapter today.
basou run claude-codewraps the process so the surrounding session is recorded without Basou knowing about Anthropic-internal formats. Native-log import additionally covers Codex:basou import claude-codeandbasou import codexderive sessions from each tool's own logs after the fact. More live-run adapters (OpenCode) are on the roadmap, not yet built. - A local cockpit, for the author.
basou refreshimports the project's native agent logs and regenerates the markdown in one step;basou viewopens a localhost-only web UI to browse sessions, tasks, decisions, and handoff and run those actions by clicking. Both are conveniences — the CLI and Markdown stay the primary surface, and the viewer binds to 127.0.0.1 with no authentication (a personal tool, never exposed beyond your machine).
Recent highlights:
- Native-log import:
basou import claude-code/basou import codexderive sessions from each tool's own logs, with multi-root capture across sibling repositories. - Local cockpit:
basou refresh(andbasou refresh --watch) keep the workspace current;basou viewopens a localhost-only web UI. - Work stats:
basou statsreports per-session and aggregate activity. - Read-only SDK + JSON Schemas:
@basou/sdkreads a workspace's provenance programmatically, and@basou/coreships JSON Schemas for the on-disk.basou/formats.
See CHANGELOG.md for the full per-release breakdown.
Quickstart (5 minutes)
# 1. Install the CLI from npm (see Installation below for the from-source path)
npm install -g @basou/cli
# 2. Initialize a workspace at the root of any Git repo
cd /path/to/your/project
basou init
# 3. Record a task + a session note
basou task new --title "Refactor login form"
basou session note --body "Started exploring auth.ts"
# 4. Regenerate the human-readable summary
basou handoff generate
cat .basou/handoff.md
# 5. Or skip the per-command typing: import the project's native agent logs
# and regenerate handoff + decisions in one step, then browse it all in a
# local web UI (localhost only, no authentication)
basou refresh
basou view
For a step-by-step walkthrough with failure modes and sample output, see basou.dev/quickstart/. For the underlying data model, see docs/spec/.
Packages
| Package | Description | Status |
|---|---|---|
@basou/cli | The basou command-line tool | Published on npm |
@basou/core | Core library: sessions, events, approvals, git capability | Published on npm |
@basou/sdk | Read-only SDK for reading a workspace's provenance | Published on npm |
Installation
From npm (recommended)
Requires Node.js >= 20.10.0.
npm install -g @basou/cli
# Verify
basou --version
See basou.dev/installation/ for upgrade and troubleshooting notes.
From source
Build from main to track changes ahead of the published releases.
Requirements:
- Node.js >= 20.10.0
- pnpm >= 8.15.0
- Git
git clone https://github.com/basou-dev/basou.git
cd basou
pnpm install
pnpm -r build
pnpm --filter @basou/cli link --global
# Verify
basou --version
Development
pnpm install
pnpm typecheck
pnpm lint
pnpm test # full unit + integration suite
pnpm -r build
Project Structure
basou/
├── packages/
│ ├── core/ # @basou/core — provenance primitives
│ ├── cli/ # @basou/cli — `basou` command
│ └── sdk/ # @basou/sdk — read-only provenance SDK
├── docs/
│ ├── quickstart.md # Redirect stub → basou.dev/quickstart/
│ └── spec/ # workspace layout, schemas, CLI surface, ...
├── apps/ # Reserved for future GUI / desktop apps
├── CHANGELOG.md
└── README.md
License
Apache 2.0 — see LICENSE. Copyright Basou Project Contributors.
Links
- Documentation: https://basou.dev/getting-started/
- Website: https://basou.dev
- GitHub: https://github.com/basou-dev/basou
- npm: https://www.npmjs.com/org/basou