The ecc command reference

Alphabetical Index

Presence & Roster

ecc ls [--host H] [--json]: List active net members across machines. Shows member ID, state, reach, repo, branch, uptime and title. Reach is one of now, idle, held (wake budget spent), asks (MCP client, hears only when it looks), turn (next turn boundary), or stuck, when a member on this host claims wake/mid-turn/steer delivery but its own oldest unread message is older than that promise should ever leave it — evidence that whatever normally drains its inbox has stopped.
ecc session start|state|end ...: Register, update, or unregister a member session manually. Used by custom wrappers when running outside supported hook environments.
ecc whoami [--json]: Display the caller's resolved member identity (host.tool.session), host, tool, PID, presence state, working directory, and currently active file reservations.
ecc watch [MEMBER] [--follow] [--all]: Observe stdout, stderr, and lifecycle transitions of a driven member on the local machine in real time.

Messaging & Inbox

ecc send (--to A,B | --topic T) SUMMARY: Queue a durable message to specific members or a topic. Supports --body TEXT|-, --ttl D, --reply-to ID, and --max-hops N for loop protection.
ecc inbox [--peek] [--all]: List your unread incoming messages and mark them as seen. --peek inspects the inbox without clearing unread status. Mail commands act only on the member they run as, never another's.
ecc read ID: Print full message details, headers, timestamps, reply-to link, and body by message ULID.
ecc wait: Block execution cleanly until new mail arrives for the active member session.

File Reservations

ecc hold PATH... [--ttl D] [--shared] [--note "..."]: Declare intent to modify files before making edits. Exclusive by default; shared allows cooperative edits. A conflicting reservation produces a warning but can still return success. These records are not filesystem locks; enforcement belongs to participating pre-tool edit hooks.
ecc holds [PATH...] [--mine] [--json | --explain]: List active file reservations across the entire net, optionally filtered to reservations covering specific files or directories. Conflicts do not cause a nonzero exit status. Custom gates must inspect the records and apply their policy. Supports --mine and --json. --explain adds UTC expiry timestamps, snapshot limitations, and safe takeover guidance. Remote holds remain until expiry; a lease cannot stop an old worker writing files.
ecc release PATH... | --all: Release held paths so other agents can immediately reserve or edit them.

Shared Tasks & Campaigns

