Metadata-Version: 2.5
Name: piloop
Version: 0.3.1
Summary: Autoresearch for any repo: coding agents try ideas, piloop scores every commit and keeps what wins
Project-URL: Homepage, https://github.com/hiloopai/piloop
Project-URL: Documentation, https://piloop.autoresearch.inc
Project-URL: Changelog, https://github.com/hiloopai/piloop/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/hiloopai/piloop/issues
Author: Autoresearch, Inc.
License-Expression: MIT
License-File: LICENSE
Keywords: agents,autoresearch,claude-code,codex,experiments,optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Requires-Python: >=3.14
Requires-Dist: alembic>=1.16
Requires-Dist: boto3>=1.43.112
Requires-Dist: covalence==0.1.0.dev6
Requires-Dist: cyclopts>=3.20
Requires-Dist: fastapi>=0.161
Requires-Dist: gitpython>=3.1.45
Requires-Dist: httpx2>=2.12.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.34
Requires-Dist: opentelemetry-sdk>=1.34
Requires-Dist: psutil>=7
Requires-Dist: pydantic-settings>=2.10
Requires-Dist: pydantic>=2.11
Requires-Dist: rich>=15.0.0
Requires-Dist: sqlalchemy>=2.0.41
Requires-Dist: textual<9,>=8.2
Requires-Dist: uvicorn>=0.54
Provides-Extra: gcs
Requires-Dist: google-cloud-storage>=3.0; extra == 'gcs'
Provides-Extra: modal
Requires-Dist: modal>=1.6; extra == 'modal'
Description-Content-Type: text/markdown

# piloop

[![CI](https://github.com/hiloopai/piloop/actions/workflows/ci.yml/badge.svg)](https://github.com/hiloopai/piloop/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hiloopai/piloop/blob/main/LICENSE)
[![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/downloads/)

**Autoresearch for any git repo: coding agents try ideas, piloop scores every commit and keeps what wins.**

Documentation: [piloop.autoresearch.inc](https://piloop.autoresearch.inc)

piloop runs coding agents on a goal that a program can measure. Each agent tries one idea in its own git worktree
and commits. piloop scores every commit with your evaluate command, and keeps a change only when it beats the best
result so far.

![piloop watch on the enwik8 example: 10 Claude Code runs took the compressed size from 3,688,770 to 2,361,893 bytes](https://raw.githubusercontent.com/hiloopai/piloop/main/docs/images/watch-campaign.svg)

*The enwik8 example after 10 runs: Claude Code agents took the first 10 MB of Wikipedia from 3,688,770 bytes (zlib) to 2,361,893 bytes (−36%) in 1.6 hours.*

piloop keeps its state on your machine: a SQLite database in `~/.piloop` and git refs in your repo. It has no hosted
service. The agents send your code and prompts to their model providers, as they do when you use them yourself.

## Start

1. Install piloop and its skills for your coding agents:

   ```bash
   curl -fsSL https://raw.githubusercontent.com/hiloopai/piloop/main/install.sh | sh
   ```

2. Open your coding agent in your repo: Claude Code, Codex, pi, Gemini CLI or Cursor.

3. Tell it what to improve. Say "piloop", so that the agent uses the piloop skills:

   ```text
   Use piloop to make our tokenizer faster without changing its output.
   ```

The agent sets up the campaign, runs it, and asks you only what needs you. To try piloop on an example first, ask for
"the enwik8 example campaign from piloop", or [run it by hand](https://piloop.autoresearch.inc/by-hand).

## Requirements

- Linux (x86-64 or ARM, glibc 2.28 or later) or macOS on Apple silicon. On an Intel Mac, installing builds
  [covalence](https://pypi.org/project/covalence/) from source, which needs a recent Rust.
- git 2.40 or later, with a commit identity.
- [uv](https://docs.astral.sh/uv/). The installer installs it.
- At least one of [Claude Code](https://code.claude.com), [Codex](https://github.com/openai/codex) or
  [pi](https://github.com/badlogic/pi-mono), logged in.

## Documentation

- [Quickstart](https://piloop.autoresearch.inc/quickstart): your first campaign, through your agent.
- [Concepts](https://piloop.autoresearch.inc/concepts/campaigns): campaigns, ideas, runs and the verdict.
- [Reference](https://piloop.autoresearch.inc/reference/cli): the CLI, the configuration and the database schema.

## Contributing

See [CONTRIBUTING.md](https://github.com/hiloopai/piloop/blob/main/CONTRIBUTING.md). Agents that operate piloop
start at [AGENTS.md](https://github.com/hiloopai/piloop/blob/main/AGENTS.md).

## License

MIT. See [LICENSE](https://github.com/hiloopai/piloop/blob/main/LICENSE).
