# Agent reference **Page:** kit/agent/reference [Download Raw Markdown](./kit/agent/reference.md) --- # Agent reference Lookup tables for the [Hoody Agent](/kit/agent/). Every route, field and response is in the [Agent API reference](/api/agent/). ## 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](/kit/terminals/#text-draws-wrongly-in-the-web-terminal). | | API | A generated OpenAPI 3.1 description, browsable in the [Agent API reference](/api/agent/); `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). | ## TUI | 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 | 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 | 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 | Field or rule | Detail | |---|---| | Required | `id`, `base_url`, `models`. Every field is in the [models API](/api/agent/models/). | | `id` | 1 to 40 lowercase letters, digits or inner hyphens; cannot change later. Models are `/`, 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 | Item | Detail | |---|---| | Agents | Swap the active agent mid-session. | | Skills | Drop a `SKILL.md` into `.hoody/skills//` 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 | 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 `/`); `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 | 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 Every operation is under `/api/v1/agent/github/`; the [GitHub API reference](/api/agent/github/) 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 | 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 The built-in [GitHub](#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=` 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. | ```json { "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. | Several widely copied `@modelcontextprotocol/server-*` packages, including github, postgres, sqlite, puppeteer and gitlab, were archived to `modelcontextprotocol/servers-archived` and may still install and run. Prefer the vendor's own server (GitHub's is `github/github-mcp-server`) and its current README. ### 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 `GET`/`PUT`/`DELETE` `/api/v1/agent/mcp/servers`, plus `POST` `/mcp/servers/enable`, `/mcp/import`, `/mcp/parse` and `/mcp/reconnect` ([MCP API](/api/agent/mcp/)). 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 | 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 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 | 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 `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 | 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 | 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](/kit/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 | 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](/kit/agent/#sign-the-agent-in-to-your-account), 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`. |