Metadata-Version: 2.4
Name: perpetual-agent
Version: 0.1.0
Summary: Autonomous research agent — persistent memory, experiment tracking, hypothesis-driven proposals, GPU run lifecycle
Project-URL: Homepage, https://github.com/nik-hz/perpetual
Project-URL: Repository, https://github.com/nik-hz/perpetual
Project-URL: Issues, https://github.com/nik-hz/perpetual/issues
Author: nik-hz
License: MIT
License-File: LICENSE
Keywords: agent,ai,autonomous,experiments,hypothesis,ml,opencode,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Requires-Dist: click>=8.0
Requires-Dist: lark>=1.1
Requires-Dist: mcp>=1.0
Requires-Dist: pygit2>=1.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: tabulate>=0.9
Description-Content-Type: text/markdown

# perpetual-agent

[![CI](https://github.com/nik-hz/perpetual/actions/workflows/ci.yml/badge.svg)](https://github.com/nik-hz/perpetual/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/perpetual-agent.svg)](https://pypi.org/project/perpetual-agent/)
[![npm](https://img.shields.io/npm/v/opencode-perpetual.svg)](https://www.npmjs.com/package/opencode-perpetual)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Persistent research backend for AI coding agents.** Hypotheses, experiment tracking, GPU run lifecycle, git-backed memory, and an autonomous research loop — accessible from any harness that speaks MCP.

Works with **Claude Code**, **Cursor**, **Codex**, **OpenCode**, and any other MCP-compatible client. One backend, many harnesses, the same persistent state.

## What it gives you

- **Experiment graph** — SQLite-tracked hypotheses, proposed/approved/running/done experiments, with a typed config and notes per run.
- **Run supervisor** — launch GPU jobs, watchdog them, capture stdout/stderr, detect crashes, debit a GPU-hours budget.
- **Git-backed memory** — markdown notes the agent reads and writes; every change is a git commit so you have a full audit trail.
- **Hypothesis-driven proposals** — agent proposes experiments scored by information gain; updates confidence as evidence accrues.
- **Autonomous loop** — `/auto` mode (or the headless daemon) polls for completed runs, analyzes results, updates hypotheses, proposes next experiments.
- **Methodology config** — a YAML file that controls auto-approve, batch size, support/refute thresholds, max concurrent runs.

## Install

One install gets you the global CLI:

```bash
pip install perpetual-agent
```

Then in any project, one command sets up everything (state directory + harness integration + MCP server registration):

```bash
perpetual init --harness opencode      # default; gets the richer first-party plugin
perpetual init --harness claude-code   # Claude Code
perpetual init --harness cursor        # Cursor
perpetual init --harness codex         # Codex
perpetual init --harness mcp           # generic MCP — for any other client
perpetual init --harness all           # scaffold every supported harness at once
```

`perpetual init` is project-scoped (like a Python venv): it creates a `.perpetual/` state directory in the current project, plus the harness-native config files. The MCP server (`perpetual mcp`) is launched on-demand by your harness and reads state from the project's `.perpetual/`.

## Quick start

```bash
mkdir my-research && cd my-research
perpetual init -p "my-research" --harness opencode
perpetual chat
```

Or for Claude Code:

```bash
mkdir my-research && cd my-research
perpetual init -p "my-research" --harness claude-code
claude    # the perpetual agent + MCP server are auto-loaded
```

## How it plugs in

`perpetual init --harness <name>` writes two things:

1. **Agent definition** in the harness's native format (e.g. `.claude/agents/perpetual.md`, `.cursor/rules/perpetual.md`, `.opencode/agents/perpetual.md`).
2. **MCP server registration** pointing at `perpetual mcp` — a stdio MCP server that exposes the perpetual tools and live research state to any MCP-compatible client.

The MCP server exposes 6 tools and a `live-state` resource:

| Tool | Purpose |
|------|---------|
| `perpetual_status` | research state (experiments by status, hypotheses, runs, budget) |
| `perpetual_propose` | propose an experiment for a hypothesis |
| `perpetual_hypotheses` | list / add / update hypotheses with confidence tracking |
| `perpetual_scan` | sync run statuses → experiment graph |
| `perpetual_memory` | read / write / list persistent research notes |
| `perpetual_budget` | GPU-hours used, per-experiment breakdown |

Plus `live-state://research` — the same markdown blob you'd see if you ran `perpetual status && perpetual hypotheses list && perpetual budget`. Harnesses that auto-include resources in context get the live state per turn for free.

## CLI

```
perpetual init               initialize project (state + harness scaffolding)
perpetual mcp                run the MCP server (stdio)
perpetual status             show experiments, hypotheses, runs, budget
perpetual hypotheses         list / add / update hypotheses
perpetual propose            propose an experiment for a hypothesis
perpetual approve <exp>      approve a proposed experiment
perpetual run <exp> <cmd>    launch an approved experiment
perpetual scan               sync run statuses → experiment graph
perpetual kill <exp>         kill a running experiment
perpetual budget             GPU-hours used, per-experiment breakdown
perpetual report             generate a markdown research report
perpetual memory             show / write / list research memory
perpetual methodology        show / init research methodology config
perpetual daemon             autonomous event loop (poll → analyze → iterate)
perpetual gpu-status         nvidia-smi summary
perpetual chat               launch the TUI (opencode passthrough)
perpetual ask "<prompt>"     send a one-shot prompt to the agent
perpetual auth               manage LLM provider credentials
```

## Daemon mode (headless, no TUI)

```bash
perpetual daemon --interval 30 --max-cycles 50
```

Polls for completed runs, dispatches analysis prompts to your harness, debits the GPU budget, exits when the queue empties.

## OpenCode plugin (richer first-party integration)

OpenCode supports plugins natively, so we ship a TypeScript plugin (`opencode-perpetual` on npm) that goes beyond MCP — it injects live research state into the system prompt every turn, registers slash commands (`/auto`, `/stop`, `/report`, `/catchup`), and gives the perpetual agent a custom color in the TUI.

`perpetual init --harness opencode` scaffolds the plugin source into `.opencode/perpetual-plugin/` and runs `bun install` automatically (if `bun` is on PATH). Or, for an existing opencode setup:

```bash
opencode plugin install opencode-perpetual
```

## Methodology

Default config in `.perpetual/methodology.yaml`:

```yaml
exploration_strategy: hypothesis_driven
proposal_batch_size: 3
confidence_support_threshold: 0.8
confidence_refute_threshold: 0.2
auto_approve: false
max_concurrent_runs: 4
auto_analyze: true
auto_propose: true
memory_write_on_completion: true
```

The agent reads this every turn and follows the policy.

## License

MIT
