Agentagon

Find failures. Test fixes. Ship with evidence.

Agentagon helps you audit, evaluate, and improve any AI agent using its code and execution traces. Find failures, test candidate fixes, and compare results against a recorded baseline.

The Python CLI captures evidence, runs checks and saves reports. The ag plugin guides your coding assistant through the reasoning, reviews and candidate edits. Supported coding hosts and setup commands are listed below.

Start with Audit your agent to investigate a concern, or Improve your agent to bring one known failure through evaluation and repair. Evaluation preparation, review and delivery happen within these journeys. Install the plugin if needed.

Prerequisites

• Python 3.12+ with pip and venv, on macOS or Linux. The implementation uses Unix facilities such as fcntl.
• Git to review changes and run evaluation or fix workflows. Full code audits also accept directories without Git.
• Codex or Claude Code with its native plugin manager and working model access for agent-led workflows.

Installation downloads Python dependencies. No Agentagon account or API key is required for the quickstart or core workflows; your coding host and configured services have their own access requirements.

Installation

Install the CLI from PyPI using pipx:

pipx install agentagon
agentagon install --host codex
# Or: agentagon install --host claude-code

Start a new coding-host session after registration. CLI installation and host
registration are separate steps; select the host you use. Downloadable wheels,
source archives and checksums are also available in GitHub Releases.

For source installation in an isolated environment:

git clone https://github.com/agentagon/agentagon.git
cd agentagon
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
agentagon --help

Ensure python3 --version reports 3.12 or newer. Keep this environment active for the following commands; reactivate it in each new shell.

For a persistent CLI and native host plugins, use the plugin installer. It creates a separate runtime and registers ag with selected or detected hosts.

Anonymous skill and Intelligence usage telemetry is enabled by default. Disable it with agentagon setup --scope user --set telemetry.enabled false or AGENTAGON_TELEMETRY_DISABLED=1. See collected fields, privacy and delivery.

Optional Agentagon Intelligence is available through live /v1/audit, /v1/eval and /v1/fix routes. Configure the issued origin explicitly and follow the workflow-specific request and privacy rules.

Quick start

After installation, open your AI agent’s code directory in a new Codex or Claude Code session.

In Codex, select ag:audit from the skill picker, then paste:

Complete a code-only audit of this AI agent.
Show the top findings and next steps.
Skip traces and optional Intelligence.

In Claude Code, paste:

/ag:audit Complete a code-only audit of this AI agent.
Show the top findings and next steps.
Skip traces and optional Intelligence.

Agentagon audits your code and saves a report with findings and recommended next steps. The dashboard opens automatically; use ag:dashboard to reopen it. See the quickstart guide for details.

Optional examples: check your installation offline, or compare fixes in the ticket-retry demonstration.

Workflows

ag:setup manages preferences; ag:dashboard reopens saved work. Audit can finish on dirty or non-Git directories. Isolated fixes and executable evaluation preparation require clean committed inputs and authorized execution limits. A reviewed patch without a runnable baseline is clearly labeled unmeasured.

Intelligence is optional and asks for approval of each outgoing request by default. Set its explicit full access mode through Setup to skip prompts while keeping calls visible. See Intelligence permissions.

Configuration and saved data

The code-only quickstart needs no trace-provider connection, evaluation setup or Intelligence key. To inspect settings for your current directory:

agentagon setup

Project overrides take precedence over user defaults. Credential settings store environment-variable names, not secret values. Use ag:setup and the configuration guide for traces and preferences, execution profiles for evaluations and fixes, and Intelligence setup for optional audit, evaluation and fix guidance.

Evidence is stored locally; your coding host and configured services determine where model processing occurs.

Development and contributing

See CONTRIBUTING.md for editable installation, local development, tests and the pull request workflow. The documentation index links deeper guides and references.

To explore the implementation, start with how Agentagon works and the extension walkthrough. Maintainers can follow release preparation.

Report vulnerabilities through SECURITY.md. Participation follows the Code of Conduct.

License

Apache-2.0.