Overview — what hotl is

hotl is a human-on-the-loop agent harness in one binary: bare hotl is the coding agent, hotl watch is the tmux dashboard for supervising agents, and hotl fleet (orchestration) is reserved. These docs cover the agent; for the dashboard see crates/hotl/README.md, and for the internals see ARCHITECTURE.md.

The design commitments

The session log is the source of truth. Every session is an append-only event log that nothing rewrites. hotl resume continues from it, hotl undo restores the agent’s last clean checkpoint via shadow-git snapshots taken at quiet windows (session start and each mutating batch’s end, always off the turn path), and context compaction appends a summary on top of history instead of replacing it — a failed compaction can’t corrupt a session.
A permission gate with a kernel floor under it. Every mutating or executing tool call passes the gate: bypass (default, no ordinary prompts), ask (y/N per call), or dontask (deny anything not pre-approved), plus an independent plan-mode toggle that makes write/edit always ask. Independent of mode, bash runs confined by Seatbelt (macOS) or Landlock (Linux) to writes inside the working directory — plus any [sandbox].writable cache directories the owner listed; entries that would expose hotl’s own config are refused — and writes to execute-later paths — git hooks, shell rc, Makefiles, agent-instruction files — never pass silently: they prompt under ask/dontask/plan and run with a loud ⚑ notice (never a blocking prompt) under bypass, which also refuses writes outside the session root outright. A build with --features security-enforced cannot have prompting disabled by any config. Network egress control is opt-in: [network].allow routes HTTP through a local allowlist proxy, and unenforceable restrictions fail loudly, never silently.
Context stays slim by construction. Tool results past a size threshold are evicted to files ([context].evict_tokens) — a preview stays inline and the agent pages the full result back on demand. Compaction summaries are precomputed in the background from ~60% context-full and fold in at ~80%, so the fold never pauses the session. The prompt prefix is byte-stable, keeping provider prompt caches hot, and each turn’s status can opt in to showing the model context fullness (show_used_pct; hidden by default so the model never wraps up early to “save” context).
Skills are indexed, not preloaded. Saved procedures — your own, your marketplaces’, and any Claude Code skills you already have — never sit in the context waiting to be used. The agent is shown a grouped index (one line per source, large sources collapsed to a count) and pulls a skill’s text only when it loads one; it can search every description on demand, and you can force one with /<skill> in the console. A 300-skill marketplace costs one line per request, not 300 names. The full design — and why there is deliberately no index database — is in skills.md.
Any model, two provider seams. HOTL_MODEL=provider/model: anthropic/… speaks the Messages API (SSE streaming, prompt-cache placement); openai/… speaks chat-completions and covers OpenAI, Groq, Ollama, gateways — anything with a base URL.
Standard protocols at the edges. MCP client (stdio transport) for external tools; hotl acp serves ACP over stdio so any ACP-speaking editor can embed the agent — the same seam the future hotl fleet orchestrator will drive.
Surfaces for how you actually work. A console TUI you can steer mid-turn, -p headless (with --json) for scripts and CI, a zsh : prefix that turns a shell line into an agent prompt, hotl bg/attach for sessions that outlive your terminal, and hotl watch for supervising every agent in your tmux session.
Nothing hidden. No daemon, no telemetry; config lives in ~/.config/hotl, sessions in ~/.local/share/hotl, and every auto-allowed call is visible in the transcript.

Read by need

You want to…	Read
Run it the first time, start to finish	quickstart.md
Drive the agent from a full-screen console	tui.md
Continue an earlier session, or fork one into a new phase	sessions.md
Prompt the agent straight from your shell (`:` prefix)	shell.md
Run a session detached and reconnect later	backgrounding.md
Understand the y/N gate, protected paths, and the sandbox — and what they don’t cover	permissions-and-sandbox.md
Save procedures the agent loads on demand (skills)	skills.md
Connect an MCP tool server	mcp.md
Run your own checks/policy on tool calls (diagnostics + hooks)	hooks.md
Run through a gateway / fetch keys from a command	gateway.md
Look up a config file, env var, subcommand, or exit code	configuration.md
Fix an error you hit	troubleshooting.md
Remove hotl and its data	uninstall.md
Point an AI agent at these docs	llms.txt — the machine-readable map

Status (2026-07-24): pre-1.0; the core harness, the headless/ACP surfaces, the extension hooks, and sub-agents (spawn, agents.md) described here are implemented and published — install with the release installer or cargo install hotl (0.2.0+; earlier crates.io releases were the watch-only dashboard). hotl acp is not yet documented here. Permission prompts are opt-in ([permissions] mode = "bypass" is the default) — see permissions-and-sandbox.md.