Metadata-Version: 2.4
Name: aidebrief
Version: 0.3.1
Summary: AI decision audit trail for engineering teams — capture, search, and review decisions from every coding AI
Author-email: Deepan Karthik <deepankarthik@gmail.com>
License: MIT
Project-URL: homepage, https://github.com/deepankarthik/aidebrief
Project-URL: repository, https://github.com/deepankarthik/aidebrief
Project-URL: changelog, https://github.com/deepankarthik/aidebrief/releases
Keywords: ai,conversation,search,mcp,sqlite,fts5,copilot,claude,opencode
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Provides-Extra: spacy
Requires-Dist: spacy>=3.7; extra == "spacy"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: ruff>=0.4; extra == "test"

# 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

```bash
pip install aidebrief
aidebrief init
aidebrief review
```

## Solo workflow

```bash
# 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

```bash
# 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

```bash
# 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:

```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

```bash
# 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:

```bash
# 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 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.
