Agentagon

Improve your AI agents.

Inspect and improve AI agents with measured fixes and custom scores. Agree on behaviors and scoring, prepare reusable evals to establish a baseline, and compare verified improvements before preparing a draft PR.

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.

Inspect agent behavior, define scores and evals, or compare measured fixes. 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:init from the skill picker, then paste:

Inspect this agent and its existing evals. Propose behaviors, scoring and
an execution budget, then establish a baseline using the settings I approve.

In Claude Code, prefix the same request with /ag:init.

Agentagon reuses suitable evals and confirms missing eval creation before proceeding. It saves the agreed definitions and evidence, prepares reviewed eval source, and measures a baseline when execution is ready. Then use Fix to compare improvements against that baseline. See the quickstart guide.

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

Workflows

ag:eval is independently available for focused evaluation work. Setup, review and delivery support these workflows. Discovery accepts dirty or non-Git directories; measurement requires clean committed inputs and authorized limits. Without a runnable baseline, Fix reports the blocker; an unmeasured application patch requires an explicit request.

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.