About

Capture AI agent sessions from any agentic coding tool as part of your repository's history and reference them during code review.

How It Works

1. Global hooks are initialized in each agent's config directory.
2. When an agent session starts, a new JSONL file is created in .sessions/.
3. All events (prompts, tool calls, responses) are appended to the session file.

Installation

[!NOTE] Right now, only MacOS/Linux operating systems are supported.

Native Install (Recommended):

curl https://assert.dev/install -fsS | bash

Homebrew:

brew install assert-labs/tap/assert

NPM:

npm install -g @assertlabs/cli

From Source:

git clone https://github.com/Assert-Labs/cli.git
cd cli
pnpm install
pnpm build
npm install -g .

Initializing Hooks

# Initialize hooks for all supported agents
assert init

Requirements

• macOS or Linux, x64 or arm64 (no Windows or Alpine/musl build yet)
• git available on your PATH — the CLI shells out to git at runtime
• If installing via NPM or from source: Node.js 18 or later

Supported Agents

| Agent | Plugin Location | | ----------- | -------------------------------------------------- | | Claude Code | ~/.claude/skills/assert/ | | Codex | ~/.codex/config.toml + ~/.codex/skills/assert/ | | Cursor | ~/.cursor/plugins/local/assert/ |

• Codex support requires the modern Codex CLI (the Rust build with hooks); the legacy @openai/codex (0.1.x) has no hook support, and assert init warns when it finds only that version.
• Support for Devin, OpenCode, Pi, and more is upcoming.
• If you would like support to be added for a particular agent, take a look at CONTRIBUTING.md and look to see if that agent will be added soon in open issues and pull requests.

Commands

assert init [agent]         # Initialize hooks globally (all agents if none specified)
assert sessions             # List sessions in current directory
assert show <session-id>    # Show session details
assert trace [ref]          # Export agent-trace attribution for a revision (default HEAD)
assert status               # Show current status
assert disable              # Pause capture (hooks stay installed)
assert enable               # Resume capture
assert help                 # Show help

Controlling Capture

Session data is written into a repo's .sessions/ as the agent works, so it shows up in git status like any other file — you stage and commit it yourself.

• Skip files: add a .assertignore to the repo root (gitignore-style patterns, e.g. dist/, *.log). Changes that only touch ignored paths won't trigger capture or appear in session data.
• Turn off persistently: assert disable pauses capture (hooks stay installed) until you run assert enable. assert status shows the current state.
• Turn off for one session: set ASSERT_DISABLE=1 in the environment your agent runs in.

Agent Trace

Captured sessions can be exported as Agent Trace records — an open standard for AI code attribution (spec & reference). assert trace derives a conformant TraceRecord for a revision from your committed session data (attributing lines to the contributing model), so any tool can consume the attribution:

assert trace            # agent-trace record for HEAD
assert trace <ref>      # for a specific commit

License

This repository is licensed under the MIT License