onpath documentation

Introduction

onpath is a local-first safety and progress monitor for AI coding agents. It watches a session as it runs, detects when the agent gets stuck, and tells you exactly what happened — and what to run next.

What is onpath

You run your coding agent through onpath. It records the session locally, runs a set of detectors over the event stream, and generates a report. When a session starts looping — rerunning the same failing test, editing the same file without progress, or burning past a time budget — onpath surfaces a finding with a recovery prompt.

$ onpath run -- codex exec "fix the failing test"

Everything after -- is passed to the child process unchanged. onpath observes and records the run; the selected policy can warn, pause, or block when a finding crosses its threshold.

Who it's for

• Solo developers using Codex, Claude Code, Cursor Agent, or OpenCode who want to know the moment an agent goes off the rails.
• Engineering teams running many AI coding sessions who need aggregate visibility into where agents stall — without collecting raw transcripts.
• Tech leads who want evidence, not vibes, about where AI time is wasted.

How it works

1. onpath spawns your agent as a child process and watches its event stream.
2. Commands, exit codes, file edits, and timings are written to a local SQLite database.
3. Detectors hash failure signatures, track edit churn, and watch the clock against your thresholds.
4. When a pattern crosses a threshold, onpath writes a finding, a markdown report, and a recovery prompt.

What onpath is not

Installation

onpath is distributed as a versioned Node.js CLI archive. Install it with the official script installer, then verify the local runtime and agent discovery.

Requirements

• macOS 13+ or a modern Linux distribution validated
• Node.js 24 LTS (Node ABI 137)
• One supported agent on your PATH: codex, claude, cursor-agent, or opencode
• Disk for the CLI archive plus a local SQLite store that grows with recorded sessions and reports

Install

$ curl -fsSL https://agent.onpath.run/install.sh | sh

Verify your install

Check the version and run the built-in doctor, which confirms onpath can find a supported agent and write to its local store.

$ onpath --version
0.1.0-rc.5

$ onpath doctor --json

Updating

Update by rerunning the script installer after a new archive release is published. Homebrew and npm publication are not the official release path for this RC.

Detectors

Detectors are deterministic checks over the local session event stream. Project config controls shared thresholds and time budgets; typed policy JSON can enable, disable, or tune individual detectors.

How detection works

onpath normalizes each event — a command, an exit code, a file edit — and feeds it to every armed detector. Detectors are stateful within a session: they count repeats, measure churn, and track elapsed time. When a detector's condition holds past its threshold, it emits a finding with a severity and a recommended action.

Built-in detectors

Failure signatures

For repeated failure detection, onpath first redacts known secret patterns and strips ANSI control sequences. It then keeps at most the last 12 error-relevant lines, or the last 12 non-empty lines when no error pattern is present, collapses horizontal whitespace, and stores a SHA-256 signature of that normalized output. Equal signatures mean equal normalized evidence; they do not prove a shared semantic root cause.

Tuning sensitivity

Project defaults live in onpath.config.json. threshold applies to repeated command and failure evidence, while timeBudget activates elapsed-time checks. Use typed policy JSON for detector-specific thresholds, cooldowns, enablement, and warn, pause, or block actions.

{
  "schemaVersion": 1,
  "threshold": 2,
  "mode": "warn",
  "fileWatch": true,
  "redactPaths": true
}

Configuration & policy

The public config command writes JSON project defaults in onpath.config.json. Policy decides what onpath does when a finding fires — warn, pause for a decision, or block the run.

onpath.config.json

onpath config print reads onpath.config.json in the project root, or the path passed with --path. Project config is merged on top of built-in defaults.

{
  "schemaVersion": 1,
  "threshold": 4,
  "mode": "pause",
  "timeBudget": "20m",
  "fileWatch": true,
  "redactPaths": true
}

Policy: warn / pause / block

Thresholds

The public config is flat JSON: threshold controls repeated command and repeated failure detection, while timeBudget controls elapsed-session warnings. Detector-specific thresholds and actions belong to typed policy JSON, not TOML sections.

Per-project overrides

Commit onpath.config.json to share project defaults. Hosted policy affects local runs only after onpath dashboard policy pull enrolls .onpath/team-policy.json. Matching policy chooses the most restrictive action; source precedence breaks ties.

