Metadata-Version: 2.4
Name: afteragent
Version: 0.3.0
Summary: Capture agent runs, diagnose failure patterns, and generate workflow interventions.
Author-email: Colin <colinson@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/txmed82/afteragent
Project-URL: Repository, https://github.com/txmed82/afteragent
Project-URL: Issues, https://github.com/txmed82/afteragent/issues
Keywords: agent,debugging,ci,workflow,diagnostics,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.50; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == "all"
Requires-Dist: openai>=1.50; extra == "all"
Provides-Extra: dev
Requires-Dist: jsonschema>=4.22; extra == "dev"
Dynamic: license-file

# AfterAction

AfterAction helps you understand why an agent run went wrong, what it missed, and what to change before the next attempt.

It captures runs, pulls in GitHub PR context, diagnoses repeat failure patterns, and turns that diagnosis into practical interventions such as prompt exports, repo instruction updates, and replay context.

## Why this exists

Agent-assisted PR repair often fails in familiar ways:

- the agent keeps fixing the wrong files
- failing CI checks never make it into the plan
- review comments stay unresolved across attempts
- the next run starts without the lessons from the last one

AfterAction makes those mistakes visible and reusable. Instead of treating each run like a fresh start, it records the run, analyzes the failure surface, and prepares the next attempt with better context.

## Who it's for

- engineers using coding agents to fix pull requests
- teams experimenting with Claude Code, Codex, OpenClaw, or plain CLI runners
- people who want a local audit trail for agent behavior
- anyone trying to turn trial-and-error repair loops into a more disciplined workflow

## What it does

- captures command runs, output, exit codes, diffs, events, and artifacts
- ingests GitHub PR context including changed files, review threads, checks, workflow runs, and CI log excerpts
- diagnoses patterns like repeated failures, low overlap with failing files, ignored review comments, and broad edit drift
- exports interventions as task prompts, runner context, replay context, and repo instruction patches
- applies repo instruction updates to files like `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `CURSOR.md`, and `COPILOT.md`
- replays a prior run with intervention context injected into the environment
- scores replay outcomes so you can tell whether the next attempt improved or regressed
- serves a local UI for runs, findings, interventions, and replay comparisons

## Runner support

AfterAction is runner-agnostic by default.

- `shell`: fallback mode for any CLI command
- `openclaw`: OpenClaw-specific targeting and transcript parsing
- `claude-code`: Claude Code instruction targeting and transcript parsing
- `codex`: Codex instruction targeting and transcript parsing

If a runner exposes richer output, AfterAction can extract structured events such as `tool.called`, `file.edited`, and `retry.detected`. If not, the shell path still works.

## Installation

Requires Python 3.11+.

```bash
pip install afteragent
```

For development:

```bash
git clone https://github.com/txmed82/afteragent.git
cd afteragent
pip install -e .
```

## Quick start

Capture a simple run:

```bash
afteragent exec -- python3 -c "print('hello from afteragent')"
```

List runs and inspect one:

```bash
afteragent runs
afteragent show <run-id>
afteragent diagnose <run-id>
```

Open the local viewer:

```bash
afteragent ui
```

By default, AfterAction stores everything in `.afteragent/` in the current repository.

## Common use cases

### 1. Capture a local agent run

Use this when you already know what command you want to run and you want the full trace.

```bash
afteragent exec -- codex run "Fix the failing tests"
afteragent exec -- openclaw repair
afteragent exec -- python3 scripts/repair.py
```

### 2. Snapshot a live pull request before making changes

Use this when you want the failure surface first: changed files, review threads, checks, and CI evidence.

```bash
afteragent validate-pr --repo vega/sphinxext-altair --pr 16
afteragent diagnose <run-id>
```

### 3. Export or apply interventions from a prior run

Use this when a failed run surfaced useful guidance you want to preserve.

```bash
afteragent export-interventions <run-id>
afteragent apply-interventions <run-id>
```

Typical outputs include:

- a task prompt export
- runner policy context
- replay context JSON
- repo instruction patches

### 4. Replay a run with better context

Use this when you want to retry from a known failure with interventions already loaded.

```bash
afteragent replay <run-id> -- python3 -c "import os; print(os.environ['AFTERACTION_SOURCE_RUN'])"
afteragent replay --runner claude-code <run-id> -- claude "Fix the failing PR"
afteragent replay --runner codex <run-id> -- codex run "Address review comments"
```

### 5. Run the full repair loop in one command

Use this when you want to validate a PR, apply interventions, and launch the next attempt in one step.

```bash
afteragent attempt-repair --repo vega/sphinxext-altair --pr 16 -- python3 -c "print('repair')"
afteragent attempt-repair --run-id <run-id> --runner openclaw -- openclaw repair
```

## Typical workflow

For a live pull request:

```bash
afteragent validate-pr --repo owner/name --pr 123
afteragent diagnose <validation-run-id>
afteragent apply-interventions <validation-run-id>
afteragent replay --runner claude-code <validation-run-id> -- claude "Fix the PR"
afteragent ui
```

For an existing failed local run:

```bash
afteragent diagnose <run-id>
afteragent export-interventions <run-id>
afteragent replay <run-id> -- python3 scripts/repair.py
```

## What the replay score means

AfterAction compares a replay against its source run and records whether things improved or got worse.

The score takes into account signals such as:

- run status and exit code
- number of findings
- failing check count
- failure-file count
- unresolved review-thread surface
- overlap between edits and the known failure surface

That makes it easier to answer a simple question: did the intervention actually help?

## Files you will see

Inside `.afteragent/` you will typically find:

- `afteragent.sqlite3`: run metadata and event history
- `artifacts/`: stdout, stderr, git diffs, GitHub context, and CI logs
- `exports/`: exported intervention sets
- `applied/`: applied instruction patches and manifests
- `replays/`: replay input bundles and manifests

You may also see repo instruction files updated in the project root, depending on the runner and what already exists:

- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`
- `CURSOR.md`
- `COPILOT.md`

