# vibepod/vibepod-cli architecture

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

- Interactive diagram: https://gitdiagram.com/vibepod/vibepod-cli
- Repository: https://github.com/vibepod/vibepod-cli

## Overview

VibePod is a CLI for running AI coding agents in isolated Docker or Podman containers. The main workflow is a user invoking `vp run`, which selects an agent and launches its container; optional configuration, profiles, providers, overlays, ACP, proxy tracking, and Herdr reporting extend that run. Separate commands manage skills and background tasks. The README documents additional analytics and comparison capabilities, but sampled sources do not establish their full implementation or wiring, so those links are intentionally limited.

Main entry points: [`src/vibepod/commands/run.py`](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/run.py) (Run command), [`src/vibepod/core/docker.py`](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/docker.py) (Container runtime), [`src/vibepod/cli.py`](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/cli.py) (Command router), [`src/vibepod/commands/task.py`](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/task.py) (Task commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Command router<br/>[cli.py]"]
end

subgraph group_run["Agent execution"]
  node_run_cmd["Run command<br/>[run.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_agents["Agent definitions<br/>[agents.py]"]
  node_docker["Container runtime<br/>[docker.py]"]
  node_launch["Launch preparation<br/>[launch.py]"]
  node_agent_container["Agent container"]
end

subgraph group_extensions["Run extensions"]
  node_overlay["Project overlays<br/>[overlay.py]"]
  node_profiles["Credential profiles<br/>[profiles.py]"]
  node_providers["Provider routing<br/>[provider_launch.py]"]
  node_acp["ACP adapter<br/>[acp.py]"]
  node_proxy["HTTP proxy metrics<br/>[proxy_filter.py]"]
  node_session_log[("Session logging<br/>[session_logger.py]")]
  node_herdr["Herdr reporting<br/>[herdr-report.js]"]
  node_analytics["Local analytics"]
end

subgraph group_management["Management features"]
  node_skills_cmd["Skills commands<br/>[skills.py]"]
  node_skills_engine["Skills engine<br/>[skills_engine.py]"]
  node_task_cmd["Task commands<br/>[task.py]"]
  node_task_store[("Task registry<br/>[tasks.py]")]
end

node_user(("CLI user"))
node_container_service["Docker / Podman"]
node_provider_service["Model endpoint"]
node_herdr_service["Herdr socket"]
node_skills_container["Skills container"]
node_editor(("ACP editor"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_run_cmd
node_cli -->|"dispatches"| node_skills_cmd
node_cli -->|"dispatches"| node_task_cmd
node_run_cmd -->|"reads"| node_config
node_run_cmd -->|"selects"| node_agents
node_run_cmd -->|"prepares"| node_launch
node_run_cmd -->|"launches through"| node_docker
node_docker -->|"controls"| node_container_service
node_container_service -->|"runs"| node_agent_container
node_run_cmd -->|"builds overlay"| node_overlay
node_run_cmd -->|"selects profile"| node_profiles
node_run_cmd -->|"prepares routing"| node_providers
node_providers -.->|"routes requests"| node_provider_service
node_run_cmd -->|"adapts protocol"| node_acp
node_editor -->|"connects"| node_acp
node_run_cmd -->|"configures tracking"| node_proxy
node_proxy -->|"tracks traffic"| node_analytics
node_run_cmd -->|"opens session"| node_session_log
node_run_cmd -->|"enables reporting"| node_herdr
node_herdr -.->|"reports state"| node_herdr_service
node_skills_cmd -->|"invokes"| node_skills_engine
node_skills_engine -->|"runs container via"| node_docker
node_docker -->|"runs"| node_skills_container
node_task_cmd -->|"records tasks"| node_task_store
node_task_cmd -->|"manages containers"| node_docker

click node_cli "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/cli.py"
click node_run_cmd "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/run.py"
click node_config "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/config.py"
click node_agents "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/agents.py"
click node_docker "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/docker.py"
click node_launch "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/launch.py"
click node_overlay "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/overlay.py"
click node_profiles "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/profiles.py"
click node_providers "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/provider_launch.py"
click node_acp "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/acp.py"
click node_proxy "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/proxy_filter.py"
click node_session_log "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/session_logger.py"
click node_herdr "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/resources/herdr/herdr-report.js"
click node_skills_cmd "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/skills.py"
click node_skills_engine "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/skills_engine.py"
click node_task_cmd "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/task.py"
click node_task_store "https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/tasks.py"
click node_analytics "https://github.com/vibepod/vibepod-cli/tree/main/src/vibepod/core"

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_cli,node_user toneBlue
class node_run_cmd,node_config,node_agents,node_docker,node_launch,node_agent_container toneAmber
class node_overlay,node_profiles,node_providers,node_acp,node_proxy,node_session_log,node_herdr,node_analytics toneMint
class node_skills_cmd,node_skills_engine,node_task_cmd,node_task_store toneRose
class node_container_service,node_provider_service,node_herdr_service,node_skills_container,node_editor toneIndigo
```

## Components

### CLI entry

- [Command router](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/cli.py): `src/vibepod/cli.py`

### Agent execution

- [Run command](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/run.py): `src/vibepod/commands/run.py`
- [Configuration](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/config.py): `src/vibepod/core/config.py`
- [Agent definitions](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/agents.py): `src/vibepod/core/agents.py`
- [Container runtime](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/docker.py): `src/vibepod/core/docker.py`
- [Launch preparation](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/launch.py): `src/vibepod/core/launch.py`
- **Agent container**

### Run extensions

- [Project overlays](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/overlay.py): `src/vibepod/core/overlay.py`
- [Credential profiles](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/profiles.py): `src/vibepod/core/profiles.py`
- [Provider routing](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/provider_launch.py): `src/vibepod/core/provider_launch.py`
- [ACP adapter](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/acp.py): `src/vibepod/core/acp.py`
- [HTTP proxy metrics](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/proxy_filter.py): `src/vibepod/core/proxy_filter.py`
- [Session logging](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/session_logger.py): `src/vibepod/core/session_logger.py`
- [Herdr reporting](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/resources/herdr/herdr-report.js): `src/vibepod/resources/herdr/herdr-report.js`
- [Local analytics](https://github.com/vibepod/vibepod-cli/tree/main/src/vibepod/core): `src/vibepod/core`

### Management features

- [Skills commands](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/skills.py): `src/vibepod/commands/skills.py`
- [Skills engine](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/skills_engine.py): `src/vibepod/core/skills_engine.py`
- [Task commands](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/commands/task.py): `src/vibepod/commands/task.py`
- [Task registry](https://github.com/vibepod/vibepod-cli/blob/main/src/vibepod/core/tasks.py): `src/vibepod/core/tasks.py`

### Other components

- **CLI user**
- **Docker / Podman**
- **Model endpoint**
- **Herdr socket**
- **Skills container**
- **ACP editor**

## Connections

- CLI user → Command router: invokes
- Command router → Run command: dispatches
- Command router → Skills commands: dispatches
- Command router → Task commands: dispatches
- Run command → Configuration: reads
- Run command → Agent definitions: selects
- Run command → Launch preparation: prepares
- Run command → Container runtime: launches through
- Container runtime → Docker / Podman: controls
- Docker / Podman → Agent container: runs
- Run command → Project overlays: builds overlay
- Run command → Credential profiles: selects profile
- Run command → Provider routing: prepares routing
- Provider routing → Model endpoint: routes requests
- Run command → ACP adapter: adapts protocol
- ACP editor → ACP adapter: connects
- Run command → HTTP proxy metrics: configures tracking
- HTTP proxy metrics → Local analytics: tracks traffic
- Run command → Session logging: opens session
- Run command → Herdr reporting: enables reporting
- Herdr reporting → Herdr socket: reports state
- Skills commands → Skills engine: invokes
- Skills engine → Container runtime: runs container via
- Container runtime → Skills container: runs
- Task commands → Task registry: records tasks
- Task commands → Container runtime: manages containers