Privacy & sync

onpath is local-first by default. Nothing leaves your machine unless you turn sync on — and when you do, you preview the exact, redacted payload first.

Local-first storage

Every session is recorded to a single SQLite file at .onpath/events.sqlite. Reports are written alongside it. You can export, inspect, or delete this data at any time — it is yours.

$ onpath data list
$ onpath data export --session <session-id> --output ./onpath-export.json
$ onpath data delete --session <session-id>

Redacted sync preview

Sync is opt-in, per project. Before anything uploads, onpath sync preview shows the exact payload. Raw command text and terminal output are excluded by default; failure signatures are hashed.

{
  "schemaVersion": 1,
  "payloadId": "sync_...",
  "payloadClass": "finding-summary",
  "sessionId": "ses_...",
  "createdAt": "2026-07-17T12:00:00.000Z",
  "redactionMode": "strict",
  "destination": "official-cloud",
  "rawIncluded": false,
  "findingId": "finding_...",
  "detectorId": "repeated-failure-output",
  "severity": "warning",
  "confidence": 0.9,
  "evidenceEventCount": 4,
  "evidenceEventIdsHash": "sha256:...",
  "titleHash": "sha256:...",
  "summaryHash": "sha256:..."
}

Retention & deletion

• The current CLI has no automatic local retention setting. Use onpath data list and explicit session-scoped deletion.
• onpath data delete --session <session-id> removes one local session.
• Hosted retention, export, and deletion are managed from the connected workspace's Sync & privacy controls.

MCP integration

onpath ships a Model Context Protocol server that exposes findings and recovery context to your agent — strictly read-only. Your agent can see that it's stuck; it can never act through onpath.

Overview

The MCP server reads from your local session store and serves a small, structured view of the current session: active findings, failure signatures, and the generated recovery prompt. Install it once per agent, scoped to a workspace.

Install for your agent

$ onpath mcp install codex --workspace .

$ onpath mcp install claude --workspace .

$ onpath mcp install cursor --workspace .

Preview the exact configuration change without writing it, or remove an installed entry:

$ onpath mcp install codex --workspace . --print --json
$ onpath mcp uninstall codex --workspace .

What's exposed

Read-only by design

Trusted work

A Work Record binds approved intent, agent attempts, recovery lineage, evidence, independent verification, and the offline Trust Gate without turning onpath into issue management.

Local trusted-work flow

Create a draft from an intent contract, authorize its current revision, checkpoint the repository, and attach each monitored run to the Work Record.

$ onpath work create --id GH-482 --file intent.json --json
$ onpath work authorize wrk_... --reason "approved scope"
$ onpath work checkpoint wrk_...
$ onpath run --work wrk_... --role generator -- codex exec "implement the approved change"

Guard and bounded recovery

Guard evaluates approved paths, commands, dependency and schema changes, budgets, and adapter enforcement fidelity. Native prevention is reported separately from wrapper-level or observe-only evidence.

When an attempt fails, create a Recovery Capsule from selected findings and an existing checkpoint, then start a recovery-role run with that capsule.

$ onpath work recover wrk_... --attempt attempt_... --checkpoint chk_... --finding finding_... --next-action "inspect the failing boundary"
$ onpath run --work wrk_... --role recovery --recovery-capsule rcv_... -- claude

Evidence, verification, and gate

Build a deterministic Evidence Pack from the append-only Work journal. Verification runs contract-declared checks against the frozen changeset and may add an independent Codex or Claude review. The Trust Gate evaluates current evidence offline and fails closed when required evidence is missing, stale, contradictory, or invalid.

$ onpath evidence build wrk_... --json
$ onpath evidence verify-pack <evidence-pack-directory> --json
$ onpath verify wrk_... --agent claude --json
$ onpath work approve wrk_... --subject reviewer@example.com --role reviewer
$ onpath gate wrk_... --output gate.json --json

Stable exit codes

CLI reference

Core public commands and their most important flags. Run onpath <command> --help for the complete version-matched reference in your terminal.

onpath run

onpath report

onpath mcp

onpath config & data