## End-to-end test matrix

The repository includes an end-to-end matrix that exercises the subprocess path and runner adapters.

```bash
./scripts/e2e_matrix.sh
```

That script runs:

- the full unit and integration suite
- the fixture-backed end-to-end tests for shell, OpenClaw, Claude Code, and Codex flows

## Current shape

AfterAction is currently local-first:

- local SQLite storage
- filesystem artifacts
- GitHub context pulled through `gh`
- small built-in UI served from the CLI

That keeps the loop inspectable and easy to run in a normal repository without extra infrastructure.

## LLM-driven diagnosis (sub-project 2)

AfterAgent can optionally run an LLM pass over each captured run to identify failure patterns the rule-based detector missed and to author interventions tailored to that specific run. Four providers are supported: Anthropic, OpenAI, OpenRouter, and Ollama.

### Zero-config: just set an API key

```bash
export ANTHROPIC_API_KEY=sk-ant-...
afteragent enhance <run-id>
```

Auto-detect picks `anthropic` + `claude-sonnet-4-5` by default.

### Per-run override

```bash
afteragent exec --enhance -- claude "fix the failing test"
```

Forces LLM enhancement for this run even if `auto_enhance_on_exec = false` in config.

### Auto-enhance every run

Create `.afteragent/config.toml`:

```toml
[llm]
provider = "anthropic"
model = "claude-sonnet-4-5"
auto_enhance_on_exec = true
```

### Ollama dogfood (free, local, offline)

```bash
ollama pull qwen2.5-coder:7b
mkdir -p .afteragent && cat > .afteragent/config.toml <<EOF
[llm]
provider = "ollama"
model = "qwen2.5-coder:7b"
EOF

afteragent exec -- claude "fix the failing test"
afteragent enhance <run-id>
```

No API key required. Runs entirely on your machine. Recommended for local iteration before spending on hosted API tokens.

### Installing provider SDKs

The anthropic and openai SDKs are optional dependencies:

```bash
pip install afteragent[anthropic]       # Anthropic only
pip install afteragent[openai]          # OpenAI / OpenRouter / Ollama
pip install afteragent[all]             # Both SDKs
```