ecc task <subcommand> [args...]: Manage the shared queue: add SUMMARY [--needs IDs] [--accept-needs IDs] [--paths P --repo R --repo-scope ULID], claim ID, renew ID --attempt ULID --fence N --lease D, done ID --command CMD, prepare-worktree, block ID --reason, show ID, drop ID, review, correct or policy. A task that sets both --repo and --paths must also set --repo-scope ULID at creation. Reuse the same operator-assigned value across tasks in a repository so cross-host claims can refuse overlaps. Historical unscoped tasks remain readable but must not be claimed as if they held shared paths. Admin only, never granted to agents: triage and operator block|correct|override. Finishing records worker-reported evidence; it does not execute the supplied command. Long-running workers extend a live claim with its exact attempt and fence; renewal refuses an expired claim rather than starting a replacement attempt. Run the check first, then provide its actual status with --exit and save its output with --output. Independently verify artifacts before acceptance.
ecc task prepare-worktree TASK_ULID --checkout PATH --worktree-root PATH --base COMMIT --worktree-name NAME: Create a private Git worktree for the current member's live task attempt, using the task and attempt IDs from the local task mirror. The mirror can lag the broker; this local workspace command does not refresh task authority or launch a worker. It preserves existing or uncertain work.
ecc tasks [--ready] [--all] [--campaign NAME] [--json]: View tasks in the distributed queue. --ready filters to unclaimed tasks whose dependencies have completed; --campaign keeps one campaign's tasks.
ecc campaign start|finish|abandon|drop|show: Group related tasks under a cohesive mission goal. A campaign refuses to close while linked tasks remain incomplete.
ecc campaigns [--all] [--json]: Overview of all active campaigns, progress metrics, and outstanding tasks.
ecc dispatcher monitor --campaign NAME --member MEMBER: Register one expected coordinator attempt for a campaign on this observer host. ecc dispatcher status [CAMPAIGN] [--remote] [--json] shows the retained local observation and incident, plus the records other hosts' observers published, with an observer column. echod checks broker connectivity and presence outside the model turn; a missing member or unavailable broker is an alert for review, not permission to reassign work. Each host keeps the last record another observer published after that observer goes away; observer_stale means the observer stopped republishing, not that the dispatcher stopped. A kept record with no open incident is removed 7 days after its observer went stale; one with an open incident stays until its observer publishes a resolution or you run ecc dispatcher forget --campaign CAMPAIGN --observer HOST, which removes only this host's copy. Status warns once the mirror holds 80% of its 256 records. ecc dispatcher resolve --campaign CAMPAIGN --expect SHA256 --reason TEXT closes this host's open incident after you have reviewed it. The digest comes from ecc dispatcher status --json (the text view prints the full command), and the command refuses if the record changed since, or has no open incident. Resolving retires that attempt: sampling stops and the final record, with your reason, is published like any observation; nothing is reassigned. Running monitor again on a campaign with no open incident starts a new attempt; with one open, it refuses until you resolve it. When a campaign finishes or is abandoned, echod retires its monitor, resolves any open incident as campaign_closed and stops sampling it; other hosts prune the retired record under the usual retention, and this host removes its own retired monitors under the same retention. The dashboard shows local records only. ecc dispatcher policy [--adopt all|off] shows or sets whether this host's echod adopts campaigns other hosts declared. The default, all, makes it a second observer that samples the expected member with its own roster, so the loss of the declaring host is still reported. An adopted monitor follows its origin when that host resolves or re-arms the attempt, but an open incident here stays open until you resolve it or its member is seen again; off retires adoptions with no open incident and keeps the rest. --max-adopted N caps adoptions (default 128), always leaving room for your own monitors. Status names each observer of a campaign, warns when fewer than two are current, and says when the cap holds a campaign back. ecc dispatcher assign --campaign NAME --task ID --to MEMBER writes the assignment to a ledger on this host, with a stable ID, before it queues the message, then records the queued message. ecc dispatcher assignments [CAMPAIGN] [--json] reads the ledger against each task: delivery_unknown means the intent was recorded but no queued message was; send_failed means the send returned an error and the outbox then held no record for it. ecc dispatcher delivery [ASSIGNMENT|CAMPAIGN] [--since DURATION] [--json] shows, for each assignment, what the ledger, the outbox, the sender's saved send budget, the daemon's trail and the task each say, kept apart: a message still in the outbox, a budget hold only where the daemon recorded one for that message, the claim, completion and acceptance. It reads local files, writes nothing and sends nothing. An absent outbox file is not receipt by the worker, a claim is not activity, and a missing hold record is not proof that nothing was held. Delivery JSON keeps the sample time (observed_at) separate from scan_started and observed_until. A shared monotonic span keeps read boundaries from moving backward across rows; the files are still sampled, not a synchronized snapshot. A detected wall-clock step sets clock_stepped and records the largest observed signed offset in clock_step. Every budget and hold record in that pass, earlier rows included, then reports clock_uncertain whatever its timestamp: it is named but carries no time and is not used as evidence. clock_tolerance states the smallest disagreement the scan can see (a step below it is not detected, so an unstepped view does not show the clock held still). With no detected step, a record beyond its read boundary is dated_after_observation, which is what the sampled timestamps say and not proof of the future. A budget record timestamp within the observed read interval is recorded_during_read; it does not establish a synchronized snapshot. Use JSON for these diagnostics; text output summarizes delivery. ecc dispatcher work [ASSIGNMENT|CAMPAIGN] --stale-after DURATION [--max-skew DURATION] [--json] observes assigned work progress across a closed vocabulary: no_report, stale_report, reported_progress, waiting_dependency, waiting_review, blocked_external, expired_claim, completed, completed_by_other, unclaimed, report_from_future, unavailable, and corrupt. Author completion (Done) is strictly attributed by recorded evidence (t.Evidence.By); when completed by a different member, the state is completed_by_other. If a task in Todo has an absent or empty run attempt, uncertainty is retained as unclaimed; self-reported progress without authoritative attempt identity does not infer a past claim. A live CLI, fresh presence, or renewed lease does not prove progress. no_report means the current attempt has no accepted owner report; reported_progress is a worker statement, not independent verification. completed records execution evidence and does not establish that a reviewer accepted the intended result. A completed review can reject it. A rejected task record remains corrupt; an incomplete scan cannot establish that an unreadable task is absent or ready. The ledger does not leave this host and reassigns nothing. Alert delivery and fenced takeover remain release work.

