Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for the Hoody Agent. Every route, field and response is in the Agent API reference.

PartDetail
hoody-agent-dThe daemon, written in Go. It owns model streaming, tool execution, sessions, workflows and memory.
hoody-agentThe 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 URLHoody 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.
APIA 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 groupHolds
AGENTConversations, named agent profiles and the MCP servers they reach, skills, multi-step pipelines, a work inbox
FLEETComputers’ live terminals, displays and files, published exec scripts, custom domains, and your account: servers, rentals, wallet, API keys
SYSTEMProviders and credentials, encrypted secrets, persistent memory, logs
FeatureDetail
MouseTabs, 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 panesEach pane scrolls on its own and flags when it needs you.
Multi-attachA client that joins mid-turn gets the full view plus the turn in progress replayed.
Clipboard imagesCtrl+V in the composer (right-click, then Paste, in the browser); the model sees the image.
Paste collapseA long paste folds into a [Pasted text #N] chip you can click to edit; the model gets the full text.
Web panesIn the browser, an “open a URL” pane shows a real web page clipped to the pane; in a plain terminal, a placeholder.
AttentionA snackbar opens straight to a background session’s waiting decision.
FLEETDiscover 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.
VaultRealm-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.
TopicDetail
Hoody AIThe default, hoody-ai/hoody-free, needs no key inside a Hoody computer and remains the default until you choose another model.
Catalogue100+ 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 keysPUT /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 modelPOST /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 profilePATCH /api/v1/agent/agents/{name}/model with {"model": "..."} pins a profile.
OAuth poolsPool several OAuth accounts per provider; the agent rotates as each hits its limit.
FusionAn engine in the daemon votes, synthesizes or debates across several models.
Token usePhase 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.
RuleDetail
Claude Pro or MaxHoody 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 CLIsClaude 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 subagentsClaude 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 subagentsA 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.
Field or ruleDetail
Requiredid, base_url, models. Every field is in the models API.
id1 to 40 lowercase letters, digits or inner hyphens; cannot change later. Models are <id>/<model>, and model_prefix, if sent, must equal id.
base_urlThe 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_schemechat_completions (default) or responses with bearer; messages with x-api-key.
headersStatic headers on every call, chat_completions only. Credential headers such as Authorization are refused.
Modelscontext_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 effectNew sessions and model switches see it, and an open session on one of its models picks it up before its next turn.
RetryWith an Idempotency-Key, a retry with the same key and body answers 201 with the provider the first try created.
EditPATCH /api/v1/agent/providers/{id} changes only the members you send; models and headers replace the whole list and map.
RemoveDELETE /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.
ItemDetail
AgentsSwap the active agent mid-session.
SkillsDrop a SKILL.md into .hoody/skills/<name>/ and live sessions pick it up.
WorkflowsA 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.
TODOsFile items, let an LLM pass sort them, and dispatch any item as a background orchestrator run.
Background subagentsThe parent is notified on completion; each has a live transcript.
Orchestrator modeA 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 toolsFile 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.
TopicDetail
Device sign-inPOST /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 tokenA 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 accountsGET /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.
TabShows and does
StatusBranches with the checked-out one marked and their tracking refs. Switch, commit, create or delete a branch, sync, stash and pop, diff and log.
WorktreesAdd and remove worktrees.
PRsList, open, check out and merge pull requests, and follow their checks.
IssuesList 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.

Every operation is under /api/v1/agent/github/; the GitHub API reference lists each one.

Route or headerDetail
clonerepo is owner/name or an HTTPS GitHub URL, resolved against the active account’s host; a URL on another host is refused.
syncFetch, 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-ComputerThe working directory, and a remote computer to run on, checked for the exec transport first.
Destructive operationsNeed an explicit confirmation whatever the automatic-write setting; over HTTP the call, or force: true, is it, and a confirmed field is ignored.
CaseWhat happens
git and gh callsCalls 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.
RecordsNot 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 cloneWrites 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 outDeletes 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 clonePersists no token unless persist_credentials: true. POST /api/v1/agent/github/repo/reconnect always writes or refreshes it. No other route persists a token.

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 modeDoes
M on the Agents tab, or the mode stripOpens it. M from the Skills tab traces where a tool came from.
space / enterEnable or disable the selected server
d / deleteArm removal; press again to confirm, any other key disarms
iImport servers from a pasted config
RRe-read the config from disk and reconnect (at most once every 5s per session)
rRefresh the list
M / escBack to Definitions (tab does not: the tab switcher takes it)
BehaviourDetail
Live stateConnected or not, negotiated revision, tool count, a stdio child’s process id, and its stderr tail when it dies.
RemovalAsks 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.
ImportClaude, Cursor and VS Code dialects; a mix is refused. ctrl+p previews what would be written, credentials stripped; ctrl+s writes.
Open sessionsDisabling 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.
LayersSettings 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 environmentScrubbed: 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"]
}
]
}
EntryWhat it shows
filesystemThe 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.
githubLeft, 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.
gituvx (Python) works like npx.
sentryA remote server, no subprocess. Sentry wants Sentry-Bearer, since plain Bearer is reserved for MCP OAuth tokens there.
FieldRule
typestdio (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.
name1 to 64 ASCII letters, digits, _ or -; no __, and neither hoody nor mcp in any letter case.
enabledAbsent means enabled. A disabled server keeps its config and credentials but is not connected or advertised.
allowed_toolsExact names. Absent means no restriction; empty means nothing; a near-miss name silently exposes nothing.
require_confirmationEvery 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, urlUsed 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.

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.

RuleDetail
locked: trueTurning 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.
RevisionA 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.

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.

RuleDetail
DispatchPOST /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-KeyA 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 sessionA running turn or parked confirmation refuses with 409 and records nothing.
Turn recordGET /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.

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.

TopicDetail
Erasing a projectTwo 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 orderExact to the nanosecond: a timeline around an item always contains that item, and items recorded in the same instant keep one stable order.
Older buildsAn 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.
TopicDetail
InstallIncluded 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 sandboxOn 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 onConfirmation rules and terminal-output sanitization.
TelemetryNone: no analytics, crash reports or telemetry calls. It still contacts the model providers, web services, OAuth endpoints and optional Hoody platform services you use.
Symptom, status or messageCauseWhat to do
Tools answer not logged inThe session was bound to a computer through your account while the agent had no sign-inSign the agent in, then start a new session.
Sign-in refusedWrong account, a token made from another token, a missing permission, or too little time leftThe reply lists what is missing.
422 provider_invalidA 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 errorFix the field the reply names.
409 provider_existsA create without Idempotency-Key repeated after it went throughThe provider exists; use it.
409 provider_builtin, 409 provider_not_managedBuilt-in providers, and those in a project’s providers file, cannot be changed or removed hereCreate a custom provider instead.
MCP server fails to authenticate${VAR} in argsMove the secret to env or headers.
MCP server never starts${VAR} in commandWrite the real command.
409 changing approval or sending a turnA turn or confirmation is in flight, or the policy is lockedWait until idle, or start a new session.
prompt:sync answers 503 after 290 secondsThe turn is still running; it is not cancelledPoll GET /sessions/{id}/turns/{turn_id} with details.turn_id.