# hoody-agent Subskill ## Overview ### What Is hoody-agent? The hoody-agent service is the AI agent orchestration and task execution layer of the Hoody platform. It provides the complete lifecycle management for AI-powered agent sessions, including session creation, prompt dispatch, tool execution, workflow orchestration, memory management, skill administration, todo tracking, GitHub integration, and multi-provider LLM authentication. hoody-agent is the bridge between human operators (or automated systems) and the underlying AI model infrastructure. Every interaction with an AI agent—whether it is a simple prompt, a complex multi-step workflow, or an autonomous todo run—flows through the hoody-agent service. ### When to Use hoody-agent Use the hoody-agent service when you need to: - **Create and manage AI agent sessions** — spawn conversational sessions, dispatch prompts, stream responses, and manage session lifecycle. - **Define and configure chat agents** — create custom agent definitions with specific models, tools, system prompts, and turn limits. - **Execute tools** — run built-in or MCP tools in a session-scoped or sessionless context, with gating and confirmation workflows. - **Manage memory** — store, recall, search, and consolidate contextual memory across projects. - **Operate workflows** — define multi-step workflows, dispatch runs, monitor progress, and handle workflow messages. - **Track todos** — file, triage, claim, run, and approve proposals for autonomous task orchestration. - **Manage skills** — install, configure, trust, and toggle skills from local stores or the remote hub. - **Authenticate with LLM providers** — configure API keys, OAuth flows, and account pools for multiple LLM providers. - **Integrate with GitHub** — clone repos, commit changes, open pull requests, and sync branches. - **Monitor and debug** — query logs, stream log tails, view metrics, and check health. - **Manage hooks** — define lifecycle hooks that fire on session events, with trust and confirmation gates. - **Schedule loops** — create recurring agent loops that fire at intervals with cost and wall-time budgets. ### Authentication Model All hoody-agent operations require authentication. Use one of these methods: | Method | Flag / Variable | Description | |--------|----------------|-------------| | CLI token | `--token ` or `-t` | Bearer token passed directly | | Environment variable | `HOODY_TOKEN` | Token from environment | | Username/password | `--username` / `--password` | Automatic login flow | | Stored credentials | `hoody auth login` | Persistent credential storage | | Config file | `--config ` | Path to `~/.hoody/config.json` | | Named profile | `--profile ` | Use a specific configuration profile | The health check endpoint (`GET /health`) is the only unauthenticated route. ### How It Fits into Hoody Philosophy hoody-agent embodies the Hoody principles of: - **Container-first architecture** — sessions bind to containers at creation time. All mutating session operations are scoped to the frozen realm/container/cwd. - **Human-in-the-loop safety** — destructive operations (consolidation, hook mutations, todo runs) require explicit human approval or gated nonces. - **Global vs. scoped resources** — provider catalogues, usage rollups, and model listings are daemon-global. Sessions, agents, skills, and todos are scoped to cwd/config_dir and active realm. - **CLI-only interaction model** — all operations are performed through the `hoody` CLI. Never call HTTP endpoints directly. ### Scope Model hoody-agent resources operate at different scopes: | Scope | Resources | Notes | |-------|-----------|-------| | **Daemon-global** | providers, usage, metrics, health, models catalogue, OpenAPI specs | No realm or container needed | | **Active-realm-scoped** | sessions, agents, skills, todos, statistics | Per-request realm header rejected; uses active realm | | **cwd-scoped** | GitHub operations | Realm header returns 400 `realm_scope_unsupported` | | **Session-scoped** | hooks, loops, tasks | Require a live `session_id` | | **Container-targeting** | most operations via `-c ` | Or `HOODY_CONTAINER` env var | --- ## Core Resource Workflows ### 1. Agents — Chat Agent Definitions Agents are reusable chat-agent definitions with system prompts, model assignments, tool allowlists, and turn limits. They are scoped to the requesting cwd/config_dir. #### List All Agents ``` hoody agent list -c -o json ``` Returns built-in and custom agent definitions for the active realm. #### Create a New Agent ``` hoody agent create -c \ --name "code-reviewer" \ --system-prompt "You are a senior code reviewer. Focus on security, performance, and maintainability." \ -o json ``` Creates or overwrites a custom chat-agent definition from name, frontmatter, and system prompt. #### Read Agent Source ``` hoody agent get-source -c --name "code-reviewer" -o json ``` Returns the raw markdown source (frontmatter + system prompt). #### Write Agent Source ``` hoody agent put-source -c --name "code-reviewer" \ --source "# Code Reviewer Agent\n---\nmodel: anthropic/claude-sonnet-4-20250514\ntools:\n - read_file\n - list_files\n---\nYou are a senior code reviewer." \ -o json ``` Overwrites the raw markdown source of a chat-agent definition. #### Set an Agent's Model ``` hoody agent set-model -c --name "code-reviewer" --model "anthropic/claude-opus-4-8" -o json ``` Sets (or removes with empty model) an agent's frontmatter model line. #### Set an Agent's Tool Allowlist ``` hoody agent set-tools -c --name "code-reviewer" \ --tools '["read_file", "list_files", "search_code"]' -o json ``` Sets the agent's frontmatter tools line. Empty list removes the allowlist (all tools). #### Toggle a Single Tool ``` hoody agent toggle-tool -c --name "code-reviewer" --tool "search_code" -o json ``` Toggles one tool on/off in the agent's frontmatter tools line. #### Set Max Turns ``` hoody agent set-turns -c --name "code-reviewer" --turns 25 -o json ``` Sets the agent's max-turns frontmatter value. #### Copy an Agent ``` hoody agent copy -c --name "code-reviewer" --new-name "code-reviewer-v2" -o json ``` Copies a chat-agent definition to a new name. #### Rename an Agent ``` hoody agent rename -c --name "code-reviewer-v2" --new-name "senior-reviewer" -o json ``` Renames a custom chat-agent definition. #### Reset Agent to Shipped Default ``` hoody agent reset-to-shipped -c --name "default" -o json ``` Restores one agent to its shipped default, discarding local customizations. Shipped-default agents and the configured default chat agent are protected from deletion. #### Delete a Custom Agent ``` hoody agent delete -c --name "senior-reviewer" -o json ``` Deletes one custom chat-agent definition. Shipped-default agents and the configured default chat agent are refused. --- ### 2. Sessions — Agent Session Management Sessions are the primary interaction unit with AI agents. A session binds realm, container, cwd, tool mode, and backend at creation time and cannot change them. #### List Sessions ``` hoody agent list-sessions -c -o json ``` Lists persisted sessions (open + closed) for the requesting cwd, with an `attached` flag for live sessions. Supports pagination via `x-pagination` headers. #### Create a New Session ``` hoody agent create-session -c --agent "default" -o json ``` Opens a new agent session, freezing realm/container/cwd/tool_mode/dir_scope/backend at start. For BYOA (Bring Your Own Agent) with an ACP backend: ``` hoody agent create-session -c \ --backend "acp" \ --delegated-agent "codex" \ -o json ``` #### Get Session Summary ``` hoody agent get-session -c --id "" -o json ``` Returns the persisted summary. A live session surfaces its frozen start binding and `attached: true`. #### List Distinct Session Working Directories ``` hoody agent list-cwds -c -o json ``` Returns the distinct working directories across all persisted sessions, most-recent first. #### Dispatch a Turn (Fire-and-Observe) ``` hoody agent post-message -c --id "" \ --message "Analyze the security implications of this codebase" \ -o json ``` Dispatches a user turn and returns `{job_id}`. Observe `agent_done` on the session's stream. #### Dispatch a Turn with Streaming ``` hoody agent prompt-stream -c --id "" \ --message "Explain the architecture" \ -o json ``` Dispatches a turn and streams the resulting events over SSE from the seq captured just before dispatch. #### Dispatch a Turn Synchronously ``` hoody agent prompt-sync -c --id "" \ --message "Summarize the codebase" \ -o json ``` Dispatches a turn and blocks until `agent_done`. Returns `{pending_gate}` when a turn parks. #### Answer a Parked Question ``` hoody agent answer-question -c --id "" \ --answer "Yes, proceed with the refactoring" \ -o json ``` Answers a parked ask-the-user question. Returns 409 on mismatch (`no_pending_gate`, `stale_gate`, `gate_already_answered`, `gate_type_mismatch`). #### Get Answer Assistance ``` hoody agent answer-assist -c --id "" -o json ``` Runs a one-shot helper-model call that proposes answers for a parked question. The real answer still travels via `/answer`. #### Confirm a Tool/Dir Gate ``` hoody agent confirm-gate -c --id "" \ --approved true \ -o json ``` Approves or denies a parked tool/dir confirmation. #### Cancel the Active Turn ``` hoody agent cancel-turn -c --id "" -o json ``` Stops the active turn at the server layer; spares the session and background tasks. #### Close a Session ``` hoody agent close-session -c --id "" -o json ``` Tears the session down. The daemon cancels it and removes it from the live map. #### Delete a Session ``` hoody agent delete-session -c --id "" -o json ``` Closes the live session connection. Use `--hard` to also remove the persisted record: ``` hoody agent delete-session -c --id "" --hard -o json ``` #### Switch the Chat Agent ``` hoody agent set-chat-agent -c --id "" \ --agent "code-reviewer" \ -o json ``` Live chat-agent switch, echoed as an event. #### Switch the Session Model ``` hoody agent set-session-model -c --id "" \ --model "anthropic/claude-sonnet-4-20250514" \ -o json ``` Live model switch, echoed as an event. #### Set Reasoning Effort ``` hoody agent set-effort -c --id "" \ --effort "high" \ -o json ``` Live reasoning-effort change. Valid values: `low`, `medium`, `high`, `xhigh`, or `""` for model default. #### Set Verbosity ``` hoody agent set-verbosity -c --id "" \ --verbosity "concise" \ -o json ``` Live verbosity change. Valid values: `normal`, `concise`, `terse`, `minimal`. #### Toggle Hoody Shell-Env Injection ``` hoody agent set-hoody-env -c --id "" \ --enabled true \ -o json ``` Live toggle of the session's `HOODY_*` shell-env contract for the bash tool. #### Arm/Disarm Auto-Reply Loop ``` hoody agent set-auto-reply -c --id "" \ --rounds 5 \ --model "anthropic/claude-sonnet-4-20250514" \ --writes true \ -o json ``` Arms the self-driving auto-reply loop with specified rounds, replier model, and write opt-in. #### Flip Auto-Reply Write Opt-In ``` hoody agent set-auto-reply-writes -c --id "" \ --writes true \ -o json ``` Flip the write-class opt-in on an already-armed auto-reply loop WITHOUT re-arming. #### Trim Session History ``` hoody agent trim -c --id "" \ --turn-index 5 \ -o json ``` Truncates the session's conversation history to (and including) the given turn index. #### Replay Buffered Events ``` hoody agent replay -c --id "" -o json ``` Returns the gateway's buffered event tail for a LIVE session, with `min_seq`/`max_seq` for resume. #### Attach to Session Event Stream ``` hoody agent stream -c --id "" ``` WebSocket (primary) or SSE attach to a live session's full `event.*` taxonomy. Use `--since ` or `Last-Event-ID` for resume from the 1024-event replay ring. #### Send Workflow Message ``` hoody agent post-workflow-message -c --id "" \ --message "User feedback on step 3" \ -o json ``` Injects user feedback/input into a running workflow. --- ### 3. Loops — Recurring Agent Loops Loops are recurring agent tasks scheduled on a session with intervals, budgets, and stop conditions. #### List a Session's Loops ``` hoody agent list-loops -c --id "" -o json ``` Returns the recurring agent loops as `{items, meta:{total}}` with optional pagination. #### Create a Loop ``` hoody agent create-loop -c --id "" \ --interval "5m" \ --max-runs 10 \ --stop-when "no_changes" \ -o json ``` Creates a recurring agent loop on a session with interval, max runs, stop predicate, and cost/wall budgets. #### Update a Loop ``` hoody agent update-loop -c --id "" \ --loop-id "" \ --paused true \ -o json ``` Updates a loop. Set exactly one intent per request: `paused` (pause/resume), `expires_in` (expiry), or body fields for configuration. #### Delete a Loop ``` hoody agent delete-loop -c --id "" \ --loop-id "" \ -o json ``` Deletes a recurring loop from a session. #### Run a Loop Immediately ``` hoody agent run-now-loop -c --id "" \ --loop-id "" \ -o json ``` Fires a loop's next run immediately, off the dedicated loop lane. --- ### 4. Tasks — Background Subagent Tasks Background tasks are subagent operations spawned during a session turn. #### Request Task Snapshot ``` hoody agent list-tasks -c --id "" -o json ``` Asks a live session to emit its background-subagent task snapshot. The snapshot arrives on the session's WS/SSE stream, not inline. #### Cancel a Background Task ``` hoody agent cancel-task -c --id "" \ --task-id "" \ -o json ``` Cancels one background subagent task. Handled at the server layer so it works mid-turn. #### Cancel All Background Tasks ``` hoody agent cancel-all-tasks -c --id "" -o json ``` Cancels all background subagent tasks on a live session. #### Request a Task Transcript ``` hoody agent request-transcript -c --id "" \ --task-id "" \ --after-seq 42 \ -o json ``` Asks a live session to emit a background task's transcript from an `after_seq` cursor. The transcript arrives on the session's WS/SSE stream. --- ### 5. Tools — Tool Catalogue and Execution Tools are the building blocks agents use to interact with systems. They include read-only tools (safe for planning) and gated tools (require confirmation for writes). #### List All Tool Schemas ``` hoody agent list-tools -c -o json ``` Lists the agent's built-in tool schemas (name, description, JSON-Schema input, `read_only` flag). Catalogue-wide and realm-independent. #### List Read-Only Tools ``` hoody agent list-read-only-tools -c -o json ``` Lists the read-only tools (safe for planning/sessionless runs). #### Get a Single Tool Schema ``` hoody agent get-tool -c --name "read_file" -o json ``` Returns the schema for a single built-in tool by name. #### List a Session's Effective Tool Set ``` hoody agent list-session-tools -c --id "" -o json ``` Returns the complete effective tool set for a LIVE session (config-enabled AND on PATH, gated by session's tool mode / agent allowlist / headless exclusions). #### List a Session's MCP Tools ``` hoody agent list-session-mcp -c --id "" -o json ``` Returns the MCP (`mcp__*`) tools available in a LIVE session. #### Run a Tool in a Live Session ``` hoody agent run-session-tool -c --id "" \ --name "read_file" \ --input '{"path": "/workspace/src/main.py"}' \ -o json ``` Runs a tool through the gated choke point on a LIVE session. #### Run a Tool Sessionlessly ``` hoody agent run-tool -c \ --name "read_file" \ --input '{"path": "/workspace/src/main.py"}' \ -o json ``` Runs a tool with NO open session. The gateway mints an ephemeral local session from scope headers. #### Run a Tool Asynchronously ``` hoody agent run-async-tool -c \ --name "search_code" \ --input '{"query": "authentication middleware"}' \ -o json ``` Returns `{job_id}` immediately. Poll with `hoody agent get-job` or `hoody agent get-job-result`. #### Run a Tool with Streaming ``` hoody agent stream-tool -c \ --name "read_file" \ --input '{"path": "/workspace/README.md"}' \ -o json ``` Streaming form over SSE: `start` frame, then `result`/`needs_confirmation`/`error` frame, then `end`. --- ### 6. Workflows — Definitions and Runs Workflows are multi-step agent orchestration definitions that can be dispatched onto live sessions. #### List Workflow Definitions ``` hoody agent list-workflows -c -o json ``` Lists workflow definitions visible to the requesting cwd/config_dir (name, summary, step briefs, system flag). #### Get a Workflow Definition ``` hoody agent get-workflow -c --name "code-review" -o json ``` Returns one workflow definition as JSON. #### Create or Replace a Workflow ``` hoody agent put-workflow -c --name "code-review" \ --definition '{"steps": [{"name": "analyze", "prompt": "Analyze the diff"}]}' \ -o json ``` Creates or replaces one workflow definition. The `{name}` path value is the workflow key. #### Delete a Workflow ``` hoody agent delete-workflow -c --name "code-review" -o json ``` Deletes one USER workflow definition. System workflows are refused. #### Hide a Workflow ``` hoody agent hide-workflow -c --name "legacy-workflow" -o json ``` Hides one workflow from the Workflows tab. This is the ONLY way to remove a SYSTEM workflow from view. #### Dispatch a Workflow Run ``` hoody agent run-session-workflow -c --id "" \ --workflow "code-review" \ -o json ``` Dispatches a workflow run onto a live session and returns `{job_id}`. #### Snapshot In-Flight and Recent Runs ``` hoody agent list-workflow-runs -c -o json ``` Returns a snapshot of in-flight and recently-finished workflow runs. Poll to track progress. #### Get a Specific Workflow Run ``` hoody agent get-workflow-run -c --run-id "" -o json ``` Returns a single workflow run row by run id. #### Cancel a Workflow Run ``` hoody agent cancel-workflow-run -c --run-id "" -o json ``` Cancels an in-flight workflow run. --- ### 7. Memory — Agent Memory System The memory system provides persistent, searchable, hybrid-recall memory for agent projects. It supports BM25 + vector + graph fusion search. #### List Memory Projects ``` hoody agent list-memory-projects -c -o json ``` Lists the memory projects. #### List Memory Items ``` hoody agent list-memory-items -c \ --project "my-project" \ --kind "fact" \ -o json ``` Lists memory records for a project with optional filters (`project`, `kind`, `type`, `query`). #### Get a Memory Item ``` hoody agent get-memory-item -c \ --id "" \ --project "my-project" \ -o json ``` Reads one memory record by id. #### Save a Memory Item ``` hoody agent save-memory-item -c \ --project "my-project" \ --kind "fact" \ --content "The authentication middleware uses JWT tokens with RS256 signing" \ -o json ``` Stores a new memory record. #### Edit a Memory Item ``` hoody agent edit-memory-item -c \ --id "" \ --content "Updated: Auth middleware uses JWT with ES256 signing" \ -o json ``` Patches a memory record by id. #### Delete a Memory Item ``` hoody agent delete-memory-item -c \ --id "" \ -o json ``` Deletes a memory record. This is the cross-project delete. #### Search Memory (Hybrid Recall) ``` hoody agent search-memory -c \ --project "my-project" \ --query "authentication patterns" \ -o json ``` Hybrid recall across a project: BM25 + vector + graph fusion. The query is privacy-stripped before tokenization/embedding. #### Read Memory Graph ``` hoody agent get-memory-graph -c \ --project "my-project" \ --limit 50 \ -o json ``` Returns a paginated page of a project's memory relation graph (nodes, edges, stats). #### Toggle Memory Capture ``` hoody agent set-memory-enabled -c --enabled true -o json ``` Flips the memory privacy switch—persists `features.memory` and flips the live store. #### Flush Memory Store ``` hoody agent flush-memory -c -o json ``` Forces the memory store durability barrier. #### Consolidate Memory ``` hoody agent consolidate-memory -c --project "my-project" -o json ``` Requests a consolidation pass for a project. **HUMAN-ONLY**: consolidation spends multi-LLM passes and evolves memory state irreversibly. --- ### 8. Skills — Local and Hub Skill Management Skills are installable capability modules that extend agent functionality. They can be sourced locally or from the remote skill hub. #### List Installed Skills ``` hoody agent list-skills -c -o json ``` Lists installed skills for the requesting cwd/config_dir, with their enabled/trust state. #### Create a New Local Skill ``` hoody agent create-skill -c \ --name "my-skill" \ --content "# My Skill\n\nDescription and instructions..." \ -o json ``` Creates a new local skill. #### Read a Skill's Source ``` hoody agent get-skill-source -c \ --root "/path/to/skills" \ --rel "my-skill" \ -o json ``` Returns a skill's source body. Identify by `root_dir` + `rel_dir` query params. #### Write a Skill's Source ``` hoody agent put-skill-source -c \ --root "/path/to/skills" \ --rel "my-skill" \ --content "# Updated Skill\n\nNew instructions..." \ -o json ``` Overwrites a skill's source body. #### Toggle a Skill ``` hoody agent toggle-skill -c \ --name "my-skill" \ --disabled false \ -o json ``` Toggles a skill's enabled state. Gates the effective skill name in the runtime registry. #### Set Skill Trust ``` hoody agent trust-skill -c \ --root "/path/to/skills" \ --rel "my-skill" \ --trusted true \ -o json ``` Sets a skill's trust state. Trust gates arbitrary code execution. #### Rename a Skill ``` hoody agent rename-skill -c \ --root "/path/to/skills" \ --rel "my-skill" \ --new-name "better-skill" \ -o json ``` Renames a skill. #### Delete a Skill ``` hoody agent delete-skill -c \ --root "/path/to/skills" \ --rel "my-skill" \ -o json ``` Deletes a skill. #### Search the Skill Hub ``` hoody agent search-hub -c --query "docker" -o json ``` Searches the remote skill hub. #### Preview a Hub Skill ``` hoody agent preview-hub -c --id "" -o json ``` Fetches a preview of a hub skill before install. #### Install a Hub Skill ``` hoody agent install-hub -c --id "" -o json ``` Installs a skill from the hub. This writes arbitrary skill code to disk. #### Scan for Importable Skills ``` hoody agent scan-import -c -o json ``` Scans well-known locations for importable skills. #### Apply a Skill Import ``` hoody agent apply-import -c --source "" -o json ``` Imports a discovered skill into the local store. #### Skill Hub Cache Stats ``` hoody agent get-hub-cache -c -o json ``` Returns the skill-hub fetch cache statistics. #### Clear Skill Hub Cache ``` hoody agent clear-hub-cache -c -o json ``` Clears the skill-hub fetch cache, including pins. --- ### 9. Todos — Autonomous Task Orchestration The todo system provides a master task list with LLM triage, proposals, orchestrator runs, and approval workflows. #### List Todos ``` hoody agent list-todos -c -o json ``` Lists master todos for the requesting cwd/config_dir. Filter via `--states`, `--tags`, `--query`, `--open-only`. #### File a New Todo ``` hoody agent create-todo -c \ --title "Refactor authentication module" \ --description "The current auth module needs to be updated to support OAuth2 PKCE flow" \ -o json ``` Files a new master todo. Deterministic triage (normalize, fingerprint-dedupe, defaults) runs server-side. #### Get a Todo ``` hoody agent get-todo -c --id "" -o json ``` Returns the full todo record including timeline and proposals. #### Update a Todo (CAS-guarded) ``` hoody agent update-todo -c --id "" \ --revision "" \ --priority "high" \ -o json ``` Applies a CAS-guarded field patch. A stale revision is rejected. #### Get the Todo Store Revision ``` hoody agent get-todo-revision -c -o json ``` Returns the current CAS revision token for optimistic concurrency. #### Archive a Todo ``` hoody agent archive-todo -c --id "" -o json ``` Archives a todo. #### Purge Archived Todos ``` hoody agent purge-todos -c -o json ``` Permanently and irreversibly removes archived todos. Tombstones are destroyed. #### Claim a Todo ``` hoody agent claim-todo -c --id "" -o json ``` Claims a todo for the caller. #### Release a Todo ``` hoody agent release-todo -c --id "" -o json ``` Releases a claimed todo. #### Run a Todo's Orchestrator ``` hoody agent run-todo -c --id "" -o json ``` Dispatches a background worker to autonomously work a todo. Returns `{job_id, session_id}`. The daemon treats reaching this RPC as the human approval itself. #### Post a Comment + Run Orchestrator Turn ``` hoody agent message-todo -c --id "" \ --message "Focus on the OAuth2 PKCE implementation first" \ -o json ``` Posts a comment AND kicks an orchestrator turn. Returns `{job_id}`. #### Post a Comment (No Turn) ``` hoody agent post-comment-todo -c --id "" \ --message "Updated priority based on sprint planning" \ -o json ``` Posts a comment onto a todo's timeline WITHOUT triggering an orchestrator turn. #### Approve a Proposal ``` hoody agent approve-proposal -c --id "" \ --proposal-id "" \ -o json ``` Approves a run proposal. Approval spawns a background worker session. #### Deny a Proposal ``` hoody agent deny-proposal -c --id "" \ --proposal-id "" \ -o json ``` Denies a run proposal. #### Cancel a Todo's Run ``` hoody agent cancel-run-todo -c --id "" -o json ``` Cancels an in-flight orchestrator run for a todo. #### Snooze a Todo ``` hoody agent snooze-todo -c --id "" \ --until "2025-12-01T00:00:00Z" \ -o json ``` Snoozes a todo until a wake time. #### Run LLM Triage ``` hoody agent triage-todos -c -o json ``` Kicks an LLM triage pass over the inbox. Returns `{job_id}`. This is a J-class op that spends model budget on an autonomous LLM run. --- ### 10. Providers — LLM Provider Management and Authentication Providers are catalogued LLM services (OpenAI, Anthropic, Google, etc.) with their models, auth methods, and credential pools. #### List Providers ``` hoody agent list-providers -o json ``` Lists every catalogued LLM provider. **Daemon-global** — no realm or container needed. #### Get a Provider ``` hoody agent get-provider --id "anthropic" -o json ``` Returns one provider's metadata plus its full catalogued model list. #### Get a Provider's Auth Status ``` hoody agent get-provider-auth --id "anthropic" -o json ``` Reports a provider's stored-credential state—API key stored, OAuth state, default method, passwordless flag. #### Set a Provider API Key ``` hoody agent set-provider-api-key --id "anthropic" \ --api-key "sk-ant-..." \ -o json ``` Stores a provider's API key in the 0600 atomic `~/.hoody/.env` keychainless store. #### Delete a Provider API Key ``` hoody agent delete-provider-api-key --id "anthropic" -o json ``` Removes a provider's stored API key and its default-method marker. Idempotent. #### Set Default Credential Method ``` hoody agent set-provider-default --id "anthropic" \ --method "api_key" \ -o json ``` Sets the effective default credential method. Validates against provider capabilities and stored credentials. #### Start a Provider OAuth Login ``` hoody agent start-provider-o-auth --id "anthropic" -o json ``` Begins an interactive OAuth login. Returns `{success, job_id, verification_uri, user_code?}`. #### Poll a Provider OAuth Login ``` hoody agent poll-provider-o-auth --id "anthropic" --job "" -o json ``` Polls an in-flight OAuth login job. Reports `state: "pending"` until authorized, then `state: "complete"`. #### Submit Provider OAuth Code ``` hoody agent submit-provider-o-auth-code --id "anthropic" --job "" \ --code "" \ -o json ``` Supplies the authorization code for manual-paste / PKCE flows. Idempotent-safe. #### Logout Provider OAuth ``` hoody agent logout-provider-o-auth --id "anthropic" -o json ``` Removes a provider's stored OAuth credentials. Idempotent. #### List Provider OAuth Account Pool ``` hoody agent list-provider-accounts --id "anthropic" -o json ``` Lists the secret-free OAuth account pool (key, label, active flag, cooldown). #### Add an OAuth Account ``` hoody agent add-provider-account --id "anthropic" -o json ``` Begins an OAuth login that ADDS to the provider's account pool. Returns `{job_id}`. #### Remove a Pooled Account ``` hoody agent remove-provider-account --id "anthropic" --key "" -o json ``` Drops one pooled OAuth account. #### Set a Pooled Account Active ``` hoody agent set-provider-account-active --id "anthropic" --key "" -o json ``` Makes one pooled OAuth account active. --- ### 11. Models — LLM Model Catalogue #### List Models ``` hoody agent list-models -c -o json ``` Lists the MERGED model catalogue: every catalogued provider model (spec, display name, context window, output limit, reasoning flag, prices) AND every selectable fusion composite. #### Get a Model by Spec ``` hoody agent get-model -c --spec "anthropic/claude-opus-4-8" -o json ``` Returns one catalogued model by its full spec, or a fusion composite by `fusion/` spec. --- ### 12. Settings — Configuration and Fusion Composites #### Get Settings ``` hoody agent get-settings -c -o json ``` Returns the effective merged settings (home → project → settings.local.json) plus the home-layer object. #### Patch Settings ``` hoody agent patch-settings -c \ --patch '{"features": {"memory": true}}' \ -o json ``` Applies a SHALLOW top-level merge into `~/.hoody/settings.json`. A nil value deletes a key. **Top-level only**: sending `{"features":{}}` REPLACES the whole features object. #### List Fusion Composites ``` hoody agent list-fusion -c -o json ``` Lists the persisted model-fusion composites. Pass `--include-invalid` to also receive entries that failed validation. #### Create or Update a Fusion Composite ``` hoody agent upsert-fusion -c --slug "fast-and-smart" \ --spec '{"name": "fast-and-smart", "method": "router", "members": ["anthropic/claude-sonnet-4-20250514", "anthropic/claude-opus-4-8"]}' \ -o json ``` Creates or updates a model-fusion composite keyed by slug. #### Delete a Fusion Composite ``` hoody agent delete-fusion -c --slug "fast-and-smart" -o json ``` Removes a model-fusion composite by slug. --- ### 13. ACP — BYOA Agent Control Plane ACP provides the Bring-Your-Own-Agent backend status and per-agent secret management. #### Get ACP Backend Status ``` hoody agent get-acp-status -c -o json ``` Reports the BYOA delegated-session backend availability (codex/claude/gemini/opencode)—enabled flag, on-PATH status, trust posture. Returns a fixed status object. #### Set an ACP Secret ``` hoody agent set-acp-secret -c \ --agent "codex" \ --key "OPENAI_API_KEY" \ --value "sk-..." \ -o json ``` Stores (or clears) one per-backend env value for a BYOA ACP agent in `~/.hoody/acp-secrets.env` (atomic temp+rename, flock). --- ### 14. GitHub — Repository Integration GitHub integration provides authentication, repository management, branch operations, and pull request workflows. All GitHub operations are **cwd-scoped** (not realm-scoped). #### Start GitHub Login (Device Flow) ``` hoody agent login-github -c -o json ``` Begins a GitHub device-flow login. Returns `{device_code, user_code, verification_uri, interval, expires_in}`. #### Poll GitHub Login ``` hoody agent login-poll-github -c \ --device-code "" \ -o json ``` Polls an in-flight device-flow login. Blocks until the user authorizes. #### Check GitHub Auth Status ``` hoody agent auth-status-github -c -o json ``` Reports the GitHub authentication state from the process-wide singleton account store. Token only in env; never returned. #### List GitHub Repos ``` hoody agent repos-github -c -o json ``` Lists known/configured repos. #### Clone a Repository ``` hoody agent clone-github -c --repo "owner/repo-name" -o json ``` Clones a GitHub repository through the hardened argv builder. #### List Branches ``` hoody agent branches-github -c -o json ``` Lists branches for the requesting cwd's repo. #### Get Working-Tree Status ``` hoody agent status-github -c -o json ``` Returns the git working-tree status for the requesting cwd. #### Stage All and Commit ``` hoody agent commit-github -c \ --message "feat: add OAuth2 PKCE support" \ -o json ``` Stages all changes and commits. Destructive operation. #### Open a Pull Request ``` hoody agent pull-request-github -c \ --title "Add OAuth2 PKCE support" \ --body "Implements PKCE flow for improved security" \ -o json ``` Opens a pull request through the hardened argv builder. Destructive operation. #### Sync (Fetch → Pull → Push) ``` hoody agent sync-github -c -o json ``` Runs fetch → pull → push as one logical sync, stopping at the FIRST non-ok step. Use `--direction pull-only` to only pull. --- ### 15. Hooks — Lifecycle Hook Management Hooks are session-scoped lifecycle event handlers that execute arbitrary commands. All hook mutations require a two-step write nonce for safety. #### List Hooks ``` hoody agent list-hooks -c --id "" -o json ``` Lists lifecycle hooks for a live session. Returns `{live, session}` summaries with drift status. #### Begin Hook Write (Get Nonce) ``` hoody agent begin-write-hooks -c --id "" \ --op "upsert" \ -o json ``` Issues the two-step write nonce required before every guarded hook mutation. #### Create or Update a Hook ``` hoody agent upsert-hook -c --id "" \ --nonce "" \ --name "post-prompt" \ --event "turn_complete" \ --command "echo 'Turn completed'" \ -o json ``` Creates or updates a hook. Requires the begin-write nonce and a live session_id. #### Toggle a Hook ``` hoody agent begin-write-hooks -c --id "" --op "toggle" -o json hoody agent toggle-hook -c --id "" \ --nonce "" \ --name "post-prompt" \ -o json ``` Toggles a single hook's enabled state. Requires the begin-write nonce. #### Disable All Hooks ``` hoody agent begin-write-hooks -c --id "" --op "set_disabled" -o json hoody agent disable-all-hooks -c --id "" \ --nonce "" \ --disabled true \ -o json ``` Disables (or re-enables) all hooks at once. #### Delete a Hook ``` hoody agent begin-write-hooks -c --id "" --op "delete" -o json hoody agent delete-hook -c --id "" \ --nonce "" \ --name "post-prompt" \ -o json ``` Deletes a hook. #### Reload Hooks from Disk ``` hoody agent reload-hooks -c --id "" -o json ``` Reloads the hook configuration from disk. #### Test-Fire a Hook ``` hoody agent test-hook -c --id "" \ --name "post-prompt" \ -o json ``` Test-fires a hook command. This EXECUTES an arbitrary command now. #### Acknowledge Hook Trust ``` hoody agent ack-trust-hooks -c --id "" -o json ``` Acknowledges the hook-trust prompt. --- ### 16. Jobs — Async Job Management Jobs track the status and results of asynchronous operations (dispatches, workflow runs, long tool calls). #### Get Job Status ``` hoody agent get-job -c --id "" -o json ``` Returns the status of an async job. `run_id` is null during the brief dispatch window for workflow runs. #### Get Job Result ``` hoody agent get-job-result -c --id "" -o json ``` Returns the result of a completed job, or the running status. #### Cancel or Delete a Job ``` hoody agent delete-job -c --id "" -o json ``` Cancels a PENDING/RUNNING job, or deletes a TERMINAL job's historical record. --- ### 17. Logs — Logging and Monitoring #### Query Logs ``` hoody agent query-logs -c \ --source "agent" \ --level "error" \ --limit 50 \ -o json ``` Queries the active-supervisor log stream. Supports filters: `source`, `level`, `host`, `since`, `until`. #### Read a Log Entry ``` hoody agent read-log-entry -c --ref "" -o json ``` Reads one log entry by ref. Always redacted. Active-only. #### List Log Sources ``` hoody agent logs-sources -c -o json ``` Lists available log sources/facets. #### Get Log Statistics ``` hoody agent logs-stats -c -o json ``` Returns log volume/level statistics. #### Stream Logs (SSE) ``` hoody agent stream-logs -c --since "" -o json ``` Tails the active-supervisor log stream over Server-Sent Events. --- ### 18. Headless — One-Shot Agent Runs #### Create a Headless Run ``` hoody agent create-headless-run -c \ --prompt "Explain the architecture of this project" \ --format "json" \ -o json ``` Drives the FULL agent loop once over an ephemeral gateway-owned session. The default (json/text) form is ASYNC: returns 202 `{job_id}`. Poll `GET /jobs/{id}` for result. Streaming returns SSE directly. --- ### 19. Discovery — Container and Realm Discovery #### List Containers ``` hoody agent list-containers -c -o json ``` Lists containers in a realm so a caller can pick a bind target. Use `--realm ` to select realm. #### List Realms ``` hoody agent list-realms -c -o json ``` Lists the realms visible to the token, with active/blocked flags. --- ### 20. System — Health, Metrics, Documentation, and OpenAPI #### Health Check ``` hoody agent health-check -c -o json ``` Returns the kit-wide 9-field health payload. The only unauthenticated route; always returns HTTP 200. #### Prometheus Metrics ``` hoody agent metrics -c -o json ``` Returns Prometheus exposition of the `hoody_agent_*` series. #### API Documentation UI ``` hoody agent docs -c ``` Opens the Swagger/Redoc UI. Auth-gated. #### OpenAPI Spec (JSON) ``` hoody agent openapi-json -c -o json ``` Returns the live-generated OpenAPI 3.1 document with Hoody `x-*` extensions. #### OpenAPI Spec (YAML) ``` hoody agent openapi-yaml -c ``` Returns the live-generated OpenAPI 3.1 document in YAML. --- ### 21. Statistics and Usage — Cross-Session Analytics #### Cross-Session Statistics ``` hoody agent get-statistics -c --scope "all" -o json ``` Returns the cross-session usage aggregate. `--scope` accepts `cwd` (default) or `all`. #### Usage Rollup by Account ``` hoody agent usage-by-account -o json ``` Per-(provider, account) usage rollup. **Daemon-global**. Use `--since ` for time range. #### Usage Rollup by Model ``` hoody agent usage-by-model -o json ``` Per-(model, provider) usage rollup (calls, success rate, cost, latency). **Daemon-global**. Use `--since `. --- ## Advanced Operations ### Full Session Lifecycle Workflow This workflow demonstrates creating a session, dispatching prompts, managing turns, and cleaning up. ``` # Step 1: Discover available containers and realms hoody agent list-realms -o json hoody agent list-containers -c --realm "" -o json # Step 2: Create a new session bound to a container hoody agent create-session -c --agent "default" -o json # Store the session ID from response # Step 3: Dispatch a prompt and stream the response hoody agent prompt-stream -c --id "" \ --message "Analyze the security posture of this codebase" -o json # Step 4: Dispatch a synchronous prompt (blocks until done) hoody agent prompt-sync -c --id "" \ --message "Generate a security checklist" -o json # Step 5: Switch the model mid-session hoody agent set-session-model -c --id "" \ --model "anthropic/claude-sonnet-4-20250514" -o json # Step 6: Adjust reasoning effort hoody agent set-effort -c --id "" \ --effort "high" -o json # Step 7: Run a tool within the session hoody agent run-session-tool -c --id "" \ --name "search_code" \ --input '{"query": "SQL injection vulnerabilities"}' -o json # Step 8: Trim history to save context hoody agent trim -c --id "" \ --turn-index 3 -o json # Step 9: Close and delete the session hoody agent close-session -c --id "" -o json hoody agent delete-session -c --id "" --hard -o json ``` ### GitHub Development Workflow End-to-end code modification and PR creation through the agent: ``` # Step 1: Authenticate with GitHub hoody agent login-github -c -o json # Note the user_code and verification_uri # Step 2: Poll until authorized hoody agent login-poll-github -c \ --device-code "" -o json # Step 3: Verify auth hoody agent auth-status-github -c -o json # Step 4: Clone the target repository hoody agent clone-github -c \ --repo "myorg/myproject" -o json # Step 5: Check working tree status hoody agent status-github -c -o json # Step 6: Create a session and make changes hoody agent create-session -c --agent "default" -o json hoody agent prompt-sync -c --id "" \ --message "Add input validation to the user registration endpoint" -o json # Step 7: Commit the changes hoody agent commit-github -c \ --message "feat: add input validation to registration" -o json # Step 8: Open a pull request hoody agent pull-request-github -c \ --title "Add input validation to registration" \ --body "Validates email format, password strength, and username constraints" \ -o json # Step 9: Sync with remote hoody agent sync-github -c -o json ``` ### Provider Authentication Setup Configure multiple LLM providers with different auth methods: ``` # Step 1: List available providers hoody agent list-providers -o json # Step 2: Set an API key for Anthropic hoody agent set-provider-api-key --id "anthropic" \ --api-key "sk-ant-api03-..." -o json # Step 3: Verify auth status hoody agent get-provider-auth --id "anthropic" -o json # Step 4: Set default credential method hoody agent set-provider-default --id "anthropic" --method "api_key" -o json # Step 5: Start OAuth flow for OpenAI hoody agent start-provider-o-auth --id "openai" -o json # Step 6: Poll for completion hoody agent poll-provider-o-auth --id "openai" --job "" -o json # Step 7: List models to verify availability hoody agent list-models -c -o json # Step 8: Set up ACP secret for BYOA hoody agent set-acp-secret -c \ --agent "codex" \ --key "OPENAI_API_KEY" \ --value "sk-..." -o json # Step 9: Verify ACP status hoody agent get-acp-status -c -o json ``` ### Memory-Driven Agent Workflow Build persistent memory and use it across sessions: ``` # Step 1: Enable memory hoody agent set-memory-enabled -c --enabled true -o json # Step 2: Save key facts hoody agent save-memory-item -c \ --project "my-project" \ --kind "architecture" \ --content "Microservice architecture with 5 services: auth, api, worker, scheduler, gateway" \ -o json hoody agent save-memory-item -c \ --project "my-project" \ --kind "convention" \ --content "All services use Go with gin framework and follow the repository pattern" \ -o json # Step 3: Search memory hoody agent search-memory -c \ --project "my-project" \ --query "what framework do we use" -o json # Step 4: View the memory graph hoody agent get-memory-graph -c \ --project "my-project" \ --limit 25 -o json # Step 5: Force flush for durability hoody agent flush-memory -c -o json # Step 6: Trigger consolidation (human approval required) hoody agent consolidate-memory -c \ --project "my-project" -o json ``` ### Skill Hub Installation Workflow Discover, preview, and install skills from the hub: ``` # Step 1: Search the skill hub hoody agent search-hub -c --query "docker" -o json # Step 2: Preview a skill before installing hoody agent preview-hub -c --id "" -o json # Step 3: Install the skill hoody agent install-hub -c --id "" -o json # Step 4: List installed skills hoody agent list-skills -c -o json # Step 5: Set trust state hoody agent trust-skill -c \ --root "/path/to/skill" \ --rel "docker-skill" \ --trusted true -o json # Step 6: Enable the skill hoody agent toggle-skill -c \ --name "docker-skill" \ --disabled false -o json # Step 7: Scan for local importable skills hoody agent scan-import -c -o json # Step 8: Check hub cache stats hoody agent get-hub-cache -c -o json ``` ### Todo Orchestration Workflow File, triage, and autonomously execute tasks: ``` # Step 1: File a new todo hoody agent create-todo -c \ --title "Upgrade database schema for multi-tenancy" \ --description "Add tenant_id column to all tables and update queries" \ -o json # Step 2: List all todos hoody agent list-todos -c -o json # Step 3: Run LLM triage to prioritize hoody agent triage-todos -c -o json # Step 4: Claim the todo hoody agent claim-todo -c --id "" -o json # Step 5: Run the orchestrator autonomously hoody agent run-todo -c --id "" -o json # Step 6: Monitor via the todo's job hoody agent get-job -c --id "" -o json # Step 7: Post follow-up guidance hoody agent message-todo -c --id "" \ --message "Focus on the users and orders tables first" -o json # Step 8: Approve any proposals hoody agent approve-proposal -c --id "" \ --proposal-id "" -o json # Step 9: Archive when complete hoody agent archive-todo -c --id "" -o json ``` ### Workflow Definition and Execution Define, dispatch, and monitor multi-step workflows: ``` # Step 1: List existing workflows hoody agent list-workflows -c -o json # Step 2: Create a custom workflow hoody agent put-workflow -c --name "security-audit" \ --definition '{"summary":"Full security audit","steps":[{"name":"scan","prompt":"Scan for vulnerabilities"},{"name":"fix","prompt":"Propose fixes"}]}' \ -o json # Step 3: Open a session for execution hoody agent create-session -c --agent "default" -o json # Step 4: Dispatch the workflow hoody agent run-session-workflow -c --id "" \ --workflow "security-audit" -o json # Step 5: Snapshot all workflow runs hoody agent list-workflow-runs -c -o json # Step 6: Get a specific run's status hoody agent get-workflow-run -c --run-id "" -o json # Step 7: Send feedback during execution hoody agent post-workflow-message -c --id "" \ --message "Skip the frontend, focus on backend only" -o json # Step 8: Cancel if needed hoody agent cancel-workflow-run -c --run-id "" -o json # Step 9: Hide a deprecated system workflow hoody agent hide-workflow -c --name "legacy-audit" -o json ``` ### Error Recovery Patterns #### Recovering from Stale Session ``` # If session is unresponsive, check its status hoody agent get-session -c --id "" -o json # Cancel the active turn if stuck hoody agent cancel-turn -c --id "" -o json # If session is dead, close and recreate hoody agent close-session -c --id "" -o json hoody agent create-session -c --agent "default" -o json ``` #### Recovering from Failed Job ``` # Check job status hoody agent get-job -c --id "" -o json # Get the result if terminal hoody agent get-job-result -c --id "" -o json # Cancel if stuck in pending/running hoody agent delete-job -c --id "" -o json ``` #### Recovering from Stale CAS Revision ``` # Get the current todo revision hoody agent get-todo-revision -c -o json # Re-read the todo to get fresh revision hoody agent get-todo -c --id "" -o json # Retry the update with fresh revision hoody agent update-todo -c --id "" \ --revision "" \ --priority "critical" -o json ``` --- ## Quick Reference ### Endpoint Group Summary | Group | Scope | Count | CLI Subgroup | |-------|-------|-------|-------------| | **ACP** | Container | 2 | `get-acp-status`, `set-acp-secret` | | **Agents** | Realm | 12 | `list`, `create`, `delete`, `copy`, `set-model`, `rename`, `reset-to-shipped`, `get-source`, `put-source`, `set-tools`, `toggle-tool`, `set-turns` | | **Containers** | Global | 1 | `list-containers` | | **Docs** | Container | 1 | `docs` | | **GitHub** | cwd | 10 | `login-github`, `login-poll-github`, `auth-status-github`, `branches-github`, `clone-github`, `commit-github`, `pull-request-github`, `repos-github`, `status-github`, `sync-github` | | **Headless** | Container | 1 | `create-headless-run` | | **Health** | Global | 1 | `health-check` | | **Hooks** | Session | 8 | `list-hooks`, `upsert-hook`, `delete-hook`, `begin-write-hooks`, `disable-all-hooks`, `reload-hooks`, `test-hook`, `toggle-hook`, `ack-trust-hooks` | | **Jobs** | Container | 3 | `get-job`, `delete-job`, `get-job-result` | | **Logs** | Container | 5 | `query-logs`, `read-log-entry`, `logs-sources`, `logs-stats`, `stream-logs` | | **Memory** | Container | 10 | `list-memory-projects`, `list-memory-items`, `get-memory-item`, `save-memory-item`, `edit-memory-item`, `delete-memory-item`, `search-memory`, `get-memory-graph`, `set-memory-enabled`, `flush-memory`, `consolidate-memory` | | **Metrics** | Container | 1 | `metrics` | | **Models** | Container | 2 | `list-models`, `get-model` | | **OpenAPI** | Container | 2 | `openapi-json`, `openapi-yaml` | | **Providers** | Global | 14 | `list-providers`, `get-provider`, `get-provider-auth`, `list-provider-accounts`, `add-provider-account`, `remove-provider-account`, `set-provider-account-active`, `set-provider-api-key`, `delete-provider-api-key`, `set-provider-default`, `start-provider-o-auth`, `poll-provider-o-auth`, `submit-provider-o-auth-code`, `logout-provider-o-auth` | | **Realms** | Global | 1 | `list-realms` | | **Sessions** | Realm | 27 | `list-sessions`, `create-session`, `get-session`, `delete-session`, `list-cwds`, `set-chat-agent`, `answer-question`, `answer-assist`, `set-auto-reply`, `set-auto-reply-writes`, `cancel-turn`, `close-session`, `confirm-gate`, `set-effort`, `set-hoody-env`, `post-message`, `set-session-model`, `prompt-stream`, `prompt-sync`, `replay`, `stream`, `trim`, `set-verbosity`, `post-workflow-message` | | **Loops** | Session | 5 | `list-loops`, `create-loop`, `update-loop`, `delete-loop`, `run-now-loop` | | **Tasks** | Session | 4 | `list-tasks`, `cancel-task`, `cancel-all-tasks`, `request-transcript` | | **Settings** | Container | 5 | `get-settings`, `patch-settings`, `list-fusion`, `upsert-fusion`, `delete-fusion` | | **Skills** | Realm | 15 | `list-skills`, `create-skill`, `delete-skill`, `get-skill-source`, `put-skill-source`, `toggle-skill`, `trust-skill`, `rename-skill`, `search-hub`, `preview-hub`, `install-hub`, `scan-import`, `apply-import`, `get-hub-cache`, `clear-hub-cache` | | **Statistics** | Realm | 1 | `get-statistics` | | **Todos** | Realm | 14 | `list-todos`, `create-todo`, `get-todo`, `update-todo`, `archive-todo`, `purge-todos`, `get-todo-revision`, `triage-todos`, `claim-todo`, `release-todo`, `run-todo`, `message-todo`, `post-comment-todo`, `approve-proposal`, `deny-proposal`, `cancel-run-todo`, `snooze-todo` | | **Tools** | Container | 8 | `list-tools`, `list-read-only-tools`, `get-tool`, `list-session-tools`, `list-session-mcp`, `run-session-tool`, `run-tool`, `run-async-tool`, `stream-tool` | | **Usage** | Global | 2 | `usage-by-account`, `usage-by-model` | | **Workflows** | Realm | 8 | `list-workflows`, `get-workflow`, `put-workflow`, `delete-workflow`, `hide-workflow`, `run-session-workflow`, `list-workflow-runs`, `get-workflow-run`, `cancel-workflow-run` | ### Essential Parameters Reference | Parameter | Type | Used By | Description | |-----------|------|---------|-------------| | `--id` | string | sessions, todos, jobs, hooks, loops, tasks | Resource identifier | | `--name` | string | agents, skills, workflows, hooks, tools | Resource name | | `--agent` | string | sessions, ACP | Agent definition name | | `--model` | string | agents, sessions | LLM model spec (e.g., `anthropic/claude-sonnet-4-20250514`) | | `--project` | string | memory, todos | Project identifier | | `--realm` | string | containers | Realm identifier | | `--spec` | string | models | Full model spec | | `--id` (provider) | string | providers | Provider identifier (e.g., `anthropic`, `openai`) | | `--revision` | string | todos | CAS revision token | | `--nonce` | string | hooks | Two-step write nonce | | `--session-id` | string | hooks, loops, tasks | Live session identifier | | `--job-id` / `--job` | string | providers, jobs | Async job identifier | | `--run-id` | string | workflows | Workflow run identifier | | `--loop-id` | string | loops | Loop identifier | | `--task-id` / `--tid` | string | tasks | Background task identifier | | `--proposal-id` / `--pid` | string | todos | Proposal identifier | | `--root` / `--rel` | string | skills | Skill location identifiers | | `--scope` | string | statistics | `cwd` or `all` | | `--since` | int | usage, logs | Unix timestamp for time-range filtering | | `--limit` | int | logs, memory, models | Result set cap | ### Response Format Notes All CLI responses support output formatting via `-o`: | Flag | Format | Use Case | |------|--------|----------| | `-o json` | JSON (compact) | Machine-readable, scripting | | `-o pretty` | JSON (pretty-printed) | Human-readable debugging | | `-o table` | Table (default) | Interactive CLI use | | `-o wide` | Wide table | More columns visible | | `-o yaml` | YAML | Configuration workflows | | `-o raw` | Raw response | Direct output | | `-o ndjson` | Newline-delimited JSON | Streaming/log processing | ### Safety Gates Summary | Operation | Gate Type | Mechanism | |-----------|-----------|-----------| | Hook mutations | Two-step nonce | `begin-write-hooks` → pass nonce to mutation | | Memory consolidation | Human-only | Multi-LLM pass, irreversible state evolution | | Todo `purge` | Unrecoverable | Destroys tombstones permanently | | Todo `run` | Implicit approval | Reaching RPC counts as human approval | | Tool execution | Gated choke point | Write tools require confirmation in interactive mode | | Skill trust | Trust flag | Gates arbitrary code execution | | Hook trust | Trust prompt | Requires explicit acknowledgment | | Workflow delete | System protection | System workflows cannot be deleted |