Isolated task worktrees

ecc worktree create --checkout PATH --root PATH --name NAME --task ID --attempt ID --base COMMIT: Source build. Create one Linux Git worktree and task-attempt branch from an explicit full commit ID. Supply absolute checkout and destination-root paths; the existing destination root and resulting task directory are owner-private (0700). Output is an ownership JSON record with the worker directory. Existing destinations and interrupted creation are preserved. Ownership metadata stays outside the checkout. This command does not claim tasks, launch workers, merge, or delete work. Git hooks and transports are disabled, but repository-configured filters may execute code; it is not a process sandbox. Other platforms currently refuse creation. Use separate worker directories and one integration owner; no coding-performance benefit has been established.
ecc worktree inspect --root PATH --task ID --attempt ID: Source build. Read-only reboot-recovery inspection of private intent and ownership records plus the recorded Git worktree identity. Reports owned_complete, intent_only, partial_or_unknown, owner_without_intent, or absent. Uncertain data is preserved for operator review; inspect never retries, repairs, or deletes a worktree.

Worker Recovery

ecc worker inspect MEMBER [--json]: Read the local durable-worker definition, task checkpoint, and provider turn checkpoint and the conversation owner/reboot-recovery record without creating state, contacting echod, or calling a model. The summary shows recovery classes, latest phases and digests, conversation identity, task binding, and any recorded boot-reclaim count. A clean local checkpoint still does not prove remote provider or task-authority state; an interrupted or uncertain turn is never replayed automatically.
ecc worker recover inspect|settle-turn|inspect-task|settle-task|inspect-claim|adopt-claim|settle-claim ...: Inspect and reconcile durable-worker state after interruption. Turn settlement records an explicit operator disposition and never marks an interrupted turn successful. Task settlement is available only when the local authority mirror proves completion, release, or a higher fence; it refuses a same-owner live claim. Unresolved claim intents require explicit review and an at-authority non-ownership attestation. A committed claim may be adopted only for a terminal task with matching assignment and receipt evidence; a live lease needs authority-side proof. Settlements record operator reasons and attestations, bind to inspected plan digests, take non-blocking owner locks, and make no provider call, task claim, renewal, or replay.

Resource Incident Review

ecc host resources inspect: Read the local account's resource incident and last acknowledgement, plus the Echo aggregate cgroup's current memory, configured limits, memory-event counters, and pressure when Linux cgroup v2 is available. Unavailable or unbounded cgroup state is reported as unqualified. When no local resource state exists, inspection is read-only and does not initialize it. The account record is not host-wide protection; the aggregate only contains work and local model services actually placed inside its configured cgroup.
ecc host resources acknowledge --incident-digest SHA256 --reason TEXT --confirm-stopped: Record an operator disposition for the exact open incident after relevant workers are stopped and uncertain task or conversation state is reviewed. Acknowledgement does not restart services, resume a worker, or replay a provider turn.

Autonomous AI Teammates

