Metadata-Version: 2.4
Name: ai-agentreflect
Version: 0.1.0
Summary: Generate AGENTS.md rules from agent failure logs
Project-URL: Homepage, https://github.com/mikiships/agentreflect
Project-URL: Repository, https://github.com/mikiships/agentreflect
Author: agentreflect contributors
License: MIT
Keywords: AGENTS.md,agent-quality,agents,ai,claude,code-quality,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: anthropic>=0.20.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: llm
Requires-Dist: anthropic>=0.20.0; extra == 'llm'
Description-Content-Type: text/markdown

# agentreflect

Generate `AGENTS.md` rules from AI coding agent failure logs. Closes the feedback loop in the agent quality trilogy.

```
Measure (coderace) → Generate (agentmd) → Guard (agentlint) → Learn (agentreflect)
```

## What it does

Every developer using Claude Code or Codex has this problem: their agent makes a mistake, they fix it manually, update `AGENTS.md`, and hope it doesn't happen again. `agentreflect` automates the "update AGENTS.md" step.

Feed it failure logs → get targeted rule suggestions → apply them to your `AGENTS.md`.

## Install

```bash
pip install ai-agentreflect
```

For LLM-enhanced mode:
```bash
pip install 'ai-agentreflect[llm]'
```

## Usage

### From pytest output

```bash
# Capture failures
pytest --tb=short 2>&1 | tee failures.txt

# Generate suggestions
agentreflect generate --from-pytest failures.txt
```

### From git log

```bash
agentreflect generate --from-git
```

Analyzes `fix:`, `bug:`, `revert:` commits and agent-related mistake commits.

### From plain text notes

```bash
agentreflect generate --from-notes "agent forgot to check for None before accessing .value"
```

## Output formats

### Markdown (default)

```
## agentreflect suggestions (2026-03-11)

### From: pytest failures (failures.txt)
- [ ] Always check for None before attribute access: use `if obj is not None` or `hasattr(obj, 'attr')`
- [ ] When catching AttributeError, log the object type with `type(obj).__name__`

_Source: 3 failures analyzed, 2 suggestions generated_
```

### Diff format

```bash
agentreflect generate --from-pytest failures.txt --format diff
```

Outputs a unified diff ready to apply to `AGENTS.md`.

### Apply directly

```bash
agentreflect generate --from-notes "agent used wrong variable" --apply AGENTS.md
# Asks for confirmation

agentreflect generate --from-pytest failures.txt --apply AGENTS.md --yes
# Applies without confirmation
```

## LLM-enhanced mode

```bash
export ANTHROPIC_API_KEY=your_key_here
agentreflect generate --from-pytest failures.txt --llm
```

Uses `claude-3-5-haiku-latest` for contextual, specific suggestions tailored to your actual failures. Cost: ~$0.001 per analysis.

Basic pattern mode works without any API key.

## Integration with the trilogy

| Tool | Role |
|------|------|
| [coderace](https://pypi.org/project/ai-coderace/) | Measure agent output quality |
| [agentmd](https://pypi.org/project/ai-agentmd/) | Generate AGENTS.md from scratch |
| [agentlint](https://pypi.org/project/ai-agentlint/) | Guard/validate AGENTS.md rules |
| **agentreflect** | **Learn from failures → update rules** |

## License

MIT
