Choose the Right Operator Surface

This guide helps you choose the AGH surface for the actor in front of you: a human operator, a script, a local agent, a web UI, or a remote integration. It intentionally avoids flag-by-flag reference. Use the generated references when you need exact syntax.

The short version

Surface	Best for	Use when	Reference
CLI	Humans, scripts, local agents	You need a stable command, shell pipeline, or `-o json` output.	CLI Reference
HTTP/SSE	Browser UI, integrations, stream readers	You need daemon state over TCP or live events over Server-Sent Events.	API Reference
UDS	Local agents and tools	You need daemon control without exposing a TCP listener.	API Reference
Web UI	Human inspection	You need to scan sessions, events, and runtime state visually.	Web UI

Choose by actor

A human operator is doing one task

Start with the CLI. It is explicit, scriptable, and mirrors daemon state directly.

agh daemon status
agh session list
agh session events sess_1234 --follow

What happened: the operator asked the daemon for current state, then followed the durable event stream for one session.

An agent needs to inspect or mutate AGH

Prefer CLI JSON output or the local UDS API. Agents should avoid scraping terminal prose or web UI state.

agh session list -o json
agh memory search release notes -o json
agh tool list -o json

What happened: the agent received machine-readable runtime state it can validate before taking the next action.

A browser surface needs live updates

Use HTTP plus SSE. Polling hides ordering and makes recovery harder; AGH events are already append-only runtime records.

curl http://localhost:2123/api/daemon/status
curl -N http://localhost:2123/api/sessions/sess_1234/stream

What happened: the browser or integration reads daemon state and then subscribes to session events as they are recorded.

A local tool should not depend on TCP

Use the UDS transport. It keeps daemon access local to the runtime home and matches the same shared API handler contracts used by HTTP.

agh daemon status
agh observe health -o json

What happened: the CLI talked to the daemon over the local socket and returned structured health data without exposing a public listener.

Common decisions

Start or stop a daemon

Use the CLI:

agh daemon start
agh daemon status
agh daemon stop

Then open Daemon Operations when you need supervision, foreground logs, socket paths, or process details.

Inspect a session

Use CLI first, then web UI when visual scanning helps:

agh session status sess_1234 -o json
agh session history sess_1234
agh session events sess_1234 --follow

For the lifecycle model behind those commands, read Session Lifecycle.

Let another system watch AGH

Use HTTP/SSE. The API route map lists the implemented route families and marks which routes are generated from OpenAPI today; the guides explain when a route is the right tool.

Start with:

Let agents manage work

Use surfaces with structured output:

agh task next -o json for claimable work
agh task heartbeat <run-id> -o json for lease extension
agh task complete <run-id> -o json for task completion
agh ch send <channel> and agh ch recv <channel> for coordination channels

These are agent-operable surfaces, not hidden in-process calls. A managed agent can use them when its session has CLI/tool access to the runtime; a human operator can run the same commands from a shell and compare the same JSON output.

The web UI can show the same state, but it should not be the only way an agent can act.

Next steps

Use Debug a Failed or Stuck Session when the surface reports an unhealthy state.
Use Coordinate Agents over AGH Network when one session needs to find or delegate to another.
Use CLI Reference for exact commands and flags.

On this page