ecc ask [flags] PROMPT...: Query frontier or local AI models grounded in live net context. Ground with --net (presence), --holds, --tasks, or --inbox. Supports OpenAI, Gemini, Anthropic, DeepSeek, Groq, Mistral, OpenRouter, and local Ollama.
ecc peer [flags]: Run an API-backed teammate that answers incoming messages. The stable --session default identity keeps its response journal across restarts; use distinct --session NAME values for independent peers. Only one peer process may own a given identity. Restart with the same handle and session to recover a saved response or finish marking an input whose reply was queued. If inference or publication has an unknown outcome, the worker stops for reconciliation instead of retrying blindly. Inspect an interrupted attempt with ecc peer recover --session NAME --json. To resolve it, specify --action retry-inference, retry-publication, or confirm-queued, plus the inspected --expect SHA256 and an evidence-based --reason. Retries also require --accept-duplicate-risk; confirmation requires a matching queued reply envelope via --reply-file PATH. The decision is recorded before changing the journal. Recovery itself performs no inference or publication; restart the same peer to continue. Supplied evidence is not proof of remote delivery. Do not delete journals to bypass recovery checks. This is not exactly-once execution. Peer storage admission defaults to 1 GiB, configured via limits.peer_storage_bytes in configuration or ECHO_PEER_STORAGE_BYTES (valid range: 8 MiB to 16 GiB). An 8 MiB admission reservation per stable identity yields 128 identities by default and up to 2048 maximum. Lowering the budget halts new admissions once reservations reach the limit; it does not delete existing identities, and existing peers can still recover. Inspecting an absent identity does not consume a slot. This bounds normal peer-journal payload growth, not a whole-disk quota; exports, inboxes, and outboxes are excluded. Ownership acquisition (including inspect) and each journal or audit write validate bounded directories and remove only recognized regular uncommitted .tmp-<digits> fragments, retaining authoritative attempt records, audits, and permanent locks. Unexpected names, symlinks, oversized files, and other unsupported entries require operator inspection. Process-crash cleanup is not proof against hardware power loss. Recovery audits store at most 64 records of 16 KiB each. Export decision audits with ecc peer recover --session NAME --action export-audit --output-dir NEW_DIRECTORY. The directory must be outside active state and its parent must exist. Unix checks ancestor ownership and replacement safety, and Windows requires the destination to reside under the current user profile on a fixed local NTFS volume. Add --prune-audit to remove exported historical audits while preserving the decision for the current unresolved snapshot. Export completes before pruning starts; ownership locks remain. Windows audit export-before-prune durability remains under qualification; pruning is refused. Exports include operator reasons and should be kept private.

Coordinate remote Claude Code, Codex and Antigravity workers

Each host needs its own running daemon connected to the same echo net. Install and authenticate the agent CLIs on the worker host, confirm that ecc ls sees the coordinator, then start dedicated workers from their assigned checkout. On Linux, every ecc run requires the dedicated /echo.slice/echo-workers.slice; the process must already be inside it, and Echo checks finite limits without creating or enforcing them. The root-owned guard is available in source but is not installed by setup and has not completed native VM qualification; guarded Linux runs require its live admission socket. SSH can prepare or launch processes; assignments and receipts travel through echo.

# Run each in its own terminal or supervised process on the worker host.
$ ecc run --resource-aggregate-cgroup /echo.slice/echo-workers.slice --drive --mail work --session remote-codex --sandbox workspace-write codex
$ ecc run --resource-aggregate-cgroup /echo.slice/echo-workers.slice --drive --mail work --session remote-claude claude
$ ecc run --resource-aggregate-cgroup /echo.slice/echo-workers.slice --drive --mail work --session remote-agy --project /path/to/project agy

These commands select queue-processing sessions; they are not a complete permission setup. --mail work treats mail as work but does not grant tool access. Without it, mail is framed as information. Keep model choices in each CLI's configuration. The --sandbox, --approval, and --approve flags are Codex-only (via its app-server session handler); non-Codex tools rely on their native permission modes, project grants, or settings. For driven agy sessions, --project <path> binds the permission project (defaulting to the current working directory).

Set an explicit executable search path for remote launches. Noninteractive SSH shells may not include the directory containing the CLIs.
Authorize the assigned checkout, required helper commands and echo state access. Headless sessions cannot rely on someone answering a prompt. Claude needs message-body read access; Antigravity may also need explicit echo_read and echo_inbox MCP permissions. Note that Codex in workspace-write sandbox mode requires the echo state directory explicitly included in its sandbox writable roots so it can write queue records. Use each installed CLI's permission syntax and narrow grants.
Address the actual member ID from ecc ls. Use one shared task board, claim a lease before editing and stop work when ownership expires. Verify artifacts and source revisions independently of worker reports.
For a retry, keep the task ID and send a new attempt message explaining what changed. Observe the task, receipt and process outcome separately: successful work can be followed by a denied optional tool call.
On shutdown, stop only the workers you started, release their reservations and remove temporary grants. Preserve the task evidence for resumption.

