Skip to main content

oneagentgraph

One run's event stream filling a terminal event by event: a graph starting, a two-party member starting, the agent side's oneharness session as its harness run begins, its first turn opening with the instruction read back from that transcript, a member-heartbeat while that turn is still in flight, the turn's Bash tool call and the whole output it answered with, the agent's own reply, the turn completing with its token usage and cost, the supervisor side's oneharness session, the supervisor's turn with its whole instruction scrolling past, the member settling as completed with the supervisor's verdict, and the graph settling at exit 0

Compose agents into a graph over oneharness and onejudge, and merge their outputs into one NDJSON event stream.

One config file and one CLI call: the graph names an oneharness config per role and side, and oneagentgraph prepares each member's launch, supervises liveness, and emits every turn, tool call, fallback, and settle as an event you can pipe into anything.

Install

pip install oneagentgraph-cli      # prebuilt binary, no Rust toolchain
npm install -g oneagentgraph-cli   # the same binary, via npm
cargo install oneagentgraph        # from crates.io, compiled locally

To install a revision that has not been released yet, build it from the repository:

cargo install --git https://github.com/nickderobertis/oneagentgraph --locked

Prebuilt archives for Linux (x86-64, arm64), macOS (Apple silicon), and Windows (x86-64) are attached to every release, with sha256 checksums.

onejudge is a library dependency, linked into this binary — there is nothing to install for it. run, smoke, and interrupt drive the oneharness CLI, so that has to be on PATH, at the release the justfile pins as oneharness-version or newer — smoke and interrupt ask it for JSON by name (--format json), which an older release refuses as an unknown argument. health, validate, history, persona, trigger, reset-timer, cancel, and sweep need nothing at all — health reads oneharness's own identity sweep through its library, in this process. ONEAGENTGRAPH_ONEHARNESS_BIN names a pinned install instead.

A kind: oneharness member's turn runs on the linked oneharness-core in this process too, so what that engine reads from the environment it reads from the graph's env: block: with ONEHARNESS_HISTORY=1 and ONEHARNESS_HISTORY_POINTER_FILE=<file> there, every such turn appends one pointer line to that file saying where its session went — oneharness's own contract, read back through the core's io::history::read_pointers. Nothing here writes or sets it; the requirement in Cargo.toml is what decides the linked core has it, and tests/inventory.rs holds it there.

What it does

oneagentgraph run graph.yaml --task "add the retry" --output json

A graph is YAML — members, the oneharness config each side uses, personas, schedules, and dependencies:

version: 11
name: node-scope
members:
  worker:
    kind: onejudge
    base_config: ./onejudge.base.yaml
    agent: { oneharness_config: ./oneharness.toml }
    judge:                            # one side, or a list of sides judged as one panel
      - oneharness_config: ./oneharness.judge.toml
        label: reviewer
      - kind: llmlint
        config: ./llmlint.yml
        diff_base: origin/main
      - command: [./scripts/checks]
    mode: bypass
    scheduled_notes:                  # timed notes into the conversation, each on its own clock
      - id: progress-report
        every: 1800
        addressee: supervisor
        text: Write the progress report now.
        reset_on: { include: [ { source: pipeline, kind: planner-surfaced } ] }

run streams one envelope per line. Exit 0 means every member settled, 1 that one failed or died, 2 that the config is invalid. --output text renders one line per envelope as it arrives — the stream at the top of this page, filling in real time — and is a rendering of those same events rather than a second report.

A member may name a persona — the role delta it layers over its base config, by built-in name (persona: engineer), by a name in the graph's own catalog, or by path. A persona is a onejudge config fragment: it is written in onejudge's own field names, and onejudge's schema decides what it may say. The persona format documents it, including the agent: block earlier versions defined, which is now refused with no compatibility path. oneagentgraph persona validate PATH takes a file or a whole catalog:

Two oneagentgraph persona validate runs in a terminal. The first checks the shipped catalog — "personas/: OK". The second is refused over a fragment carrying an agent block: agent is not a persona key: a persona is a onejudge config fragment, and onejudge has no agent field, with the migration to a top-level system_prompt spelled out, then "invalid config: 1 persona(s) invalid"

The images on this page are captures of the real CLI, rendered from its actual output by just screenshots and hash-gated by screencomp — so they cannot drift away from what the binary prints.

