perpetual-agent

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:

pip install perpetual-agent

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

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

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

Or for Claude Code:

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:

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)

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:

opencode plugin install opencode-perpetual

Methodology

Default config in .perpetual/methodology.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