Tested on 2026-09-23 with a Linux coordinator and all three CLIs on macOS: 15 coordination and fixture-verification checks passed after permission fixes. On 2026-09-25, a Linux Codex coordinator drove a real same-host Antigravity (agy) session through a multi-page documentation update, hold acquisition, and independent review. This is not a coding-quality benchmark, a universal ranking of coordinator roles, or a promise that every final agent turn exits successfully.

CLI workflows and subscription limits: Users choose whichever CLI fits their installed tooling and context; there is no universal best coordinator. CLI subscription tiers (such as Pro or Max) differ from direct API billing, and remaining context is not subscription quota; see the installation and workflow guide for details.

Agent Adapters & Runtime

ecc run [flags] <cli> [args...]

Run any agent CLI as a managed child process with net membership, stdio capture, and automatic presence tracking. The required --resource-aggregate-cgroup /echo.slice/echo-workers.slice checks finite, root-owned memory and swap limits and verifies the caller is inside the dedicated slice. It does not create or enforce those limits; the host operator must reserve the slice for Echo workers and local model services. The root-owned guard is available in source but is not installed by setup and has not completed native VM qualification; guarded Linux runs require its live admission socket.

ecc mcp

Serve the net as a Model Context Protocol (MCP) server over stdio, built on the official Go SDK. A client that speaks MCP over stdio connects without shell hooks. Claude Code, Goose, OpenCode (a smoke test) and the Go SDK client have been exercised; Cursor, Windsurf and Claude Desktop have not been qualified.

Native tools include: echo_whoami (inspect session ID, host, tool, and held paths), echo_ls (members on the net with host, tool, state, reach, repo and branch), echo_send (direct and topic messaging), echo_inbox and echo_read (mail queue and full bodies), echo_hold, echo_holds, and echo_release (distributed file reservations), echo_tasks, echo_task_add, echo_task_claim, echo_task_renew, echo_task_done, echo_task_block, echo_task_progress, echo_task_status, echo_dispatcher_delivery (the read-only delivery view of dispatcher assignments), and echo_task_drop (shared tasks, atomic leasing, recorded evidence, and self-reported progress with a status that keeps what is known apart from what was said), and echo_campaigns and echo_campaign (list, start, finish or abandon campaigns that group tasks under one goal).

Tool argument schemas come from the server's tools/list answer, not from the CLI flags: paths and to are JSON arrays, and ttl and lease are Go durations such as 30m.

echo_task_claim returns task.fence and task.attempt. Long jobs call echo_task_renew with that exact tuple; an expired or replaced claim is refused. echo_task_done requires that exact tuple with the task ID and evidence; stale claim tuples are refused. If renewal becomes uncertain, the worker should stop and reconcile the authoritative task before continuing.

A successful repository-scoped claim also returns repository_reservation with the task's repo_scope. This is the shared cross-worktree path lease. The MCP holding field and echo_holds list only local advisory holds; they do not show shared repository leases. If the returned scope is missing or unexpected, do not assume the paths were reserved.

Context resources: echo://whoami, echo://roster, echo://holds and echo://tasks, each exactly what echo_whoami, echo_ls, echo_holds and echo_tasks (all) return. Editors read these resources directly into prompt context without consuming tool execution turns.

Client configuration, in the mcpServers form many clients read:

{
  "mcpServers": {
    "echo": {
      "command": "ecc",
      "args": ["mcp"]
    }
  }
}

ecc hook claude|codex

Hook adapter processing event payloads on stdin from Claude Code or OpenAI Codex sessions.

ecc hooks off [reason] | on | status

Emergency kill-switch to pause or resume participation on this host instantly without uninstalling anything.

ecc login --token-stdin [--org ORG] [--gateway URL]

Read an administrator-issued token from standard input, write it to a protected private token file, configure the cloud profile in config.json, and set active_profile to cloud. Standard input keeps the token out of command arguments; profile listings redact credentials. This does not authenticate to a server, provision an account, or verify connectivity. Public hosted enrollment is not available. Start or restart echod using the cloud profile and verify presence with ecc ls.

