Metadata-Version: 2.4
Name: autoevolve-cli
Version: 0.1.1
Summary: Git-backed experiment loops for coding agents
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1.46
Requires-Dist: rich>=14
Requires-Dist: textual>=1
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# autoevolve

![screenshot](https://raw.githubusercontent.com/wiskojo/autoevolve/main/assets/screenshot.png)

`autoevolve` lets coding agents run git-backed experiment loops autonomously. It gives agents a lightweight workflow for branching, recording results, and comparing experiments without needing heavy external dependencies, databases, or services.

Initialize it inside a project, let it set up the files your coding agents need, and then let the agents iterate through experiments, branch into new research directions, and explore ideas on their own.

> [!NOTE]
> `autoevolve` can create many experiment branches and worktrees. Try it in a repo where extra git history won’t be a problem, or use a new repo.

## Install

```bash
pip install autoevolve-cli
```

## Quickstart

**1. Initialize `autoevolve` in an existing git repo**:

```bash
autoevolve init
```

`autoevolve init` walks you through the setup for your coding harness and problem:

- `SKILL.md` or `PROGRAM.md`: the instructions your coding agent reads to use `autoevolve`
- `PROBLEM.md`: the goal, metric, constraints, and validation setup for your problem

For an example problem to try, see the [circle packing example repo](https://github.com/wiskojo/autoevolve-circle-packing-example).

**2. Tell your agent to read `PROGRAM.md` or activate the skill depending on your setup**:

```text
Read PROGRAM.md, then start working.

# If using skills
$autoevolve  # Codex
/autoevolve  # Claude Code
```

From there, your agent should start working in the repo as usual. This works best if your agent is running with dangerously skip permissions/yolo mode. Experiment commits will include:

- `EXPERIMENT.json`: the structured record of the experiment, including summary, metrics, and any references to other experiments
- `JOURNAL.md`: the narrative record of the experiment, which could include the hypothesis, changes made, outcomes, reflections, etc.

**3. Start the TUI to monitor your agent's progress**:

```bash
autoevolve dashboard
```

## CLI

Here’s the CLI surface: `Human` commands handle setup and monitoring, `Lifecycle` manages experiments, and `Inspect` and `Analytics` help your agents review the experiment state.

```text
Usage: autoevolve [OPTIONS] COMMAND [ARGS]...

  Git-backed experiment loops for coding agents.

Options:
  --help  Show this message and exit.

Human:
  init       Set up PROBLEM.md and agent instructions.
  validate   Check that the repo is ready for autoevolve.
  update     Update detected prompt files to the latest version.
  dashboard  Open the experiment dashboard.

Lifecycle:
  start      Create a managed experiment branch and worktree.
  record     Validate, commit, and remove the current managed worktree.
  clean      Remove stale managed worktrees for this repository.

Inspect:
  status     Show the current experiment status.
  log        Show experiment logs.
  show       Show experiment details.
  compare    Compare two experiments.
  lineage    Show experiment lineage around one ref.

Analytics:
  recent     List the most recent recorded experiments.
  best       List the top experiments for one metric.
  pareto     List the Pareto frontier for selected metrics.

Examples:
  autoevolve start tune-thresholds "Try a tighter threshold sweep" --from 07f1844
  autoevolve record
  autoevolve log
  autoevolve recent --limit 5
  autoevolve best --max benchmark_score --limit 5

Run "autoevolve <command> --help" for command-specific details.
```
