piloop 0.1.0__tar.gz

piloop-0.1.0/.github/ISSUE_TEMPLATE/1_bug_report.yml

@@ -0,0 +1,32 @@
+name: Bug report
+description: Something in piloop does not work as the docs say.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: The smallest set of steps or commands that shows the problem.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `piloop --version` and `piloop doctor`
+      render: text
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Operating system and harnesses
+      placeholder: macOS 26, Claude Code 2.1, runtime = "herdr"
+    validations:
+      required: true

piloop-0.1.0/.github/ISSUE_TEMPLATE/2_feature_request.yml

@@ -0,0 +1,16 @@
+name: Feature request
+description: Propose a change or a new feature.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What you are trying to do, and why piloop makes it hard today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Your proposal
+      description: What you want piloop to do. Include the commands or config you have in mind.

piloop-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://piloop.autoresearch.inc
+    about: Install, quickstart, concepts and reference.

piloop-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What this changes and why. Link the issue it fixes. -->
+
+## Test plan
+
+<!-- How you verified it: the tests you added, and anything you ran by hand. -->
+
+- [ ] `make` passes (format, lint, types, tests with 100% coverage, generated docs).
+- [ ] A user-visible change has a line under `[Unreleased]` in CHANGELOG.md.

piloop-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

piloop-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  workflow_call: {}
+
+env:
+  COLUMNS: 150
+  UV_FROZEN: "1"
+  UV_PYTHON_PREFERENCE: only-managed
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-suffix: lint
+      - run: uv sync
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --all-files --verbose
+        env:
+          SKIP: no-commit-to-branch
+          UV_NO_SYNC: "1"
+
+  test:
+    name: test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            make: testcov
+          # Coverage is measured on Linux: a few paths (the lock holder from /proc/locks) exist only there.
+          - os: macos-latest
+            make: test
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-suffix: test
+      - run: uv sync
+      - run: make ${{ matrix.make }}
+
+  install:
+    name: install.sh quickstart
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - run: git config --global user.name piloop-ci && git config --global user.email ci@piloop
+      - run: PILOOP_SRC=. ./install.sh
+      - name: enwik8 example, headless (no Herdr on a runner)
+        env:
+          PILOOP_PROJECT_RUNTIME: subprocess
+          COLUMNS: 200
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          piloop init --example enwik8 /tmp/enwik8 | tee /tmp/init.txt
+          grep -q "registered; baseline candidate#1" /tmp/init.txt
+          piloop status enwik8
+      - name: the wheel carries the skills (a stand-in codex on PATH)
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          mkdir -p /tmp/bin && printf '#!/bin/sh\n' > /tmp/bin/codex && chmod +x /tmp/bin/codex
+          PATH="/tmp/bin:$PATH" piloop install-skills
+          test -f ~/.agents/skills/piloop-operate/SKILL.md
+
+  check:
+    if: always()
+    needs: [lint, test, install]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

piloop-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  release:
+    needs: ci
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+      - name: The tag matches the package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - name: Release notes from CHANGELOG.md
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '$0 ~ "^## \\[" v "\\]" {on=1; next} on && /^## \[/ {exit} on' CHANGELOG.md > notes.md
+          test -s notes.md || { echo "CHANGELOG.md has no section for $version"; exit 1; }
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    # PyPI trusted publishing: pypi.org trusts this repo, this workflow and this environment. No token.
+    environment:
+      name: release
+      url: https://pypi.org/project/piloop/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v7
+      - run: uv publish --trusted-publishing always

piloop-0.1.0/.github/workflows/sync.yml

@@ -0,0 +1,34 @@
+# Keeps main identical in hiloopai/piloop and its private mirror hiloopai/piloop-dev, in both directions. Experimental
+# branches live only in piloop-dev; merging one into its main publishes it. A diverged main fails here, never forces.
+name: Sync main
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-main
+
+jobs:
+  sync:
+    if: contains(fromJSON('["hiloopai/piloop", "hiloopai/piloop-dev"]'), github.repository)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - env:
+          DEPLOY_KEY: ${{ secrets.SYNC_DEPLOY_KEY }}
+          TARGET: ${{ github.repository == 'hiloopai/piloop' && 'hiloopai/piloop-dev' || 'hiloopai/piloop' }}
+          SSH_AUTH_SOCK: /tmp/ssh-agent.sock
+        run: |
+          ssh-agent -a "$SSH_AUTH_SOCK" > /dev/null
+          ssh-add - <<< "$DEPLOY_KEY"
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+          git push "git@github.com:$TARGET.git" HEAD:refs/heads/main