ecc switch [local | cloud | <profile>] [--json]

Select a connection profile for subsequent processes. Existing daemons require restart with the intended configuration. Without arguments, lists all available connection profiles and highlights the active profile. With a target name, atomically switches the active profile in the operator configuration file (config.json). A legacy profiles.json produces a conversion error only when config.json is absent.

Cryptographic Identity & RBAC

ecc cert inspect [MEMBER] | keygen --member MEMBER | issue [flags] | list [--json]: Manage Ed25519-signed member identity certificates. inspect displays an agent certificate, public key, role (admin, architect, worker, ci, observer), and scoped directory permissions. issue mints a new cryptographically signed certificate with --role, --allow, --deny, and --ttl. list displays all trusted certificates in the net.
ecc revoke TARGET --reason "..." [--authority-key PATH]: Create a signed member, key, or certificate revocation. Daemons propagate and validate the record; disconnected hosts receive it after reconnection. Creates a signed Ed25519 revocation record, drops any active file reservations held by the target, and is checked by enforced echo operations. Revoke broker credentials separately to remove machine access.
ecc revocations [--json]: List all active cryptographic revocations and audit reasons currently enforced across the net.

Observability & Diagnostics

ecc log [--since D] [--from M] [--grep R] [--host H]: Audit trail of every message, delivery, wake, hold, and task transition in strict chronological sequence.
ecc stats [--since D] [--net N] [--json]: Aggregate throughput, delivery latencies, and event counts from the local trail metrics.
ecc probe [flags]: Measure network latency to the NATS server and exercise compare-and-set claims against JetStream key-value buckets.
ecc bench [flags]: Run high-throughput end-to-end message benchmark across the live net.
ecc validate FILE...: Validate raw JSON wire records against the schema; exits 1 on format or security violations.
ecc version: Print the current binary build version and revision.
ecc update status|check|trust|apply|recover: The operator's signed updater, an admin command that agents are never granted. It reads only local files and makes no network call. Managed updates are opt-in: trust init pins the root and trust adopt makes an install managed. status --json prints a versioned document for scripts. ecc update help lists the flags.
ecc completion bash|zsh|fish: Print a shell completion script for the command names. Load it with source <(ecc completion bash), the same with zsh, or ecc completion fish | source. The script reads no state and makes no network call.

Environment Variables, Configuration & Guard Defaults

System parameters can be configured via command-line flags, environment variables, or the shared operator configuration file (config.json):

