Runtime Quickstart

By the end of this guide, a task you start in one agent survives a dead session and finishes in another — verified by an agent that didn’t write it.

Before you begin

Make sure you have:

• Node 22.13 or newer. Check with node --version. Below the floor, install refuses with ERROR_NODE_VERSION.
• Postgres installed and running. Check with pg_isready. macOS: brew install postgresql@17 && brew services start postgresql@17. Debian/Ubuntu: apt install postgresql && service postgresql start.
• At least one supported harness on your PATH: Claude Code, Codex, or Cursor.

Prefer to hand this to your agent? Copy the AI Prompt from the install block on the homepage — it runs every step below and reports back.

Step 1: Install the CLI

npm install -g @oathe/oathe@latest

Confirm it worked:

oathe version

It prints the package version on your PATH.

Step 2: Run oathe init

Once per machine, from anywhere:

oathe init

Setup is one screen. The local substrate comes up (database + schema). Every harness detected on your machine is pre-selected — Space toggles a row, Enter installs. Each row says exactly what selecting it writes. oathe uninstall removes exactly what init recorded.

On macOS, init also seats the notch: a quiet glass on the camera housing that pulses verdicts and opens the board on click. oathe notch --welcome replays its tour.

If you see Postgres is not reachable (OATHE_SUBSTRATE_UNREACHABLE): install and start Postgres as above, then re-run oathe init.

Confirm everything is wired:

oathe doctor

Every managed surface should report healthy.

Step 3: Open a normal session

cd your-project
claude

Nothing about how you work changes. It’s a normal session, and the board is in it. Nothing auto-resumes — the session start just shows what work exists here.

Step 4: Claim your first task

Inside the session, your agent claims work through the oathe_* tools. The same verbs work from the terminal:

oathe claim fix-login "users can sign in again"
oathe note  fix-login "found the stale token check"

A claim records the task, its owner, and what “done” means — set before the work starts, so it can’t quietly drift.

Step 5: Kill the session. Pick it up in another harness.

Ctrl-C anytime. Then open the other harness in the same folder:

codex

Same board, same claim. Say continue fix-login and it picks up the task: what’s done, what’s left, and the test that decides whether it’s finished. Nothing pasted, nothing retyped. The new agent doesn’t have to take the old agent’s word for anything.

Step 6: Settle the work

oathe done   fix-login "guard rewritten, test added" src/auth.test.js
oathe verify fix-login

done is a claim, not a verdict. verify runs a non-author engine over the recorded session traces — no agent grades its own homework. Verification passes; the task settles.

Essential commands

Command	What it does
oathe ls	This workspace’s board (--all: every workspace)
oathe claim <task> "<objective>"	Claim a task, minting it if new
oathe note <task> "<text>"	Record a progress statement
oathe done <task> "<what>" [ref]	Assert completion
oathe verify [task]	Non-author verification (--engine claude|codex|cursor)
oathe yield <task> "<note>"	Put the task back on the board, unowned
oathe doctor	Verify every managed surface
oathe update	The whole upgrade in one verb
oathe uninstall	Remove exactly what init recorded

What’s next

• How a handoff works — what survives a dead session
• How verification settles work — why “done” needs a non-author verdict
• Changelog — what shipped, release by release
• What oathe init touches — every write, reversible and recorded
• Privacy — what Oathe reads, stores, and sends