piloop-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+.coverage/
+htmlcov/
+dist/
+node_modules/
+piloop/templates/*/data/
+.alembic-scratch.db*
+*.db
+*.db-wal
+*.db-shm

piloop-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: no-commit-to-branch
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: [--maxkb=1024, --enforce-all]
+        exclude: ^uv\.lock$
+
+  - repo: local
+    hooks:
+      - id: format
+        name: Format
+        entry: make
+        args: [format]
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: lint
+        name: Lint
+        entry: make
+        args: [lint]
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: typecheck
+        name: Typecheck
+        entry: make
+        args: [typecheck]
+        language: system
+        types: [python]
+        pass_filenames: false
+      - id: docs
+        name: Generated docs
+        entry: make
+        args: [docs-check]
+        language: system
+        types: [python]
+        pass_filenames: false

piloop-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

piloop-0.1.0/AGENTS.md

@@ -0,0 +1,48 @@
+# Operating piloop
+
+This file is for a coding agent that a human asks to set up, run or review a piloop campaign. To change piloop's own
+code, read [CONTRIBUTING.md](CONTRIBUTING.md) instead.
+
+If `PILOOP_ACTOR` is already set to a `worker#`, `watchdog#`, `research#` or `scout#` id, piloop started you. Follow
+your brief, and ignore this file and the skills.
+
+piloop runs an autoresearch campaign on a git repo. A daemon starts coding agents (Claude Code, Codex or pi). Each
+agent tries an idea in its own git worktree. piloop scores every commit with the project's evaluate command and keeps
+what beats the head. You, the agent that the human talks to, set up the campaign and act as its orchestrator.
+
+## The skills
+
+Each task has an [Agent Skill](https://agentskills.io). Read the one that matches the task. Each `SKILL.md` is
+complete on its own.
+
+| Skill | Use it to |
+|---|---|
+| [piloop-setup](skills/piloop-setup/SKILL.md) | Set up or change a campaign in the current repo: check the machine, interview the human, write `brief.md` and `piloop.toml`, register the project, start the daemon. |
+| [piloop-operate](skills/piloop-operate/SKILL.md) | Orchestrate a running campaign: the inbox loop, ideas and priorities, escalations and decisions, sweeps, steering workers. |
+| [piloop-review](skills/piloop-review/SKILL.md) | Review a campaign during or after a run: are the gains real, did an agent game the evaluation, where did the time and tokens go. |
+
+`piloop install-skills` copies these skills into `~/.claude/skills` (Claude Code) and `~/.agents/skills` (Codex, pi,
+Gemini CLI, Cursor), for each of these harnesses on the `PATH`. The installer and `piloop upgrade` run it, so the
+skills always match the installed CLI. `piloop doctor` reports a missing or old copy.
+
+## The interface is the CLI
+
+The database is the contract, and the `piloop` CLI is the only way in:
+
+- `piloop sql "<one statement>"` reads and writes the database.
+- `piloop schema` prints the conventions and every table. Read it before your first write.
+- `piloop status` shows the state of each project.
+- `piloop inbox` lists what waits for a decision.
+- `piloop inbox wait` blocks until something needs you.
+- `piloop --help` lists every other command.
+
+## Rules
+
+- Run every command as `PILOOP_ACTOR=orchestrator piloop …`. Your writes are then signed as yours, and
+  `piloop inbox wait` skips them.
+- Record every decision that you make for the human as a `decision` comment with a priority. The human reviews and
+  revises these decisions in the inbox. You do not have to wait for the human.
+
+## Documentation
+
+The documentation is at [piloop.autoresearch.inc](https://piloop.autoresearch.inc). It is also in `docs/` in this repo.

piloop-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to piloop are in this file. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and piloop follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0, a minor release may contain breaking changes.
+A deprecated configuration key shows a warning for at least one minor release before it is removed.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+
+Initial public release.
+
+### Added
+
+- `piloop init`: makes a git repo a project, measures the baseline and registers it. Two bundled examples:
+  `enwik8` (compress Wikipedia text) and `titanic-tracks` (accuracy and CPU cost on Kaggle's Titanic data).
+- The daemon, `piloop serve`: starts coding agents (Claude Code, Codex or pi) in git worktrees, scores every commit
+  with the project's evaluate command, and keeps what beats the head.
+- The verdict: one primary metric that must improve with confidence, guardrail metrics with margins and floors, and
+  a paired bootstrap over per-unit results.
+- Three agent roles: the worker, the watchdog and the research agent, with a scout mode for outside techniques.
+- Ideas, seeds, links between ideas, branch runs from pinned starting points, notes on regressed results, and
+  imported reference candidates.
+- Tracks: several objectives for one project, on one trunk.
+- The orchestrator skills (setup, operate, review) for Claude Code, Codex, pi, Gemini CLI and Cursor, and the inbox
+  where the orchestrator records its decisions.
+- `piloop watch`: the campaign on one screen, with keys to act on it.
+- Stop conditions, token accounting for every agent, and a hard spend limit in USD.
+- Session capture of every agent with Entire.
+- MCP servers for the agents of a role, defined once for every harness, with keys from the daemon's environment or
+  `PILOOP_SECRETS_COMMAND`.
+- `piloop restart`, `piloop upgrade`, `piloop doctor` and `piloop service-unit` for campaigns that run for days.
+
+[Unreleased]: https://github.com/hiloopai/piloop/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/hiloopai/piloop/releases/tag/v0.1.0

piloop-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to piloop
+
+This file explains how to set up a development checkout, run the checks and send a change.
+
+## Set up
+
+You need git, [uv](https://docs.astral.sh/uv/) and `make`.
+
+```bash
+git clone https://github.com/hiloopai/piloop
+cd piloop
+make install
+```
+
+`make install` installs the dependencies and the pre-commit hooks.
+
+To try the installer from your checkout, as CI does:
+
+```bash
+PILOOP_SRC=. ./install.sh
+```
+
+## Run the checks
+
+```bash
+make
+```
+
+`make` formats the code, runs the linter (ruff), runs the type checker (ty), runs the tests with coverage, and
+regenerates the generated files. Coverage must be 100%. The full test suite takes several minutes. While you work,
+run only the tests that you need:
+
+```bash
+COLUMNS=150 uv run pytest tests/scoring
+```
+
+The tests marked `herdr` need a local [Herdr](https://herdr.dev). They are skipped when `herdr` is not on your
+`PATH`.
+
+Other targets: `make format`, `make lint`, `make typecheck`, `make test` (no coverage), `make testcov`, `make docs`
+and `make docs-check`. CI runs the pre-commit hooks, `make testcov` on Linux, `make test` on macOS, and `install.sh`
+with the enwik8 example.
+
+## Generated files
+
+`make docs` writes these files from the code. Never edit them by hand:
+
+- `docs/reference/configuration.mdx`, from the models that `piloop.config.ProjectConfig` reaches (in
+  `piloop/config.py`, `piloop/harnesses.py`, `piloop/mcp/` and `piloop/usage/`), from `piloop/deprecated.py`, and from
+  the header in `scripts/gen_docs.py`.
+- `docs/reference/schema.mdx`, from `piloop/db/models.py`.
+- `piloop/db/actor_triggers.sql` and `piloop/db/persistent_triggers.sql`, from `piloop/db/triggers/`.
+- The part between the markers of `docs/architecture/data-model.mdx`, `state-machines.mdx` and `code-layout.mdx`:
+  the diagram of the tables, the values of the state enums, and the graph of the imports between the subpackages.
+
+`make docs-check` fails when one of them is stale. The pre-commit hook runs it.
+
+## Documentation
+
+The documentation site is in `docs/`. It is a [Mintlify](https://mintlify.com) site: `docs/docs.json` and one `.mdx`
+file for each page. To preview it, with Node.js installed:
+
+```bash
+cd docs
+npx mint dev
+npx mint broken-links --check-anchors
+```
+
+In `.mdx` files, `{`, `}`, `<` and `>` in text are syntax. Put them in code spans, or escape them.
+
+## Change the database schema
+
+1. Change the models in `piloop/db/models.py`.
+2. Create a new Alembic revision:
+
+   ```bash
+   uv run alembic revision --autogenerate -m "add the foo column to ideas"
+   ```
+
+3. Read the generated revision and fix what autogenerate missed.
+4. Run `make docs`.
+
+Never edit an existing revision. Users have databases at every revision, and piloop migrates them when it starts. A
+batch migration that rebuilds a table drops its triggers, so call `piloop.db.triggers.recreate` after it.
+
+## Deprecate a configuration key
+
+To rename or remove a key of `piloop.toml`, add a bridge in `piloop/deprecated.py`. The module docstring explains
+how. The old key then keeps working, with a warning, for at least one minor release. Add a line under `Deprecated` in
+`CHANGELOG.md`.
+
+## Code style
+
+- Python 3.14, single quotes, lines of at most 120 characters, Google-style docstrings.
+- No new `Any` (the existing uses type untyped JSON), no `# type: ignore`, no new `noqa`. Fix the cause instead.
+- No `logging`. Emit spans and span events with `piloop.otel`.
+- Comments explain a reason that is not obvious, a gotcha or a TODO. They do not repeat the code.
+
+## Package layout
+
+The package has one subpackage for each concern. Imports only point down this list:
+
+1. `db/`: storage, the SQL gate for agents, the events feed.
+2. `mcp/`, `usage/`, and `config.py` with `harnesses.py`: MCP servers, token usage, the project configuration.
+3. `runtime/`: where the agent processes run (a background process, or a Herdr pane).
+4. `scoring/`: the evaluate command, the ledger, the verdict.
+5. `agents/`: the roles and their prompts, the agent lifecycle, session capture.
+6. `campaign/`: projects, ideas, the inbox, stop conditions, the spend limit.
+7. `reports/`: status, history, the research pack.
+8. `daemon/`: the process, the scheduler, the run executor.
+9. `watch/` and `cli/`.
+
+The top-level modules `settings`, `otel`, `git`, `proc`, `text` and `deprecated` are leaves that every subpackage may
+use.
+
+## Send a change
+
+- Open an issue first for a large change, so that we can agree on the approach.
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `fix: keep the head when a merge conflicts`,
+  `feat(watch): filter the agents panel`.
+- Add a line under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for every change that a user can see.
+- Make sure that `make` passes before you open the pull request.
+
+## Release
+
+Maintainers only.
+
+1. Set `version` in `pyproject.toml`, and run `uv lock`.
+2. In `CHANGELOG.md`, rename `[Unreleased]` to the version and the date, add a new empty `[Unreleased]`, and update the
+   links at the bottom.
+3. Merge that change, then tag the commit on `main`: `git tag v0.2.0 && git push origin v0.2.0`.
+
+The `Release` workflow runs CI, checks that the tag matches the version, creates the GitHub release with the
+changelog section as its notes, and publishes the package to PyPI.

piloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autoresearch, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

piloop-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.DEFAULT_GOAL := all
+
+.PHONY: install
+install:  ## Install deps and pre-commit hooks
+	uv sync --frozen
+	uv run pre-commit install --install-hooks
+
+.PHONY: format
+format:  ## Format the code
+	uv run ruff format
+	uv run ruff check --fix --fix-only
+
+.PHONY: lint
+lint:  ## Lint the code
+	uv run ruff format --check
+	uv run ruff check
+
+.PHONY: typecheck
+typecheck:  ## Static type check
+	uv run ty check
+
+.PHONY: test
+test:  ## Run tests (no coverage)
+	COLUMNS=150 uv run pytest --durations=10
+
+.PHONY: testcov
+testcov:  ## Run tests with coverage; fails under 100%
+	COLUMNS=150 uv run coverage run -m pytest --durations=10
+	uv run coverage report
+
+.PHONY: docs
+docs:  ## Regenerate the configuration and schema reference pages and the trigger SQL from code
+	uv run python scripts/gen_docs.py
+
+.PHONY: docs-check
+docs-check:  ## Fail if a generated file is stale
+	uv run python scripts/gen_docs.py --check
+
+.PHONY: all
+all: format lint typecheck testcov docs