Configuration File & Platform Paths: File selection precedence: --config FILE (precedes any command) > ECHO_CONFIG_FILE > config.json in ECHO_CONFIG_DIR > platform user directory (Linux ~/.config/echo/config.json, macOS ~/Library/Application Support/echo/config.json, Windows %APPDATA%\echo\config.json). For individual settings, present command flags override environment variables, which override config.json values, followed by defaults. Not every setting exposes all three interfaces; consult config schema. Operator configuration subcommands (config init, config validate, config show, config inspect, config schema) manage the JSON document. config inspect reports shared-loader input provenance (active profile, configuration path, resolved endpoints, and whether values come from environment, configuration, built-in defaults, or are unset) with secrets redacted; it never displays secret contents, and does not enumerate consumer-specific defaults or command flags.
Logging & Diagnostics: ECHO_LOG_LEVEL (default: info; choices: debug, info, warn, error), ECHO_LOG_FORMAT (default: json; choices: json, text), ECHO_LOG (daemon diagnostic log file path), and ECHO_METRICS=0 (disable metrics trail). Corresponding configuration fields are logging.level and logging.format (shared across components), and logging.file (currently honored by the echod daemon, defaulting on Windows to log/echod-service.jsonl inside the network state directory). Structured logging supports JSON and text output with redaction for recognized secret fields and known credentials; arbitrary payloads may contain unmodeled secrets, and automatic file retention or log rotation is not implemented. Bootstrap errors and full event coverage remain under qualification.
Runner Frame Limits, Write Deadlines & Transcript Buffering: limits.drive_frame_bytes in config.json or ECHO_DRIVE_FRAME_BYTES bounds driven CLI stdout frames (default: 4 MiB / 4194304 bytes; valid range: 1024 to 16777216 bytes). Oversized frames terminate and reap the owned child process and fail the runner. limits.drive_write_timeout_ms in config.json or ECHO_DRIVE_WRITE_TIMEOUT_MS bounds driven stdin record writes (default: 15s / 15000 ms; valid range: 100 to 60000 ms) across handshakes, protocol replies, and turns. A stalled write terminates the child and fails the run rather than replaying partial instructions. This bounds protocol delivery time, not model inference or whole-task duration. Early transcript capture buffers up to 64 records at at most 2 KiB of raw data per record, bounding retained early payloads to 128 KiB. In source-qualified driven runners, mail is admitted and marked with a conservative delivery_uncertain state before moving to seen/ and writing to the CLI stdin pipe. Writing confirms bytes reached the child process's pipe, not completed model inference or task execution. A failed, stalled, or interrupted write retains the uncertainty marker and requires operator inspection and reconciliation (ecc usage session reconcile --reviewed-delivery); mail is never automatically replayed. Messages remain readable with ecc read, and automatic dispatch recovery remains open. Neither partial nor successful writes guarantee exactly-once execution. Total session stdout/stderr disk allowances and process memory caps remain unimplemented.
Peer Storage & Recovery Budget: limits.peer_storage_bytes in config.json or ECHO_PEER_STORAGE_BYTES bounds peer-journal storage admission (default: 1 GiB / 1073741824 bytes; valid range: 8 MiB to 16 GiB). An 8 MiB admission reservation per stable identity yields 128 identities by default and up to 2048 maximum. Lowering the budget halts new admissions once reservations reach the limit; existing peers still recover and stored identities are not deleted. Normal peer-journal payload growth is bounded, excluding exports, inboxes, and outboxes.
Core Identity & Paths: ECHO_NET (default: home), ECHO_HOST (local hostname), ECHO_MEMBER (current session token), and ECHO_STATE_DIR (default: ~/.local/state/echo/<net>).
Daemon Transport & Security: ECHO_NATS_URL (NATS server address), ECHO_CREDS (NATS credentials file), ECHO_TLS (enable TLS), ECHO_TLS_CA (CA cert path), ECHO_TLS_CERT and ECHO_TLS_KEY (client certs for mTLS), and ECHO_NATS_TOKEN (local auth token).
Reservation Enforcement & Loop Protections: ECHO_HOLDS (default: advisory; set to enforce to refuse conflicting edits), ECHO_MAX_HOPS (6), ECHO_SEND_RATE (30/hr), ECHO_SEND_BURST (10), ECHO_WAKE_RATE (12/hr), ECHO_DEDUPE_WINDOW (10m), and ECHO_PAIR_LIMIT (8 pairs per 5m).
Role-Based Access Control (RBAC): ECHO_RBAC (default: advisory; set to enforce or strict to strictly mandate verified cryptographic certificates and role/path boundaries; set to off to disable checks), and ECHO_ADMIN_KEY (hex-encoded Ed25519 seed or private key used to sign certificates and revocations).

Configuration & Session Quota

ecc config init|validate|show|inspect|schema: Manage the shared JSON configuration document (config.json). config init writes a starter document; config validate verifies JSON syntax and cross-field constraints without opening private credential files; config show prints stored settings with credentials withheld; config inspect reports input provenance (active profile, configuration path, resolved endpoints, and origin) with sensitive values and credentials strictly redacted; config schema outputs JSON Schema for editor validation.
ecc usage normalize|show|statusline capture|session|member|pool: Offline native CLI rate-limit event processing, session quota inspection, and bounded conversation and pool containment. usage normalize ingests native CLI stream events from standard input with RFC 3339 timestamps and freshness bounds (--max-age), distinguishing observed limits from estimated or unknown usage under subscription or API billing without making network calls. usage show inspects saved bounded session quota snapshots. usage statusline capture records the quota in Claude Code status-line JSON read from standard input; add it to your own status-line script (see the install guide). It prints nothing, always exits 0 and adds a few milliseconds, never more than 200 ms. Echo never edits status-line settings. Source-qualified pre-release subcommands (usage session list|inspect|reconcile, usage member list|inspect|reconcile, and usage pool inspect|reconcile) inspect local incident markers and record operator reconciliation under same-user attestation without making network calls. Member reconciliation requires an exact member ID, a fresh marker hash, and review of any surviving child or external effects. usage member list discovers retained local member markers; busy, invalid, or truncated scans report incomplete status, and another host cannot inspect those markers until the original host state is available. Quota pool gating binds through explicit quota.run_pool_by_tool configuration and coordinates only across wrappers sharing the same local net state directory with native agy classification; it does not provide automatic reset tracking, cross-host coordination, or global subscription cap enforcement, and is source-qualified rather than fleet-installed.