A two-party member's judge: is a list of sides judged as one panel — a harness reviewer, an llmlint run over the worker's tree, and a repository's own command, on one worker at once — and a single side is the one-element shorthand for it. A harness side names an oneharness_config, an llmlint side says kind: llmlint with its config resolved from the graph's own directory, and a command side names a command; each may carry a label. A list of one harness side composes the same onejudge provider it always did; any other list composes onejudge's split provider with the judges in list order, and each judge's verdict on each worker turn is published as a judge-decided event naming the judge, its kind, its decision and its reason.

A single-sided member may declare pre_turn commands — run immediately before each of its turns, with what they printed prepended to what that turn is asked. A supervisory member's first act becomes reading a prepared view rather than spending tool calls rediscovering state that already exists. A view that cannot be started, fails, prints nothing, or outruns its own bound leaves the turn happening without it and publishes a pre-turn-context saying which.

A two-party member may declare scheduled_notes: each is offered into its one conversation on a clock of its own, for whichever turn is live to take at its end — never interrupting one — so a long-running supervisor is told something on a timer at the cost of one more message rather than a fresh paid turn. Any clock may declare reset_on, a filter in the stack's shared grammar, and restarts on a matching envelope: one the run itself publishes, or one another program appends to the stream oneagentgraph run --follow-events PATH follows. A schedule's resettable: true and the reset-timer verb still work exactly as before, and say on standard error that they are deprecated in favour of reset_on.

When a member's turn goes the wrong way, oneagentgraph interrupt RUN MEMBER --input "do this instead" redirects it in place instead of discarding it the way cancel does. Exit 3 means there was no controllable turn in flight, and says which — a fact, not an error.

oneagentgraph owns no harness, model, or fallback logic. oneharness keeps owning identity chains, fallback, model pins, and quota classification; onejudge keeps owning the two-party conversation. This composes them.

Check a graph before you run it

oneagentgraph validate GRAPH reads the document, resolves every config and persona it names, and builds each member's invocation, without launching anything. A refusal names the member, the entry inside it, and the value it will not take:

Two oneagentgraph validate runs in a terminal. The first prints "node-scope: 1 member(s) OK". The second is refused with exit status detail: invalid config, member "worker", judge entry 1, label "code reviewer" — use letters, digits, hyphens, and underscores; a label names this judge on every surface and, for a harness judge, the config file this run writes for it

Review with one member's judge alone

run --judge-only runs only one member's reviewer over a piece of work — a plan before it launches, a correction to one that is running — with that member's own judge panel, harness routing and persona bar, and no agent side at all:

oneagentgraph run graphs/planner.yaml --judge-only --member worker --input plan.md
oneagentgraph run graphs/planner.yaml --judge-only --member worker \
  --persona ./personas/strict.yaml --input - < plan.md

It exits 0 when the bar is met, 1 with the findings on stderr when it is not, and 2 when no judgement was reached. --bar-fingerprint in place of --input prints one digest of that bar and runs nothing, so a host can record what a pass was judged against; the judge-only run's member-settled carries the same digest.

What past runs did

A run's record is written when it starts and rewritten as it settles, so oneagentgraph history lists the run that is still going alongside the ones that finished — each with its exit code:

The oneagentgraph history listing in a terminal: two rows, each a run id, an exit code, and a graph name. offline-probe-1790101020202-40772 exited 1; review-panel-1790101010101-40771 exited 0

history show ID prints that run's whole record — which members it declared and what became of each, the digest of every config the run resolved, and where the merged stream was written:

The record oneagentgraph history show prints, as pretty JSON: schema_version 3, the run id, the graph path and name, started and finished milliseconds, exit_code 0, a members map with implementer and reviewer both settled, the declared members, a refs list giving the origin, sha256 and byte length of each config the run resolved, and the events_path under ~/.local/state/oneagentgraph/runs

oneagentgraph render EVENTS_PATH reads that stream back as --output text would have shown it, resolving each turn's content from the transcript it references; it reads stdin without a path and writes nothing but stdout.

Identities and quota

oneagentgraph health forwards oneharness's own per-identity sweep: which identities this host has, how each was selected, its auth mode, and the headroom left in its subscription window. Every probe is free — no harness takes a model turn — so it is a pre-flight check rather than a thing that costs what it measures. Here it is swept on a machine with no harness installed at all, which is why every identity answers with the program it could not find or the reason it has no headroom to report:

