devoidfury/hotdog — Hotdog: An AI Agent Harness
Transcript
QuickFacts
Let's explore Hotdog — a lightweight AI agent framework that turns any language model into an autonomous coding assistant.
PlainEnglish
Think of Hotdog as the scaffolding between an AI model and your filesystem. It handles streaming API responses, executes tools when the model wants to read or edit files, keeps conversation history under token limits, and coordinates background workers for parallel tasks. It's the plumbing that makes the AI useful.
QuickFacts
The stack is deliberately minimal. It's TypeScript running on Bun, which provides all the runtime APIs — no npm dependencies. The agent connects to any OpenAI-compatible endpoint for language model inference and supports the Model Context Protocol for plugging in third-party tools.
Architecture
Here's how the pieces fit together. User input flows into the Agent, which is the main loop managing conversation history. The Agent fires events through a HookSystem that extensions listen to. When ready, the Agent streams a request to the LLM client, gets back content and tool calls, and hands those tool calls to the ToolExecutor. Results loop back, and the cycle continues.
Architecture
The HookSystem is like a bulletin board in an office building. Extensions post handlers for thirty-plus event hooks — things like CONTEXT before compaction checks, TOOL_CALL when a gate decision is needed, PROVIDER_RESPONSE after the model answers. Compaction checks token count on CONTEXT, security extensions can block tools on TOOL_CALL, and metrics watchers log everything on TURN_END. It's how the core stays minimal while features compose freely.
Architecture
Extensions are loaded like plugins in a digital audio workstation. The loader scans for extension dot json manifests, reads declared dependencies, and sorts everything topologically so dependencies load first. It imports each extension, calls its create function passing the core API, extracts hook handlers, and wires them to the event bus. Then it fires the TOOLS_REGISTER hook so extensions can add their tools. No manual registration needed — drop a folder in, restart, and you're live.
Architecture
Tool execution is like airport security — multiple checkpoints. The call enters, first checkpoint validates the tool exists, second fires the gate hook so extensions can block or modify, third checks arguments against JSON schema, fourth executes the actual tool with a context object, and fifth logs metrics and writes the result to conversation history. Extensions can inject checkpoints anywhere via hooks.
Architecture
Task delegation works like a construction foreman with subcontractors. The manager agent has a delegate task tool that spawns worker agents. Each worker is a full agent with its own LLM loop but a restricted tool set — no spawning more workers. Workers run in parallel, do their work autonomously, and when done they file a completion report that gets appended to the manager's context and wakes the manager up. The manager can check in or send clarifications but mostly lets them work.
PlainEnglish
Here's what a real session looks like. Alice asks the agent to fix a login validation bug. The agent adds her message to the conversation log, streams the context to the LLM, and the model responds with a grep tool call searching for login validation. The tool executor runs the search, appends results to the log, and the agent loops back. Now seeing the grep results, the model calls read to open the file, then edit with a targeted replacement fixing the bug. Finally it returns a text response explaining what it changed. The whole conversation is logged to a JSON lines file for debugging later.
Architecture
Let's zoom into the core modules. The Agent orchestrates everything — it builds messages via MessageLog, streams requests through LlmClient, and delegates tool execution to ToolExecutor. All three components fire lifecycle events through the HookSystem, which is how extensions hook into the flow. The Tool Executor also fires gate hooks so extensions can block or transform tool calls before they run. These five modules form the foundation, and everything else is an extension listening to their events.
Community
This is a very young project — committed just today, with a single contributor and two branches. No tags or releases yet, but the signal is active. It's early-stage code, so expect API changes and experimentation. If you're curious about agent frameworks or want to see a clean hook-driven architecture in action, this is a great time to dive in and shape its direction.
PlainEnglish
Here's the takeaway. Hotdog proves you can build a capable AI agent framework with a tiny core and radical extensibility. Twenty-nine thousand lines, zero npm dependencies, and every feature is a plugin listening to hooks. If you need an agent harness you can actually understand and modify, this architecture is worth studying. Thanks for watching.
How this was made
Lenzon read devoidfury/hotdog and generated this walkthrough automatically. The narration above is the transcript of what it says.
Explain a pull request from your own repo
Point Lenzon at a repo or a pull request and get a narrated walkthrough like this one.
Try it