Metadata-Version: 2.4
Name: agentagon
Version: 0.1.3
Summary: Inspect and improve AI agents with measured fixes and custom scores.
License-Expression: Apache-2.0
Project-URL: Homepage, https://agentagon.ai
Project-URL: Documentation, https://agentagon.ai/docs/
Project-URL: Source, https://github.com/agentagon/agentagon
Project-URL: Issues, https://github.com/agentagon/agentagon/issues
Project-URL: Changelog, https://github.com/agentagon/agentagon/releases
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.txt
Requires-Dist: click<9,>=8.1
Requires-Dist: jsonschema<5,>=4.21
Requires-Dist: referencing<1,>=0.28.4
Requires-Dist: httpx<1,>=0.28
Requires-Dist: gepa==0.1.4
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff==0.16.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: browser
Requires-Dist: playwright==1.57.0; extra == "browser"
Provides-Extra: e2b
Requires-Dist: e2b==2.46.4; extra == "e2b"
Dynamic: license-file

# 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](https://github.com/agentagon/agentagon/blob/main/docs/audit.md), [define scores and evals](https://github.com/agentagon/agentagon/blob/main/docs/init.md), or [compare measured fixes](https://github.com/agentagon/agentagon/blob/main/docs/fix.md). [Install the plugin](https://github.com/agentagon/agentagon/blob/main/docs/getting-started/install.md) 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](https://pipx.pypa.io/stable/installation/):

```sh
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](https://github.com/agentagon/agentagon/releases).

For source installation in an isolated environment:

```sh
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](https://github.com/agentagon/agentagon/blob/main/docs/audit.md#install). 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](https://github.com/agentagon/agentagon/blob/main/docs/telemetry.md).

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](https://github.com/agentagon/agentagon/blob/main/docs/intelligence.md).

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

```text
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](https://github.com/agentagon/agentagon/blob/main/docs/fix.md) to compare improvements against that baseline. See the [quickstart guide](https://github.com/agentagon/agentagon/blob/main/docs/getting-started/first-audit.md).

Optional examples: [check your installation offline](https://github.com/agentagon/agentagon/blob/main/examples/local-audit/README.md), or [compare fixes in the ticket-retry demonstration](https://github.com/agentagon/agentagon/blob/main/examples/ticket-retry/README.md).

## Workflows

| Goal | Skill and result |
|---|---|
| Inspect agent behavior and find failures | [ag:audit](https://github.com/agentagon/agentagon/blob/main/docs/audit.md): evidence-backed findings from code and execution traces. |
| Improve a saved goal or named issue | [ag:fix](https://github.com/agentagon/agentagon/blob/main/docs/fix.md): bounded Omni optimization, verified comparisons and draft PR or local delivery. |
| Define behaviors, custom scores and evals | [ag:init](https://github.com/agentagon/agentagon/blob/main/docs/init.md): agreed behaviors, scoring and limits, reusable evals and a scored baseline. |
| Inspect history, rerun a baseline or manage settings | [ag:dashboard](https://github.com/agentagon/agentagon/blob/main/docs/dashboard.md): checkout-scoped baselines, results and opt-in controls. |

[ag:eval](https://github.com/agentagon/agentagon/blob/main/docs/eval.md) 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](https://github.com/agentagon/agentagon/blob/main/docs/intelligence.md).

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

```sh
agentagon setup
```

| Setting or location | Purpose |
|---|---|
| `--workspace PATH` before the subcommand | Select the application directory; defaults to `.` |
| `AGENTAGON_CONFIG` | Override the configuration file path |
| `$XDG_CONFIG_HOME/agentagon/config.json` | Default settings file; falls back to `~/.config/agentagon/config.json` |
| `.agentagon/` in the application directory | Evidence, reports and experiment state; initialization excludes it from Git |

Project overrides take precedence over user defaults. Credential settings store environment-variable names, not secret values. Use [ag:setup and the configuration guide](https://github.com/agentagon/agentagon/blob/main/docs/audit.md#first-audit-and-setup) for traces and preferences, [execution profiles](https://github.com/agentagon/agentagon/blob/main/docs/fix.md#configure-execution-once) for evaluations and fixes, and [Intelligence setup](https://github.com/agentagon/agentagon/blob/main/docs/intelligence.md) 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](https://github.com/agentagon/agentagon/blob/main/CONTRIBUTING.md) for editable installation, local development, tests and the pull request workflow. The [documentation index](https://github.com/agentagon/agentagon/blob/main/docs/README.md) links deeper guides and references.

To explore the implementation, start with [how Agentagon works](https://github.com/agentagon/agentagon/blob/main/docs/contributing/architecture.md) and the [extension walkthrough](https://github.com/agentagon/agentagon/blob/main/docs/contributing/extending.md). Maintainers can follow [release preparation](https://github.com/agentagon/agentagon/blob/main/docs/contributing/releasing.md).

Report vulnerabilities through [SECURITY.md](https://github.com/agentagon/agentagon/blob/main/SECURITY.md). Participation follows the [Code of Conduct](https://github.com/agentagon/agentagon/blob/main/CODE_OF_CONDUCT.md).

## License

[Apache-2.0](https://github.com/agentagon/agentagon/blob/main/LICENSE).
