Agent Relay

Agent Relay is a local, machine-wide coordination ledger and bus for AI and developer sessions.

It gives parallel sessions a shared status surface without importing or reading each other's transcript history.

Ledger = durable memory
Bus = active coordination
Session history = never imported

Install

npm install -g @neonwatty/agent-relay

Install the Codex plugin from the npm package:

npx @neonwatty/agent-relay plugin install

Or, after a global install:

agent-relay plugin install

Check the Codex plugin install:

agent-relay plugin doctor

CLI

agent-relay publish --project my-package --session vitest-repro --type experiment.result --status done --tag esm --summary "Vitest ESM repro confirmed"
agent-relay latest --project my-package
agent-relay claim --project my-package --session docs-session --files "docs/**" --task "Update package usage docs"
agent-relay claims --project my-package
agent-relay handoff --project my-package --session tests --to-role docs --summary "Docs should cover the ESM caveat"
agent-relay cleanup

Use --json on any command that supports machine-readable output.

TypeScript API

import { latest, publish } from "@neonwatty/agent-relay"
import { claim, handoff, presence } from "@neonwatty/agent-relay/bus"

publish({
  project: "my-package",
  session: "vitest-repro",
  type: "experiment.result",
  status: "done",
  summary: "Vitest ESM repro confirmed",
  tags: ["esm", "vitest"]
})

claim({
  project: "my-package",
  session: "docs-session",
  scopes: [{ kind: "files", patterns: ["docs/**"] }],
  ttl: "45m"
})

handoff({
  project: "my-package",
  session: "tests",
  toRole: "docs",
  summary: "Docs should cover the ESM caveat"
})

presence({
  project: "my-package",
  session: "docs-session",
  role: "docs"
})

console.log(latest({ project: "my-package" }))

Storage

Default database:

~/.agent-relay/relay.db

Override with:

AGENT_RELAY_HOME=/custom/home
AGENT_RELAY_DB=/custom/home/relay.db

Privacy

Agent Relay only stores explicit events and bus records. It does not ingest transcripts, scan files, or capture command output automatically.