GitHub - gageml/gage: Scan Claude sessions to learn what your coding agent's up to.

Scan Claude sessions to find and fix hidden issues.

Website · Report an issue

Coding agents do a lot of work you never see. Buried in your Claude Code transcripts are diagnosed-but-unfixed bugs, quietly violated project rules, and agent behavior that worked against you. Gage scans those transcripts, turns what it finds into actionable issues, and uses Claude Code itself to help you resolve them.

Find issues

Scanners read your Claude Code sessions and surface issues you would otherwise never see: bugs left unfixed, agent behavior that worked against you, settings that cost you data.

Scan your Claude sessions

Find real issues backed by evidence

Fix issues

gage resolve opens an interactive Claude Code session that works through open issues with you. You decide what gets fixed and what gets skipped.

Use Claude to resolve issues

Work interactively to apply fixes

Trace everything

Every issue cites its evidence. Walk from an issue to its notes to the exact session content behind it --- thinking blocks included --- or query everything directly with SQL.

Trace the issue to the offending entry

Trace the logic that wrote the issue

Requirements:

• Local gage binary install on Linux or macOS
• Local Claude Code plugin install
• Active Claude Code login status (Pro plans recommended)

IMPORTANT: Gage uses Claude Code to scan sessions and resolve issues. Token usage is handled through Claude Code according to your Anthropic plan.

Quick start

1. Install Gage

curl https://raw.githubusercontent.com/gageml/gage/refs/heads/release/scripts/install.sh | sh

2. Initialize Gage

3. Run a scan

Adjust the scan settings and confirm. When the scan is complete and you've had a chance to review the results, press q to exit.

4. Resolve issues

Scanners

Gage ships these scanners in the default group. Their source is under scanners in this repository.

Install

Supported platforms:

• Linux
• macOS

Windows support is planned.

Install prebuilt binary

To run the install script, use:

curl https://raw.githubusercontent.com/gageml/gage/refs/heads/release/scripts/install.sh | sh

This installs the gage binary for your system (Linux or macOS only) to ~/.local/bin/gage. It does not require elevated privileges.

Install with cargo binstall

If you have cargo-binstall installed, you can install Gage by running:

cargo binstall --git https://github.com/gageml/gage gage-cli

To install cargo-binstall, ensure that you have the Rust toolchain installed and then run:

cargo install cargo-binstall --locked

Install from source

Gage requires the Rust toolchain to compile.

Follow the instructions at https://rustup.rs/ to install it.

Clone the Gage repo:

git clone https://github.com/gageml/gage.git

Install the Gage CLI:

cargo install --path gage-cli

Claude Code plugin

Gage requires a Claude Code plugin. Install it by running:

Features

Scan Claude Code sessions

gage scan runs scanners on your Claude Code sessions. Scanners are self-contained programs written in the Rune programming language. You can read their source code under scanners in this repository.

gage scan lets you select the scanners to run. Alternatively, you can specify each scanner using the -s/--scanner option. By default, Gage runs all scanners in the default group. Use --list-scanners to show available scanners.

You can also specify how many sessions you want to scan. By default Gage scans the last 20 sessions. To scan all available sessions, use the -a/--all option. Otherwise you can set the number with -n/--limit.

During a scan you can view the active scan tasks, session, issues, and notes.

Issues and notes

Scanners write issues and notes. An issue is a concern that warrants your attention. Issues are initially written as open or pending and are intended to be closed once resolved. An issue is closed as completed, skipped, or noted as a duplicate.

A note is any sort of information attached to a session, project, or other scan. Think of a note as a sticky note that points to something of interest. Notes are cited as evidence for opening issues.

You can see issues and notes as they are written during a scan.

Resolve issues

Gage is designed to use Claude Code to evaluate and resolve issues.

List unresolved issues:

You can alternatively view issues written during a scan using gage scan view.

To resolve issues, run:

This opens an interactive Claude Code session that reviews open issues and helps you resolve them. You can alternatively run the /gage:resolve command in any Claude Code session.

During an issue resolution session, Claude uses Gage tools to list and read open issues. Work through issues with Claude's help as you see fit. Each issue provides information to confirm the problem and advice on fixing it. If you decide it's not a problem, skip it --- Claude can close the issue as skipped. If you resolve the issue, Claude can close the issue as completed.

Gage Query

gage query provides a SQL interface to all Gage data. This includes:

• Session data (e.g. line entry JSON)
• Notes
• Issues
• Project config

Scanners use this facility exclusively for read-only data.

Use gage query -c SQL to run queries yourself. This is useful for analysis you'd like to perform on sessions, notes, or issues.

Gage Query provides a PostgreSQL compatible interface. The REPL supports commands using the syntax \COMMAND. Run \? from the REPL to list available commands.

Note that Gage Query reads some data from local files (e.g. sessions and project config). Some queries will cause full file system scans, which are surprisingly slow and memory intensive. In general, avoid running unbounded queries.

Avoid:

This will read every session line into memory!

Instead, use WHERE and LIMIT clauses:

SELECT * FROM entry WHERE session_id LIKE 'abc123%' LIMIT 10;

FAQ

What license is Gage available under?

Apache 2

Where is Gage data stored?

Gage writes all of its data to files under ~/.gage/. These include:

• Settings (~/.gage/settings.json)
• Installed scanners (~/.gage/lib/scanners/)
• Data including notes and issues (~/.gage/data/)
• Cache and temporary files (~/.gage/cache/, ~/.gage/tmp/)
• Logs (~/.gage/log/)

Does Gage "phone home" for any reason?

No. Gage runs locally and writes all state under ~/.gage/.

Gage provides tools to Claude Code over a local MCP server. Claude is free to use these tools within the constraints of user-defined permissions (allow and deny). Gage tools do not open network connections or otherwise write outside of ~/.gage/. Claude, however, may. This is the normal risk profile of running an agent. To minimize the risk of sensitive data exfiltration, follow the safeguards recommended by Anthropic.