HEDDLE

CLI reference

heddle agent

Shipped
heddle agent <subcommand>

Run the local agent gRPC daemon (Unix socket) and the orchestration reservation API. The integration surface for tools that drive Heddle from outside a shell.

heddle agent serve runs a gRPC daemon that other tools (IDE plugins, custom orchestrators, evaluation harnesses) connect to over a Unix-domain socket at .heddle/sockets/grpc.sock. The socket is same-user only — no TCP, no network surface. --socket overrides the default; --foreground is required (background daemonization isn't wired yet).

status and stop are lifecycle commands — show whether the daemon is running for this repo, ask it to drain and exit. reserve / heartbeat / capture / ready / release / list are the reservation API: atomically reserve a thread for one writer, keep the reservation alive via heartbeat, capture under the session-validated reservation, mark ready for integration, release. Output for the reservation API is JSON-only — these are designed for tools, not humans.

Distinct from the FUSE mount daemon — see heddle daemon for that one. They share no code surface beyond the name.

Examples

Start the daemon

bash$ heddle agent serve --foreground &heddle agent serve: listening on /Users/me/repo/.heddle/sockets/grpc.sockheddle agent serve: pidfile at /Users/me/repo/.heddle/agents/heddle.pid

Reserve a thread for orchestration

bash$ heddle agent reserve --thread task/biscuit-authz --task "scope-narrowing pass"{"session_id":"…","reservation_token":"…","thread":"task/biscuit-authz",…}

Check daemon status

bash$ heddle agent statusheddle agent: running (pid 12345)  socket: /Users/me/repo/.heddle/sockets/grpc.sock  pidfile: /Users/me/repo/.heddle/agents/heddle.pid

See also

Subcommands

  • agent serve Start the agent gRPC daemon (Unix socket; requires --foreground)
  • agent status Show daemon status (pid, socket, pidfile)
  • agent stop Ask the running daemon to drain and exit
  • agent reserve Atomically reserve a thread for one writer
  • agent heartbeat Update reservation heartbeat
  • agent capture Capture under a session-validated reservation
  • agent ready Mark a reservation's thread ready for integration
  • agent release Release a reservation (status: complete | abandoned)
  • agent list List agent reservations (optionally filtered to alive ones)