HEDDLE

CLI reference

heddle agent

Shipped
heddle agent [OPTIONS] <COMMAND>

Agent reservation and one-shot orchestration API. The writer-lease protocol orchestrators use to coordinate parallel writers on one repository. Entirely local — no server involved.

Output text (default)

The binary's own framing, verbatim: heddle agent reserve|capture|ready|release|list|heartbeat is the stable JSON contract orchestrators use to coordinate parallel writers. heddle daemon remains the distinct FUSE mount control plane. There is no agent serve, no agent status and no agent stop — agent is not a daemon and does not listen on a socket. Every subcommand is local file-backed coordination under .heddle; none of it does network I/O.

The protocol. heddle agent reserve --thread atomically reserves a thread for one writer and returns a lease_id and a bearer token. Every downstream verb — heartbeat, capture, ready, release — requires both, as --lease --token . Prefer the HEDDLE_RESERVATION_TOKEN environment variable to --token when process-list visibility matters.

The lease is a five-minute heartbeat lease. agent heartbeat, agent capture and agent ready all renew a current one. --hold-for-pid adds an early-death signal for a long-lived orchestrator process, but PID liveness does not replace heartbeats. release --status closes the lease as complete or abandoned.

Actor session IDs identify provenance; they do not grant writer authority. The token is the authority. (Relatedly: HEDDLE_SESSION_ID and HEDDLE_SESSION_SEGMENT are not implemented — do not rely on them.)

Output is not JSON-only. Every agent subcommand takes the global --output, and text is the default there as everywhere else. Pass --output json to get the contract.

Beyond the lease verbs, agent carries four family surfaces: task (the local delegation record), fanout (plan and start native fan-out lanes), presence (attribution and work context for the active worker — agent presence explain is the first place to look when Heddle attributed activity to the wrong agent), and provenance (provider/model/policy epochs).

Examples

The canonical multi-agent flow

bash$ heddle start feature/auth --task "Implement auth middleware"$ heddle agent reserve --thread feature/auth# → a lease_id and a bearer token; export HEDDLE_RESERVATION_TOKEN rather than passing --token$ heddle agent heartbeat --lease <LEASE> --token <TOKEN>$ heddle agent capture --lease <LEASE> --token <TOKEN> -m "Implement auth middleware"$ heddle agent ready --lease <LEASE> --token <TOKEN>$ heddle agent release --lease <LEASE> --token <TOKEN>$ heddle land --thread feature/auth

See who holds what

bash$ heddle agent list --alive-only --output json

See also

Subcommands

  • agent reserve Atomically reserve a thread for one writer; returns a lease_id and a bearer token
  • agent heartbeat Update reservation heartbeat
  • agent capture Capture under a token-authenticated writer lease
  • 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)
  • agent task Manage local agent task assignments: create, list, show, update
  • agent fanout Plan and start native fan-out lanes: plan, start
  • agent presence Inspect attribution and work context: list, show, explain, complete
  • agent provenance Record provider/model/policy provenance: begin, segment, end, list, show