Agent Setup Reference (Pre-release)

Current working trees include the source-built setup command to plan, verify, and manage client configuration across supported coding agents. This is an unreleased pre-release tool; there is no public installer yet. See the installation guide for building from source and integrations for detailed adapter specifications.

ecc setup [--agents <clients>] [--mcp] [--permissions] [--skills] [--check] [--format text|json]: Plan client integrations by discovering agent executables on PATH, or probe the local MCP server in disposable state with --check. --check --agents <clients> starts the command each client has registered instead. With no component flag every component a client supports is included. Operates strictly read-only without modifying client settings unless run with --apply or --remove. Reports registration-not-inspected by design: detecting a binary is discovery, not proof of registration or broker connection.
setup --apply|--remove --agents <clients>: Apply or remove MCP registration, the ecc permission grant and the coordination skill for each selected client, or only the components named by --mcp, --permissions or --skills. MCP uses the mcpServers.echo JSON entry for Claude and Antigravity (agy), or staged TOML for Codex. Removal deletes only what echo setup wrote, plus files and containers it created once they are empty. Explicit --agents selection is mandatory. Running agent sessions must be closed before modification to prevent file rename races. Unmanaged configurations are preserved for manual review and never silently adopted.
setup --permissions --agents claude,codex,agy [--apply|--remove]: Manage the native grant for member commands only (send, hold, task and the rest of the coordination set) on trusted absolute ecc paths: permissions.allow entries in ~/.claude/settings.json and ~/.gemini/antigravity-cli/settings.json, and prefix rules in ~/.codex/rules/echo-ecc.rules. Admin commands such as setup, config, run and login are never granted. Only an ecc installed by deploy/local install (or ~/.local/bin/ecc) is granted, never one another account could replace or one inside a git worktree or agent workspace. Goose and Aider have no command-level mechanism and get no grant.
setup --skills --agents <clients> [--apply|--remove]: Plan and inspect canonical coordination skill (SKILL.md) targets and hash by default; add --apply to install or --remove to remove. Codex and Goose share ~/.agents/skills/echo-coordination/SKILL.md (removing for either client removes it for both). Claude and agy use native skill directories.

Client boundaries: Goose (tested on 1.52.0) gets only the shared skill from setup; its persistent MCP apply remains unfinished; connect per session using --with-extension 'echo:ecc mcp' without YAML edits (requires source-built bin/ on PATH so Goose can launch the inner ecc process). Aider operates via the CLI wrapper (ecc run) without an MCP adapter. Lifecycle phases (installation, registration, discovery, model invocation, production connectivity) are distinct; tool discovery does not guarantee model invocation or network reachability.

Binary Update Status & Foundations

Releases of ecc and echod are signed, and metadata is checked against a pinned root of Ed25519 keys before anything is installed. ecc update is the operator's updater and an admin command: ecc setup never grants it to agents. Managed updates are opt-in. ecc update trust init pins the root, delivered out of band, and ecc update trust adopt makes one install managed. On Linux, ecc update apply --live-service stages the new pair, trials it, then commits or rolls back, and ecc update recover settles an interrupted update. Windows and macOS refuse service activation for now. There is no public release server yet, so metadata and archives reach a host as local files, and nothing installs itself.

Release checks verify metadata without changing trust: ecc update check reads a local file, and an opt-in scheduled check in echod (off by default, bounded, honoring an offline setting and a version pin) can fetch an https source. Both report through one local file shown by ecc update status and the human ecc whoami, never in JSON, hooks or MCP. See docs/CONFIGURATION.md for the settings.