aidebrief 0.4.0

AI decision audit trail for engineering teams — capture, search, and review decisions from every coding AI

aidebrief

AI decision audit trail for engineering teams.

Every AI coding conversation — from Copilot, Claude Code, opencode — makes decisions about your codebase. None of them leave a durable record.

aidebrief captures every conversation, extracts structured engineering decisions, and gives you a queryable audit trail across all your AI tools. No cloud, no telemetry, no infrastructure.

Think git log for AI decisions.

Quick start

pip install aidebrief
aidebrief init
aidebrief review

Solo workflow

# Browse recent sessions with decision counts
aidebrief review

# Decisions grouped by topic across all sessions
aidebrief review --decisions

# Search extracted decisions
aidebrief decisions sqlite

# Full-text search across all conversations
aidebrief search "why did we use WAL mode"

# Structured summary of a single session
aidebrief summarize <session_id>

# Check if a proposal contradicts past decisions
aidebrief contradictions "use PostgreSQL instead of SQLite"

# Find all contradictory decisions across sessions
aidebrief audit

# Investigate all decisions about a topic
aidebrief diff sqlite

# Suppress a false-positive contradiction
aidebrief suppress sqlite --reason "acknowledged, won't fix"

# Database summary with source breakdown
aidebrief status

# Everything works as JSON for piping
aidebrief audit --json
aidebrief decisions --json

Team sync

Share decisions across your team via a git repository. No server needed, no infrastructure, no cloud. Just git.

The idea: each developer captures decisions locally, then push exports them to a shared git repo. Anyone can pull to see the team's collective decision trail, filter by person (--author alice), and run audits across the entire team.

Each dev:  capture → local DB → push → team/decisions/*.json
Any dev:   pull ← git repo → local DB (source = "team:{author}")
           review --team, audit --author alice, decisions --team

Setup

# One-time per developer: point to a shared git repository
aidebrief config team.dir ../team-decisions

# If the directory doesn't exist yet, create it
mkdir -p ../team-decisions && git init ../team-decisions

The team.dir setting is stored in .aidebrief/config.json (project-level) or ~/.aidebrief/config.json (fallback). Solo users never need this file.

Push — exporting your decisions

# Push all new decisions since your last push (incremental)
aidebrief push

# Push everything, ignoring your last-push timestamp
aidebrief push --all

# Push to a directory other than the configured one
aidebrief push --to /path/to/team-repo

# Stage files but don't auto-commit (review before committing)
aidebrief push --no-commit

# Override the author name (default: git config user.name)
aidebrief push --author "alice"

# Auto-commit and also git push to remote
aidebrief push --push-remote

What gets written to the team directory:

team-decisions/
├── decisions/
│   ├── a1b2c3d4-...json     one file per decision
│   ├── e5f6g7h8-...json
│   └── ...
└── suppressions.json        team-wide contradiction suppressions

Each decision file is self-contained JSON:

{
  "id": "a1b2c3d4-...",
  "session_id": "orig-session-uuid",
  "author": "alice",
  "source": "copilot",
  "topic": "sqlite",
  "decision_text": "Use WAL mode for concurrent reads",
  "rationale": "Allows reads during writes without blocking",
  "related_files": ["src/store.py"],
  "keywords": ["sqlite", "wal"],
  "status": "active",
  "created_at": 1718000000000
}

Key behaviors:

• Incremental by default — push tracks last_push_at per team directory
• Never re-exports team decisions — decisions with source starting with team: are skipped (you can't push someone else's pulled decisions back)
• Git-aware — if the team directory is inside a git repo, push auto-stages and commits the new files. --no-commit skips this.

Pull — importing team decisions

# Pull all decisions from the configured team directory
aidebrief pull

# Pull from a different directory
aidebrief pull --from /path/to/team-repo

# Preview what would be imported without actually importing
aidebrief pull --dry-run

# Skip importing the suppression list
aidebrief pull --no-suppressions

What happens during pull:

• Reads every .json file from <team_dir>/decisions/
• For each file, checks if the decision id already exists in your local DB
• New decisions are inserted with source = "team:{author}" (e.g. team:alice)
• Already-imported decisions are skipped (idempotent — safe to run repeatedly)
• Optionally imports suppressions.json into your local suppressed_contradiction table

Team review

Once you have pulled teammates' decisions, they appear transparently in every command:

# See only team-shared decisions (source starts with "team:")
aidebrief review --team

# Filter by a specific team member
aidebrief review --author alice

# Audit only team decisions for contradictions
aidebrief audit --team

# Audit a specific person's decisions
aidebrief audit --author bob

# Search across a specific person's decisions
aidebrief decisions sqlite --author bob

The --team flag filters by source LIKE 'team:%'. The --author flag filters by exact source source = 'team:{name}'. These can be combined with any other filter (--since, --limit, --json).

Requirements for team sync

• The team directory must be writable by all team members
• Git is optional but recommended (push will detect and auto-commit)
• Each developer's git config --global user.name is used as the author tag (override with --author)
• All decision IDs are UUIDs — no merge conflicts between team members

Features

Command	What it does
aidebrief review	Browse recent sessions (table with decision counts)
aidebrief review --decisions	Decisions grouped by topic across all sessions
aidebrief decisions <query>	Search extracted engineering decisions (human-readable table)
aidebrief summarize <id>	Structured markdown summary of a single session
aidebrief audit	Find contradictory decisions across all sessions
aidebrief audit --team	Audit only team-shared decisions
aidebrief diff <topic>	Investigate all decisions about a topic across sessions
aidebrief contradictions <query>	Check if a proposal conflicts with past decisions
aidebrief suppress <keyword>	Mark a contradiction as acknowledged (hides from future audits)
aidebrief suppressed	List suppressed contradictions
aidebrief unsuppress <keyword>	Re-enable a suppressed keyword
aidebrief search <query>	Full-text search across all conversations (table by default)
aidebrief context <query>	Retrieve relevant past sessions as context
aidebrief list	List recent sessions
aidebrief status	Database summary with source breakdown and topic overview
aidebrief push	Push decisions to the team sync directory
aidebrief pull	Pull decisions from the team sync directory
aidebrief config team.dir <path>	Set the team sync directory
aidebrief export	Export decisions+suppressions to a portable JSON file
aidebrief export	Export decisions+suppressions to a portable JSON file
aidebrief export --include-sessions	Include session metadata in the export
aidebrief export --since 30	Export only decisions from the last 30 days
aidebrief import <file>	Import decisions from an export file
aidebrief init	Install hooks and create database

All commands default to human-readable output. Add --json for raw JSON.

How capture works

Copilot and Claude Code hook files are written to disk when a conversation ends. On your next review, search, or status call, SyncManager processes them lazily — ingesting the transcript, indexing it with FTS5, and extracting structured engineering decisions. No background daemon needed.

An MCP server exposes the same database via tools accessible to AI agents.

Decision extraction

Decisions are extracted from assistant responses using regex patterns — no LLM by default:

Pattern	Example	Confidence
explicit	Decision: use SQLite WAL mode	1.0
verb	we chose PostgreSQL over MySQL	0.9
comparison	SQLite over PostgreSQL for embedded	0.8
constraint	avoid SELECT *	0.5

Each decision includes the decision text, rationale (if a because/reason: clause is nearby), topic (scored noun), keywords, and file paths.

An LLM backend is available via AIDEBRIEF_EXTRACTION=llm for higher accuracy.

Requirements

Python 3.11+ and mcp>=1.0.0. No other dependencies.