Agent reference
Section titled “Agent reference”Lookup tables for the Hoody Agent. Every route, field and response is in the Agent API reference.
How the agent is built
Section titled “How the agent is built”| Part | Detail |
|---|---|
hoody-agent-d | The daemon, written in Go. It owns model streaming, tool execution, sessions, workflows and memory. |
hoody-agent | The client: a mouse-driven TUI built on Bubble Tea, talking to the daemon over a Unix socket. It opens in a browser tab through xterm.js at the computer’s agent-1 URL; the browser adds clipboard images and web panes. |
| Browser URL | Hoody Terminal runs the agent binary as the session’s process, with no shell underneath. Instance indices start at 1: agent-1 is your first agent. Web terminal options such as ?fontSize= and ?rendererType= work too; see text draws wrongly. |
| API | A generated OpenAPI 3.1 description, browsable in the Agent API reference; hoody-agent-d --generate-openapi writes it offline. GET /api/v1/agent/version marks each feature supported (this build knows it) and available (its required routes, events and runtime conditions are ready). |
| Tab group | Holds |
|---|---|
| AGENT | Conversations, named agent profiles and the MCP servers they reach, skills, multi-step pipelines, a work inbox |
| FLEET | Computers’ live terminals, displays and files, published exec scripts, custom domains, and your account: servers, rentals, wallet, API keys |
| SYSTEM | Providers and credentials, encrypted secrets, persistent memory, logs |
| Feature | Detail |
|---|---|
| Mouse | Tabs, rows, headers and chips click, tables sort by header, pane dividers drag to resize, file paths open a syntax-highlighted viewer, and URLs are links. |
| Chat panes | Each pane scrolls on its own and flags when it needs you. |
| Multi-attach | A client that joins mid-turn gets the full view plus the turn in progress replayed. |
| Clipboard images | Ctrl+V in the composer (right-click, then Paste, in the browser); the model sees the image. |
| Paste collapse | A long paste folds into a [Pasted text #N] chip you can click to edit; the model gets the full text. |
| Web panes | In the browser, an “open a URL” pane shows a real web page clipped to the pane; in a plain terminal, a placeholder. |
| Attention | A snackbar opens straight to a background session’s waiting decision. |
| FLEET | Discover computers, manage their files, author and run exec scripts, supervise long-running programs, schedule cron jobs, send notifications, and drive several live terminals in a grid. Fleet tools exist only when the platform is reachable, so a session without it pays none of their prompt cost. |
| Vault | Realm-scoped secrets. With encryption on, the TUI encrypts the entry with AES-256-GCM and the daemon sees only its envelope; with encryption off it passes through the daemon as plaintext. |
Models and providers
Section titled “Models and providers”| Topic | Detail |
|---|---|
| Hoody AI | The default, hoody-ai/hoody-free, needs no key inside a Hoody computer and remains the default until you choose another model. |
| Catalogue | 100+ providers ship in the binary; GET /api/v1/agent/providers lists them. Credentials come from the environment or the agent’s credential file: /hoody/storage/hoody-agent/.env inside a Hoody computer, normally ~/.hoody/.env elsewhere. |
| API keys | PUT /api/v1/agent/providers/{id}/auth/api-key with {"api_key": "..."}. GET /api/v1/agent/providers/{id}/auth shows whether one is stored, as a redacted preview. |
| Session model | POST /api/v1/agent/sessions with {"model": "..."} sets it for that session only. PATCH /api/v1/agent/sessions/{id}/model switches a live one; for a native session its default scope: "agent" also updates the agent profile that later sessions use. persisted says whether that profile write worked; the live switch applies either way. Send {"model": "...", "scope": "session"} to change only this session. Claude Code model switches are session-only. |
| Agent profile | PATCH /api/v1/agent/agents/{name}/model with {"model": "..."} pins a profile. |
| OAuth pools | Pool several OAuth accounts per provider; the agent rotates as each hits its limit. |
| Fusion | An engine in the daemon votes, synthesizes or debates across several models. |
| Token use | Phase instructions arrive as user messages, so moving from exploring to planning keeps the prompt cache. A minified file view strips whitespace the model does not need, where the language supports it. |
Claude Code sessions
Section titled “Claude Code sessions”| Rule | Detail |
|---|---|
| Claude Pro or Max | Hoody has no Anthropic OAuth flow. It delegates the session to Claude Code: the separately installed claude CLI reasons on its own login, and Hoody runs its own tools, so the session keeps the same tools, files and confirmations. |
| Other CLIs | Claude Code is the only agent a whole session can be delegated to. Codex, Gemini and OpenCode are one-shot tools (run_codex, run_gemini, run_opencode) when installed and enabled. |
| Its subagents | Claude Code’s own subagents are disabled under Hoody. Use Hoody’s spawn_agent tool instead when it is enabled for the session. Hoody’s own background subagents and orchestrator mode are unaffected. |
| Hoody subagents | A delegated session can use spawn_agent, task_output and list_tasks when those tools are on for the session. tools.delegated_subagents is retired and has no effect. |
Custom providers
Section titled “Custom providers”| Field or rule | Detail |
|---|---|
| Required | id, base_url, models. Every field is in the models API. |
id | 1 to 40 lowercase letters, digits or inner hyphens; cannot change later. Models are <id>/<model>, and model_prefix, if sent, must equal id. |
base_url | The part before /chat/completions, /responses or /v1/messages: an https URL with no user name, password, query or fragment, at a public address. |
wire_format, auth_scheme | chat_completions (default) or responses with bearer; messages with x-api-key. |
headers | Static headers on every call, chat_completions only. Credential headers such as Authorization are refused. |
| Models | context_window and output_limit in tokens (0 or omitted means unknown), and reasoning for a reasoning-capable model. Automatic compaction is off while the effective context window is unknown; an unknown output_limit does not turn it off. |
| Takes effect | New sessions and model switches see it, and an open session on one of its models picks it up before its next turn. |
| Retry | With an Idempotency-Key, a retry with the same key and body answers 201 with the provider the first try created. |
| Edit | PATCH /api/v1/agent/providers/{id} changes only the members you send; models and headers replace the whole list and map. |
| Remove | DELETE /api/v1/agent/providers/{id} deletes the provider and its stored key; api_key_removed says whether a stored key was removed, and api_key is removed, none or kept_shared (a key another provider may read stays). A mid-turn session finishes that turn. Then a session on one of its models fails its next prompt with session_unconfigured until you switch it with PATCH /api/v1/agent/sessions/{id}/model, and an agent profile naming one fails the same way until changed. |
Hoody files and tools
Section titled “Hoody files and tools”| Item | Detail |
|---|---|
| Agents | Swap the active agent mid-session. |
| Skills | Drop a SKILL.md into .hoody/skills/<name>/ and live sessions pick it up. |
| Workflows | A step marked read_only limits the step and every subagent it spawns to read-only tools. Codebase Map surveys an unfamiliar repository in one click; its second pass fact-checks the draft against the code. |
| TODOs | File items, let an LLM pass sort them, and dispatch any item as a background orchestrator run. |
| Background subagents | The parent is notified on completion; each has a live transcript. |
| Orchestrator mode | A delegation-first persona with no file or shell tools of its own. A change counts as done only after an independent reviewer subagent verifies it. |
| Built-in tools | File and shell tools, web fetch, model-routed web search, image generation, grep and glob, tree-sitter code scanning with optional per-language LSP, persistent memory with hybrid recall, GitHub and MCP servers. |
GitHub
Section titled “GitHub”| Topic | Detail |
|---|---|
| Device sign-in | POST /api/v1/agent/github/auth/login with no body returns device_code, user_code, verification_uri, interval and expires_in; POST /api/v1/agent/github/auth/login/poll with the device_code finishes the link. |
| Access token | A token in the login body is validated against GitHub’s /user endpoint and its account stored, with no browser step. With host for GitHub Enterprise Server, the host is checked first, so a token only goes to a public address. |
| Several accounts | GET /api/v1/agent/github/auth/status lists them (accounts[].key is <host>/<login>); POST /api/v1/agent/github/auth/active picks one for later operations; POST /api/v1/agent/github/auth/logout removes one. Accounts belong to the realm the request arrives in. The TUI’s account manager does the same, from the command palette, Settings or the splash screen’s repository picker. |
Git panel
Section titled “Git panel”| Tab | Shows and does |
|---|---|
| Status | Branches with the checked-out one marked and their tracking refs. Switch, commit, create or delete a branch, sync, stash and pop, diff and log. |
| Worktrees | Add and remove worktrees. |
| PRs | List, open, check out and merge pull requests, and follow their checks. |
| Issues | List and open issues. |
The status bar chip shows the branch, ahead and behind counts against its upstream, and dirty files, or a clean marker; detached, rebasing and merging states replace the branch name. Each cue pairs a glyph, a count and text, readable without colour. POST /api/v1/agent/github/commit/suggest-message (or the TUI) drafts a commit message: one tool-free model call that sends the pending diff to the selected model, using a throwaway git index so your real index is untouched.
GitHub over HTTP
Section titled “GitHub over HTTP”Every operation is under /api/v1/agent/github/; the GitHub API reference lists each one.
| Route or header | Detail |
|---|---|
clone | repo is owner/name or an HTTPS GitHub URL, resolved against the active account’s host; a URL on another host is refused. |
sync | Fetch, pull, then push, stopping at the first failure, so a push never lands on a half-synced tree. direction makes it pull-only or push-only. |
X-Hoody-Cwd, X-Hoody-Computer | The working directory, and a remote computer to run on, checked for the exec transport first. |
| Destructive operations | Need an explicit confirmation whatever the automatic-write setting; over HTTP the call, or force: true, is it, and a confirmed field is ignored. |
Where the GitHub token goes
Section titled “Where the GitHub token goes”| Case | What happens |
|---|---|
git and gh calls | Calls that need authentication receive GH_TOKEN (GH_ENTERPRISE_TOKEN on Enterprise Server); the command line holds only the name. Local Git operations run without the token. Global and system Git config are disabled (GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM point at /dev/null), hooks are off, and authenticated calls override repository credential helpers, so a repository’s credential helper cannot read it. |
| Records | Not written to the session record, the logs or the daemon’s memory. Output is scanned for the token, so a server reflecting it back cannot leak it. |
| TUI clone | Writes the token into a mode 0600 credential store in the checkout’s .git, with a host-scoped credential.helper, so plain git push works from the agent’s shell. It stays there, readable by the agent, scoped to that host over HTTPS. Re-linking an expired account re-points the copies, leaving another account’s copy alone. |
| Logging out | Deletes the copies only in checkouts a live session is bound to, replying "credential_purge": "partial"; others, and those in stopped computers, keep theirs. Revoking the token on GitHub is the only complete remedy. |
| HTTP or SDK clone | Persists no token unless persist_credentials: true. POST /api/v1/agent/github/repo/reconnect always writes or refreshes it. No other route persists a token. |
MCP servers
Section titled “MCP servers”The built-in GitHub tools keep the credential in the daemon, so you do not need the GitHub MCP server below. The client speaks every MCP revision from 2024-11-05 through 2026-07-28, negotiating with each server.
| Key in MCP servers mode | Does |
|---|---|
M on the Agents tab, or the mode strip | Opens it. M from the Skills tab traces where a tool came from. |
space / enter | Enable or disable the selected server |
d / delete | Arm removal; press again to confirm, any other key disarms |
i | Import servers from a pasted config |
R | Re-read the config from disk and reconnect (at most once every 5s per session) |
r | Refresh the list |
M / esc | Back to Definitions (tab does not: the tab switcher takes it) |
| Behaviour | Detail |
|---|---|
| Live state | Connected or not, negotiated revision, tool count, a stdio child’s process id, and its stderr tail when it dies. |
| Removal | Asks twice because it destroys env and headers, which are never shown again. Moving the selection, leaving the surface or tab, or a refresh disarms it. |
| Import | Claude, Cursor and VS Code dialects; a mix is refused. ctrl+p previews what would be written, credentials stripped; ctrl+s writes. |
| Open sessions | Disabling or removing a server cuts it off at once, mid-turn; a call already sent may return. An untouched healthy server is never restarted by an unrelated edit. |
| Layers | Settings layers merge field by field. Read files from GET /api/v1/agent/mcp/servers?session_id=<id> for the session’s resolved settings paths. A later layer that changes type, command, args or url without its own env/headers clears them. |
| stdio environment | Scrubbed: no provider API key or Hoody platform token is inherited. "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"} shares the daemon’s value with that one server. |
{ "mcp_servers": [ { "name": "filesystem", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], "require_confirmation": true }, { "name": "github", "command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } }, { "name": "git", "command": "uvx", "args": ["mcp-server-git", "--repository", "/workspace"] }, { "name": "sentry", "type": "http", "url": "https://mcp.sentry.dev/mcp", "headers": { "Authorization": "Sentry-Bearer ${SENTRY_TOKEN}" }, "allowed_tools": ["search_issues", "search_events"] } ]}| Entry | What it shows |
|---|---|
filesystem | The path is the server’s own access control, not Hoody’s; the process runs with your privileges. Hoody enforces require_confirmation, on every call, reads included. |
github | Left, the server’s variable name; right, ${VAR} from the daemon’s environment. -e NAME with no value makes Docker forward it, so the token is never in args. |
git | uvx (Python) works like npx. |
sentry | A remote server, no subprocess. Sentry wants Sentry-Bearer, since plain Bearer is reserved for MCP OAuth tokens there. |
MCP config fields
Section titled “MCP config fields”| Field | Rule |
|---|---|
type | stdio (default); http, url, streamable or streamable-http for Streamable HTTP; or sse for the deprecated 2024-11-05 HTTP+SSE transport. Values are case-insensitive. Another value is a config error, not a fallback. |
name | 1 to 64 ASCII letters, digits, _ or -; no __, and neither hoody nor mcp in any letter case. |
enabled | Absent means enabled. A disabled server keeps its config and credentials but is not connected or advertised. |
allowed_tools | Exact names. Absent means no restriction; empty means nothing; a near-miss name silently exposes nothing. |
require_confirmation | Every call goes through the confirm gate. A tool the server marks destructive gets one anyway. |
env (stdio), headers (URL) | The only fields where ${VAR} expands, anywhere in the value. Ordinary variables come from the daemon’s environment; HOODY_* variables come from the session’s scoped Hoody environment, or expand to empty when it is not available. "Bearer ${TOKEN}" works, and a Bearer prefix inside the variable is sent twice. An unset variable expands to empty. |
command, args, url | Used verbatim: a literal secret sits in clear text in settings.json, and ${VAR} stays literal. In args the server usually fails to authenticate; in command it never starts; in url the literal reaches URL parsing. |
MCP over HTTP
Section titled “MCP over HTTP”GET/PUT/DELETE /api/v1/agent/mcp/servers, plus POST /mcp/servers/enable, /mcp/import, /mcp/parse and /mcp/reconnect (MCP API). Every write (upsert, delete, set_enabled, import) presents a single-use nonce from POST /mcp/write-intents, bound to one operation and one settings layer, and expect_hash, the hash you last read, so a concurrent edit is a conflict. The enable route’s op is set_enabled; any other op is refused before a nonce is issued. For a file that does not exist yet, pass the empty-array hash the read reports. POST /mcp/probe tries a config without saving it and refuses machine callers, because it starts a process or contacts a URL of the caller’s choosing.
Approval policy
Section titled “Approval policy”| Rule | Detail |
|---|---|
locked: true | Turning YOLO on, adding a per-tool allow rule and clearing a rule are refused with 409. Turning YOLO off and adding a deny rule remain allowed. A confirmation requesting a remembered allow applies once and reports session_scope_applied: false. prompt:sync and prompt:stream with policy=auto_approve are refused with 409 on an always session. |
| Revision | A stale If-Match answers 412 with the current revision, so no client overwrites another unseen. |
| Per-tool rules | /sessions/{id}/approval/rules/{tool}, allow or deny. A deny is always accepted; adding an allow is refused on an always or locked policy. Existing allow rules remain effective when a default policy is locked; always mode ignores them. |
Approver lease
Section titled “Approver lease”On an always session whose lease was minted, every decision presents it, so two clients cannot both answer a gate, and a client that lost it is refused. POST /sessions/{id}/approver-lease returns the capability once, bound to the session and caller with a visible expiry; every confirm sends it in X-Hoody-Approver-Lease. A second acquire answers 409 unless it presents the current capability (replace: true alone does not). Renew with PATCH, release with DELETE. It lives in memory: after a restart the approval read reports held: false.
Retry-safe turns
Section titled “Retry-safe turns”| Rule | Detail |
|---|---|
| Dispatch | POST /sessions/{id}/turns answers 202 with a receipt (turn_id, job_id, state, stream_url, result_url) once the turn is recorded durably. POST /sessions/{id}/messages returns the same turn_id. |
Idempotency-Key | A retry with the same key returns the same receipt with duplicate: true; the turn never runs twice. The same key with a different request is 422. |
| Busy session | A running turn or parked confirmation refuses with 409 and records nothing. |
| Turn record | GET /sessions/{id}/turns/{turn_id}, live or dormant session: state, then outcome and error_code. A turn cut off by a restart ends interrupted with effects_may_have_occurred and is never re-run on its own. |
Session state and attachments
Section titled “Session state and attachments”GET /sessions/{id}/state is one snapshot to rebuild from after a disconnect: the stream cursor (incarnation, seq), state (idle, running, parked or closed), the approval policy and rules, queued turn ids, and any parked confirmation with the identity a confirm must name.
Without a stream or attachment lease, an idle session or an unanswered parked gate can close after five minutes. Running turns and background helpers keep the session alive. POST /sessions/{id}/attachments keeps the session and its parked confirmation open, 15 minutes by default, at most 60 minutes; use the returned lease_id to renew with PATCH /sessions/{id}/attachments/{lease_id} or release with DELETE /sessions/{id}/attachments/{lease_id}. Leases end when the agent restarts; /state reports what survived.
Memory
Section titled “Memory”| Topic | Detail |
|---|---|
| Erasing a project | Two calls: ask for a write intent, then present it on the delete. A reply with incomplete_erasure: true erased the items but could not confirm the steps listed in incomplete_steps, so a derived copy may still hold erased material until it is rebuilt. Check this field before treating an erasure as clean. |
| Time order | Exact to the nanosecond: a timeline around an item always contains that item, and items recorded in the same instant keep one stable order. |
| Older builds | An older agent build cannot open a store a newer build upgraded. It reports the store unavailable instead of running against it, and the store is not wiped. |
Setup and defaults
Section titled “Setup and defaults”| Topic | Detail |
|---|---|
| Install | Included in every computer created with hoody_kit: true; the daemon starts the first time you reach the agent, and sessions and files stay with the computer. No setup step or policy file. |
| Command sandbox | On by default: Landlock on Linux with a bubblewrap fallback, Seatbelt on macOS. On a Linux Hoody computer where the agent’s user has passwordless sudo, the bash tool runs unsandboxed. Otherwise, when no mechanism is available, it logs a warning and runs unsandboxed, unlike the Program Sandbox, which refuses to launch; a realm-limited login serving several realms refuses the local shell instead. |
| Always on | Confirmation rules and terminal-output sanitization. |
| Telemetry | None: no analytics, crash reports or telemetry calls. It still contacts the model providers, web services, OAuth endpoints and optional Hoody platform services you use. |
Troubleshooting
Section titled “Troubleshooting”| Symptom, status or message | Cause | What to do |
|---|---|---|
Tools answer not logged in | The session was bound to a computer through your account while the agent had no sign-in | Sign the agent in, then start a new session. |
| Sign-in refused | Wrong account, a token made from another token, a missing permission, or too little time left | The reply lists what is missing. |
422 provider_invalid | A provider definition breaks a rule on create or update, including an internal address or a name that resolves to one. A later connection refusal appears as a turn error | Fix the field the reply names. |
409 provider_exists | A create without Idempotency-Key repeated after it went through | The provider exists; use it. |
409 provider_builtin, 409 provider_not_managed | Built-in providers, and those in a project’s providers file, cannot be changed or removed here | Create a custom provider instead. |
| MCP server fails to authenticate | ${VAR} in args | Move the secret to env or headers. |
| MCP server never starts | ${VAR} in command | Write the real command. |
409 changing approval or sending a turn | A turn or confirmation is in flight, or the policy is locked | Wait until idle, or start a new session. |
prompt:sync answers 503 after 290 seconds | The turn is still running; it is not cancelled | Poll GET /sessions/{id}/turns/{turn_id} with details.turn_id. |