# devoidfury/hotdog architecture

> Architecture diagram of the GitHub repository devoidfury/hotdog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devoidfury/hotdog
- Repository: https://github.com/devoidfury/hotdog

## Overview

hotdog is a local-first agent harness for OpenAI-compatible inference backends. Its main workflow starts from a one-shot or interactive CLI (or Web UI), assembles configuration and extensions, runs an agent against a model, and exposes tool use and session results. The graph also preserves documented extension capabilities such as approvals, compaction, skills, MCP, subagents, and workflows. Relationships for unsampled features are based on README descriptions; source excerpts are partial, so implementation-level links are limited.

Main entry points: [`src/core/agent.ts`](https://github.com/devoidfury/hotdog/blob/main/src/core/agent.ts) (Agent loop), [`src/core/extensions/tool-registry.ts`](https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/tool-registry.ts) (Tool registry), [`src/core/main.ts`](https://github.com/devoidfury/hotdog/blob/main/src/core/main.ts) (Runtime bootstrap), [`src/core/extensions/extensions.ts`](https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/extensions.ts) (Extension loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_main["Runtime bootstrap<br/>[main.ts]"]
  node_config["Configuration and profiles"]
  node_extension_loader["Extension loader<br/>[extensions.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_loop["Agent loop<br/>[agent.ts]"]
  node_context["Context management<br/>[context-manager.ts]"]
  node_inference["LLM client<br/>[client.ts]"]
  node_tool_execution["Tool execution<br/>[tool-executor.ts]"]
  node_tool_registry["Tool registry<br/>[tool-registry.ts]"]
  node_hooks["Extension hooks<br/>[hooks.ts]"]
end

subgraph group_extensions["Agent capabilities"]
  node_core_tools["File tools"]
  node_bash["Bash tool<br/>[index.ts]"]
  node_approvals["Tool approvals<br/>[index.ts]"]
  node_compaction["Context compaction<br/>[index.ts]"]
  node_skills["Skills<br/>[index.ts]"]
  node_mcp["MCP client<br/>[client.ts]"]
  node_subagents["Subagents<br/>[index.ts]"]
  node_workflows["Workflow graphs<br/>[engine.ts]"]
  node_handoff["Task handoff<br/>[index.ts]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI modes<br/>[index.ts]"]
  node_oneshot["One-shot CLI<br/>[index.ts]"]
  node_webui["Web UI<br/>[server.ts]"]
  node_websocket["WebSocket server<br/>[server.ts]"]
end

subgraph group_state["Session state"]
  node_session_log[("Session logs<br/>[session-log.ts]")]
end

node_user(("User"))

node_user -->|"starts"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"loads extensions"| node_extension_loader
node_user -->|"interacts"| node_cli
node_user -->|"submits prompt"| node_oneshot
node_user -->|"opens interface"| node_webui
node_webui -->|"serves sessions"| node_websocket
node_cli -.->|"runs agent"| node_agent_loop
node_oneshot -.->|"runs agent"| node_agent_loop
node_agent_loop -.->|"manages context"| node_context
node_agent_loop -.->|"requests completion"| node_inference
node_agent_loop -.->|"runs tool calls"| node_tool_execution
node_tool_execution -.->|"resolves tools"| node_tool_registry
node_extension_loader -->|"registers hooks"| node_hooks
node_extension_loader -->|"registers tools"| node_tool_registry
node_tool_registry -.->|"offers tools"| node_core_tools
node_tool_registry -.->|"offers tool"| node_bash
node_tool_execution -.->|"checks calls"| node_approvals
node_agent_loop -.->|"manages context"| node_compaction
node_agent_loop -.->|"loads guides"| node_skills
node_tool_registry -.->|"offers tools"| node_mcp
node_agent_loop -.->|"delegates tasks"| node_subagents
node_agent_loop -.->|"runs workflows"| node_workflows
node_agent_loop -.->|"restarts with plan"| node_handoff
node_agent_loop -.->|"logs sessions"| node_session_log

click node_main "https://github.com/devoidfury/hotdog/blob/main/src/core/main.ts"
click node_config "https://github.com/devoidfury/hotdog/tree/main/src/core/config"
click node_extension_loader "https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/extensions.ts"
click node_agent_loop "https://github.com/devoidfury/hotdog/blob/main/src/core/agent.ts"
click node_context "https://github.com/devoidfury/hotdog/blob/main/src/core/context/context-manager.ts"
click node_inference "https://github.com/devoidfury/hotdog/blob/main/src/core/llm-client/client.ts"
click node_tool_execution "https://github.com/devoidfury/hotdog/blob/main/src/core/tool-executor.ts"
click node_tool_registry "https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/tool-registry.ts"
click node_hooks "https://github.com/devoidfury/hotdog/blob/main/src/core/hooks.ts"
click node_core_tools "https://github.com/devoidfury/hotdog/tree/main/src/extensions/core-tools"
click node_bash "https://github.com/devoidfury/hotdog/blob/main/src/extensions/bash-tool/index.ts"
click node_approvals "https://github.com/devoidfury/hotdog/blob/main/src/extensions/user-gate/index.ts"
click node_compaction "https://github.com/devoidfury/hotdog/blob/main/src/extensions/compaction/index.ts"
click node_skills "https://github.com/devoidfury/hotdog/blob/main/src/extensions/skills/index.ts"
click node_mcp "https://github.com/devoidfury/hotdog/blob/main/src/extensions/mcp-client/client.ts"
click node_subagents "https://github.com/devoidfury/hotdog/blob/main/src/extensions/subagents/index.ts"
click node_workflows "https://github.com/devoidfury/hotdog/blob/main/src/extensions/workflows/engine.ts"
click node_handoff "https://github.com/devoidfury/hotdog/blob/main/src/extensions/handoff-tool/index.ts"
click node_cli "https://github.com/devoidfury/hotdog/blob/main/src/extensions/ui-interactive-cli/index.ts"
click node_oneshot "https://github.com/devoidfury/hotdog/blob/main/src/extensions/ui-one-shot/index.ts"
click node_webui "https://github.com/devoidfury/hotdog/blob/main/src/extensions/webui/server.ts"
click node_websocket "https://github.com/devoidfury/hotdog/blob/main/src/extensions/websocket/server.ts"
click node_session_log "https://github.com/devoidfury/hotdog/blob/main/src/core/session/session-log.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_extension_loader,node_user toneBlue
class node_agent_loop,node_context,node_inference,node_tool_execution,node_tool_registry,node_hooks toneAmber
class node_core_tools,node_bash,node_approvals,node_compaction,node_skills,node_mcp,node_subagents,node_workflows,node_handoff toneMint
class node_cli,node_oneshot,node_webui,node_websocket toneRose
class node_session_log toneIndigo
```

## Components

### Entry and configuration

- [Runtime bootstrap](https://github.com/devoidfury/hotdog/blob/main/src/core/main.ts): `src/core/main.ts`
- [Configuration and profiles](https://github.com/devoidfury/hotdog/tree/main/src/core/config): `src/core/config`
- [Extension loader](https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/extensions.ts): `src/core/extensions/extensions.ts`

### Agent runtime

- [Agent loop](https://github.com/devoidfury/hotdog/blob/main/src/core/agent.ts): `src/core/agent.ts`
- [Context management](https://github.com/devoidfury/hotdog/blob/main/src/core/context/context-manager.ts): `src/core/context/context-manager.ts`
- [LLM client](https://github.com/devoidfury/hotdog/blob/main/src/core/llm-client/client.ts): `src/core/llm-client/client.ts`
- [Tool execution](https://github.com/devoidfury/hotdog/blob/main/src/core/tool-executor.ts): `src/core/tool-executor.ts`
- [Tool registry](https://github.com/devoidfury/hotdog/blob/main/src/core/extensions/tool-registry.ts): `src/core/extensions/tool-registry.ts`
- [Extension hooks](https://github.com/devoidfury/hotdog/blob/main/src/core/hooks.ts): `src/core/hooks.ts`

### Agent capabilities

- [File tools](https://github.com/devoidfury/hotdog/tree/main/src/extensions/core-tools): `src/extensions/core-tools`
- [Bash tool](https://github.com/devoidfury/hotdog/blob/main/src/extensions/bash-tool/index.ts): `src/extensions/bash-tool/index.ts`
- [Tool approvals](https://github.com/devoidfury/hotdog/blob/main/src/extensions/user-gate/index.ts): `src/extensions/user-gate/index.ts`
- [Context compaction](https://github.com/devoidfury/hotdog/blob/main/src/extensions/compaction/index.ts): `src/extensions/compaction/index.ts`
- [Skills](https://github.com/devoidfury/hotdog/blob/main/src/extensions/skills/index.ts): `src/extensions/skills/index.ts`
- [MCP client](https://github.com/devoidfury/hotdog/blob/main/src/extensions/mcp-client/client.ts): `src/extensions/mcp-client/client.ts`
- [Subagents](https://github.com/devoidfury/hotdog/blob/main/src/extensions/subagents/index.ts): `src/extensions/subagents/index.ts`
- [Workflow graphs](https://github.com/devoidfury/hotdog/blob/main/src/extensions/workflows/engine.ts): `src/extensions/workflows/engine.ts`
- [Task handoff](https://github.com/devoidfury/hotdog/blob/main/src/extensions/handoff-tool/index.ts): `src/extensions/handoff-tool/index.ts`

### User interfaces

- [CLI modes](https://github.com/devoidfury/hotdog/blob/main/src/extensions/ui-interactive-cli/index.ts): `src/extensions/ui-interactive-cli/index.ts`
- [One-shot CLI](https://github.com/devoidfury/hotdog/blob/main/src/extensions/ui-one-shot/index.ts): `src/extensions/ui-one-shot/index.ts`
- [Web UI](https://github.com/devoidfury/hotdog/blob/main/src/extensions/webui/server.ts): `src/extensions/webui/server.ts`
- [WebSocket server](https://github.com/devoidfury/hotdog/blob/main/src/extensions/websocket/server.ts): `src/extensions/websocket/server.ts`

### Session state

- [Session logs](https://github.com/devoidfury/hotdog/blob/main/src/core/session/session-log.ts): `src/core/session/session-log.ts`

### Other components

- **User**

## Connections

- User → Runtime bootstrap: starts
- Runtime bootstrap → Configuration and profiles: loads settings (evidence: `src/core/main.ts`)
- Runtime bootstrap → Extension loader: loads extensions (evidence: `src/core/main.ts`)
- User → CLI modes: interacts
- User → One-shot CLI: submits prompt
- User → Web UI: opens interface
- Web UI → WebSocket server: serves sessions (evidence: `src/extensions/webui/server.ts`)
- CLI modes → Agent loop: runs agent
- One-shot CLI → Agent loop: runs agent
- Agent loop → Context management: manages context
- Agent loop → LLM client: requests completion
- Agent loop → Tool execution: runs tool calls
- Tool execution → Tool registry: resolves tools
- Extension loader → Extension hooks: registers hooks
- Extension loader → Tool registry: registers tools
- Tool registry → File tools: offers tools
- Tool registry → Bash tool: offers tool
- Tool execution → Tool approvals: checks calls
- Agent loop → Context compaction: manages context
- Agent loop → Skills: loads guides
- Tool registry → MCP client: offers tools
- Agent loop → Subagents: delegates tasks
- Agent loop → Workflow graphs: runs workflows
- Agent loop → Task handoff: restarts with plan
- Agent loop → Session logs: logs sessions