The report oneagentgraph health prints, as pretty JSON: schema_version 0.1, an observed_at timestamp, and an identities list covering claude-code, codex, opencode, goose, qwen, crush, copilot and cursor. Each names how it was selected and its auth mode; claude-code, codex and cursor are unknown for a missing binary, opencode and goose unavailable for no plan quota, qwen and crush for no headroom reader, and copilot unknown because no GitHub token was set to read its quota with

Reclaiming scratch

Under disk pressure, oneagentgraph sweep --dry-run says what scratch exists, what is reclaimable, and what it could not examine; without --dry-run it reclaims what it proves is dead. --format json writes the same report as one JSON object a script reads by field name, and --min-age-hours takes a non-negative decimal — 0.5 is thirty minutes, the same floor onevcs sweep takes. What counts as proof, and the JSON's shape, are stated in the contract.

The report oneagentgraph sweep --dry-run prints in a terminal: it examines the "runs" family under ~/.local/state/oneagentgraph/runs and the "temp" family under /tmp, retains one directory because it has no readable owner.lock, would reclaim two others with their sizes, and closes with a verdict line — would reclaim 6.5 KiB from 2 directories, which families it examined and which it could not, and that this covers those families only, not the host and not scratch another tool owns

The command surface

Eleven verbs beside clap's own help, in the three groups they fall into: run, smoke and interrupt drive the oneharness CLI; trigger, reset-timer and cancel signal a run that is already going; and validate, history, health, sweep and persona need nothing installed at all. oneagentgraph <VERB> --help has the flags for each, and the contract is the approved statement of the whole surface.

oneagentgraph --help in a terminal, colourised: the one-line description, the usage line, and the twelve commands with their summaries — run, validate, trigger, reset-timer, cancel, interrupt, history, health, smoke, sweep, persona and help — then the --help and --version options

Develop

just bootstrap   # from a clean clone; installs the toolchain and oneharness CLI
just check       # the deterministic gate: format, clippy, tests, coverage, docs
just gate        # check + the LLM-judge tier; the pre-push bar

Licence

MIT. See LICENSE.

Metadata

Release files for oneagentgraph-cli 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for oneagentgraph-cli 0.12.0
File Actions
oneagentgraph_cli-0.12.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for oneagentgraph_cli-0.12.0-py3-none-win_amd64.whl
oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
oneagentgraph_cli-0.12.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for oneagentgraph_cli-0.12.0-py3-none-macosx_11_0_arm64.whl

Total release size: 29.5 MB

Release files / oneagentgraph_cli-0.12.0-py3-none-win_amd64.whl

Download URL oneagentgraph_cli-0.12.0-py3-none-win_amd64.whl
Size 6.3 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
a12ea288f8e39720c070ca7e31f00749eaa89c55f21c627af8a9bb67a9f1531b
BLAKE2b-256 checksum
How to use checksums
9068dad126872a23064b464856451c6d79a2a4e5301d617a4ea085f812ba93fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 6.1 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
060fe3280d0d16025cf6d73c36ba6cea7d8af7a8b0e7a5433afe8ee2415296b0
BLAKE2b-256 checksum
How to use checksums
cececd76dcc71a3eb75ee6c2e39ca79179a972b3b39026130738719e6d8e4577
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL oneagentgraph_cli-0.12.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 5.7 MB
Tags Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
b0a3e0eb245f50d84dcee81d35ef786f14006b7a545daa08cf1a4439880173bb
BLAKE2b-256 checksum
How to use checksums
8b8081f38a4d85a73244ba32f837aef2edf98ab6d5c4d91d850ced3e1d2c1a1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / oneagentgraph_cli-0.12.0-py3-none-macosx_11_0_arm64.whl

Download URL oneagentgraph_cli-0.12.0-py3-none-macosx_11_0_arm64.whl
Size 11.3 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
75e3ed09beac3ef970e1b406951723e05808ba61d16cc48e3d8a93431f512dcc
BLAKE2b-256 checksum
How to use checksums
08a0f2f882c3441e2ac3ba14b6126f21789df33b8459d3607e8bfffc8c0b71da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for oneagentgraph-cli 0.12.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.12.0 This release

4 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page