AgentRun open-sources a platform for self-improving agents

AgentRun is an open-source platform (Apache-2.0, run with npx @parcha/agentrun) that sits on top of an existing agent harness and adds three things: self-improvement, durable execution and a control plane. The supported harnesses are Claude Code, Codex, OpenCode and pi. The README's pitch is that agents are good at figuring things out but keep figuring out the same things: given a job done a hundred times, an agent rediscovers the same API, rereads the same docs and rebuilds the same plan, and the user pays for every token. The authors claim their agents become smarter, more fault tolerant and use fewer tokens with every run.
The README leads with two cost examples, both the authors' own. In the first, Greptile started charging a dollar a review in March, then the authors' agents took off and their bill went from $180 a month to $6,451, a 36x rise this year. They built their own reviewer on a cheap model and tuned it on their own pull requests. It costs 18 cents a review, and on 30 PRs it had never seen, they say it caught 1.6x the real bugs Greptile did. In the second, they let Opus work out how to classify merchants, then handed what it learned to a cheap model: the same job went from $0.89 down to $0.12 a merchant.
Learning is opt-in per agent, switched on with "learning": true in the agent's definition. At the end of each run the agent gets one more turn to say what it would keep: a note, a skill or a workflow. AgentRun checks the proposal with code, has one grader judge it, and commits what passes to the agent's own git folder (plain git, one branch, main). The next run starts from there. Notes are short markdown files, one fact each, in Claude Code's memory format. Skills describe how to do a job again, and only a run that finished the job can write one. Learned workflows run as one tool call on any harness, under the run's own cap and tool permissions. Once a learned skill has served 3 runs, the next run is asked for that job as a workflow draft, which is dry-run before it is kept: no model is asked and no tool runs.
The filter is strict. An item that breaks its own rules (size or count limit, name, shape) is left out and the rest goes on. A secret or hidden character anywhere in the answer, a file outside the folder, a deletion or a full index drops the whole answer. A risky rule waits for the user's OK, and a rule found in a web page or pasted email, or a note holding an account number, is dropped. The Learning tab lists every note, skill and workflow with a change log; items can be retired there or with the CLI, and git keeps the history so a retired note can come back. When notes outgrow the learning budget, each run gets those that bear on its first message in full and a line for each of the rest.
For repeatable work the README suggests typed workflows instead of agents: a JSON document of steps that call tools, run a model, ask a fast typed question (yes or no, pick one, a score, each with its confidence), branch, map over a list in parallel, loop a bounded number of times, call other workflows or hand a hard case to an agent. In the README's example, the model leans approve at 0.61, below the workflow's 0.75 bar, so the case goes to review. Workflows can be watched node by node, paused and resumed, and run in an app with a TypeScript builder.
Durability rests on one store for every agent, revision, run and step: SQLite in the data folder by default, or Postgres via AGENTRUN_STORE_URL. Stop the server mid-run, start it again, and the run carries on. With several runners, another picks up a dead runner's runs once its 30-second lease runs out. A finished step is never run again, and a write cut off by a crash mid-call is marked interrupted rather than retried, so the user can check it.
The control plane covers approvals (each tool is allowed, asks first, or is denied, and a server-side deny holds even over "never ask"), spend caps (a run pauses at its cap instead of failing and reports the least it needs to continue; a cost AgentRun cannot price reads "unknown", never $0), questions the agent can ask the user mid-run, and one console with a live timeline, files and, for browser runs, a screen the user can take over. Mission Control shows what needs attention, what failed, what is running and what it cost, by day, by harness and by tool. Every agent is also an API.
An agent's computer is one setting: none, sandbox, desktop, phone or browser, with a named provider (daytona is the README's example) for every kind but none. Without a computer setting, agents get a Docker sandbox where the server has Docker. Remote computers bill through the user's own vendor account. Five ready-made agent templates ship with the project, each a folder with instructions, skills, rules and eval cases; applying one grants nothing until the user ticks each MCP tool. Triggers can start capped runs from schedules, signed webhooks and GitHub pull request events.
Getting started needs Node 24.22.3 or newer on macOS or Linux. npx @parcha/agentrun starts the server and one runner on port 7340 (or the next free one), keeps everything in ~/.agentrun and opens the console. The user sets a password and adds a model key; one OPENROUTER_API_KEY gives every harness a model, an Anthropic key runs pi and Claude Code, and an OpenAI key runs pi, Codex and OpenCode. The first suggested run is the KYB due diligence template, which produces a report with a verdict and every claim cited. It can also run in one container, as a server with runners, or deployed to Render in one click.
Key facts
- AgentRun is an Apache-2.0 platform that adds learning, durable execution and a control plane (approvals, spend caps, one console) on top of Claude Code, Codex, OpenCode or pi.
- With "learning": true, an agent proposes a note, skill or workflow after each run; code checks it, one grader judges it, and passing items are committed to the agent's own git folder.
- Runs live in one store (SQLite by default, or Postgres) and survive a server restart; a dead runner's runs are picked up after a 30-second lease, and a write cut off mid-call is marked interrupted, not retried.
- The authors' own figures: a code review bill that rose from $180 to $6,451 a month with Greptile, replaced by an in-house reviewer at 18 cents a review that they say caught 1.6x the real bugs on 30 unseen PRs.
- Quickstart is npx @parcha/agentrun on Node 24.22.3 or newer, macOS or Linux, with five ready-made agent templates.
Why it matters
Agent costs grow with usage, and the README's argument is that much of the spend is repeated discovery. AgentRun's answer is to let an agent keep what it learned and, where possible, turn a repeated job into a fixed workflow that a cheaper model can run. The merchant example shows the shape: Opus works out the classification, a cheap model does the job later, and the cost per merchant goes from $0.89 to $0.12. The project also does not ask users to switch harness; it wraps the ones they already use.
Who it affects
Teams running agents on repeated jobs such as code review, merchant classification or due diligence, and anyone paying per-review or per-token bills that scale with agent activity. It targets people who already use Claude Code, Codex, OpenCode or pi and want approvals, spend caps and recovery without building them. Installation is supported on macOS and Linux only.
How to use it
Install with npx @parcha/agentrun on Node 24.22.3 or newer. It starts a server and one runner on port 7340 (or the next free one), stores data in ~/.agentrun and opens a console. Set a password, add one model key under Settings, then apply the KYB due diligence template and start a run with a company's name and website. Open the agent's Learning tab afterwards to see what it kept. To learn on your own agents, set "learning": true in the agent's definition. The license is Apache-2.0. For a server with a URL, the README offers a one-click Render deploy; Docker gives agents a sandbox with a shell, and without Docker they can read and write files but get no shell.
How solid is it
The cost and quality numbers are the authors' own claims from their README case studies, and no independent evaluation is cited. The 1.6x bug-catch result rests on 30 PRs the reviewer had not seen; how a real bug was defined or verified is not stated, and the cheap model behind the reviewer and the merchant classifier is not named. The savings figures cover only the code review and merchant-code examples, not learning in general. The design details (checks before commit, dry-run of workflow drafts, lease-based recovery, conformance suites per computer provider) are described concretely, but the README is the vendor's own description of its product.
Risks and caveats
Learned notes and skills change future behavior, so the safeguards matter: risky rules wait for user approval, and rules found in pages or pasted emails are dropped. A write cut off by a crash is marked interrupted and left for the user to check, not retried. Templates grant no tool access until each MCP tool is ticked. Spend caps pause a run rather than fail it, and an unpriceable cost shows as unknown, so cost totals may be incomplete. Remote computers bill through the user's own vendor account, and Daytona, Modal and E2B sandboxes run only with an Archil disk; with Archil on, the Docker sandbox is refused.
“Agents are great at figuring things out. The problem is they figure out the same things over and over.”
— AgentRun README