# surya20062425/void-cli architecture

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

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

## Overview

Void is a terminal AI-agent CLI. Its main workflow takes a user’s chat request through the CLI, builds a model client, and runs an agent loop that can dispatch model-requested tools before returning text. Separate command surfaces manage providers and fallbacks, saved sessions, installed skills, and scheduled jobs. The README documents these capabilities; some command implementations and runtime wiring are unsampled, so their links are shown only where documented or indexed.

Main entry points: [`void/cli.py`](https://github.com/surya20062425/void-cli/blob/main/void/cli.py) (Command interface), [`void/providers.py`](https://github.com/surya20062425/void-cli/blob/main/void/providers.py) (Provider resolution), [`void/agent.py`](https://github.com/surya20062425/void-cli/blob/main/void/agent.py) (Agent loop), [`void/tools/registry.py`](https://github.com/surya20062425/void-cli/blob/main/void/tools/registry.py) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI experience"]
  node_cli["Command interface<br/>[cli.py]"]
  node_theme["Terminal theme<br/>[theme.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_loop["Agent loop<br/>[agent.py]"]
  node_tool_registry["Tool registry<br/>[registry.py]"]
  node_system_tools["System tools<br/>[system.py]"]
  node_web_tools["Web tools<br/>[web.py]"]
end

subgraph group_settings["Models and providers"]
  node_model_client["Model client<br/>[model.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_providers["Provider resolution<br/>[providers.py]"]
  node_model_commands["Model commands<br/>[model_cmd.py]"]
  node_auth_commands["Auth commands<br/>[auth_cmd.py]"]
  node_fallback_commands["Fallback commands<br/>[fallback_cmd.py]"]
end

subgraph group_management["Agent management"]
  node_skills["Skill management<br/>[skills_cmd.py]"]
  node_sessions_commands["Session commands<br/>[sessions_cmd.py]"]
  node_session_store[("Session store<br/>[sessions.py]")]
  node_cron_commands["Scheduled jobs<br/>[cron_cmd.py]"]
  node_cron_store[("Cron job store")]
end

node_user(("CLI user"))
node_model_service["OpenAI-compatible API"]
node_web_service["DuckDuckGo"]

node_user -->|"runs commands"| node_cli
node_cli -->|"starts chat"| node_agent_loop
node_agent_loop -->|"requests completion"| node_model_client
node_model_client -->|"calls API"| node_model_service
node_model_client -->|"reads defaults"| node_config
node_agent_loop -->|"gets schemas; dispatches calls"| node_tool_registry
node_agent_loop -->|"loads skill context"| node_skills
node_tool_registry -->|"discovers tools"| node_system_tools
node_tool_registry -->|"discovers tools"| node_web_tools
node_web_tools -->|"searches web"| node_web_service
node_cli -->|"reads and sets"| node_config
node_cli -->|"resolves provider"| node_providers
node_providers -->|"reads and saves"| node_config
node_cli -->|"routes model commands"| node_model_commands
node_cli -->|"routes auth commands"| node_auth_commands
node_cli -->|"routes fallback commands"| node_fallback_commands
node_auth_commands -->|"manages providers"| node_providers
node_fallback_commands -->|"manages fallback chain"| node_providers
node_model_commands -->|"manages models"| node_providers
node_cli -->|"routes sessions commands"| node_sessions_commands
node_sessions_commands -->|"reads and writes sessions"| node_session_store
node_cli -->|"routes skill commands"| node_skills
node_cli -->|"routes cron commands"| node_cron_commands
node_cron_commands -->|"reads and writes jobs"| node_cron_store
node_cli -->|"uses terminal styling"| node_theme

click node_cli "https://github.com/surya20062425/void-cli/blob/main/void/cli.py"
click node_theme "https://github.com/surya20062425/void-cli/blob/main/void/theme.py"
click node_agent_loop "https://github.com/surya20062425/void-cli/blob/main/void/agent.py"
click node_tool_registry "https://github.com/surya20062425/void-cli/blob/main/void/tools/registry.py"
click node_system_tools "https://github.com/surya20062425/void-cli/blob/main/void/tools/system.py"
click node_web_tools "https://github.com/surya20062425/void-cli/blob/main/void/tools/web.py"
click node_model_client "https://github.com/surya20062425/void-cli/blob/main/void/model.py"
click node_config "https://github.com/surya20062425/void-cli/blob/main/void/config.py"
click node_providers "https://github.com/surya20062425/void-cli/blob/main/void/providers.py"
click node_model_commands "https://github.com/surya20062425/void-cli/blob/main/void/commands/model_cmd.py"
click node_auth_commands "https://github.com/surya20062425/void-cli/blob/main/void/commands/auth_cmd.py"
click node_fallback_commands "https://github.com/surya20062425/void-cli/blob/main/void/commands/fallback_cmd.py"
click node_skills "https://github.com/surya20062425/void-cli/blob/main/void/commands/skills_cmd.py"
click node_sessions_commands "https://github.com/surya20062425/void-cli/blob/main/void/commands/sessions_cmd.py"
click node_session_store "https://github.com/surya20062425/void-cli/blob/main/void/sessions.py"
click node_cron_commands "https://github.com/surya20062425/void-cli/blob/main/void/commands/cron_cmd.py"
click node_cron_store "https://github.com/surya20062425/void-cli/tree/main/void/commands"

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_theme,node_user toneBlue
class node_agent_loop,node_tool_registry,node_system_tools,node_web_tools toneAmber
class node_model_client,node_config,node_providers,node_model_commands,node_auth_commands,node_fallback_commands,node_model_service toneMint
class node_skills,node_sessions_commands,node_session_store,node_cron_commands,node_cron_store toneRose
class node_web_service toneIndigo
```

## Components

### CLI experience

- [Command interface](https://github.com/surya20062425/void-cli/blob/main/void/cli.py): `void/cli.py`
- [Terminal theme](https://github.com/surya20062425/void-cli/blob/main/void/theme.py): `void/theme.py`

### Agent runtime

- [Agent loop](https://github.com/surya20062425/void-cli/blob/main/void/agent.py): `void/agent.py`
- [Tool registry](https://github.com/surya20062425/void-cli/blob/main/void/tools/registry.py): `void/tools/registry.py`
- [System tools](https://github.com/surya20062425/void-cli/blob/main/void/tools/system.py): `void/tools/system.py`
- [Web tools](https://github.com/surya20062425/void-cli/blob/main/void/tools/web.py): `void/tools/web.py`

### Models and providers

- [Model client](https://github.com/surya20062425/void-cli/blob/main/void/model.py): `void/model.py`
- [Configuration](https://github.com/surya20062425/void-cli/blob/main/void/config.py): `void/config.py`
- [Provider resolution](https://github.com/surya20062425/void-cli/blob/main/void/providers.py): `void/providers.py`
- [Model commands](https://github.com/surya20062425/void-cli/blob/main/void/commands/model_cmd.py): `void/commands/model_cmd.py`
- [Auth commands](https://github.com/surya20062425/void-cli/blob/main/void/commands/auth_cmd.py): `void/commands/auth_cmd.py`
- [Fallback commands](https://github.com/surya20062425/void-cli/blob/main/void/commands/fallback_cmd.py): `void/commands/fallback_cmd.py`

### Agent management

- [Skill management](https://github.com/surya20062425/void-cli/blob/main/void/commands/skills_cmd.py): `void/commands/skills_cmd.py`
- [Session commands](https://github.com/surya20062425/void-cli/blob/main/void/commands/sessions_cmd.py): `void/commands/sessions_cmd.py`
- [Session store](https://github.com/surya20062425/void-cli/blob/main/void/sessions.py): `void/sessions.py`
- [Scheduled jobs](https://github.com/surya20062425/void-cli/blob/main/void/commands/cron_cmd.py): `void/commands/cron_cmd.py`
- [Cron job store](https://github.com/surya20062425/void-cli/tree/main/void/commands): `void/commands`

### Other components

- **CLI user**
- **OpenAI-compatible API**
- **DuckDuckGo**

## Connections

- CLI user → Command interface: runs commands (evidence: `README.md`)
- Command interface → Agent loop: starts chat (evidence: `README.md`)
- Agent loop → Model client: requests completion (evidence: `void/agent.py`)
- Model client → OpenAI-compatible API: calls API (evidence: `void/model.py`)
- Model client → Configuration: reads defaults (evidence: `void/model.py`)
- Agent loop → Tool registry: gets schemas; dispatches calls (evidence: `void/agent.py`)
- Agent loop → Skill management: loads skill context (evidence: `void/agent.py`)
- Tool registry → System tools: discovers tools (evidence: `void/tools/registry.py`)
- Tool registry → Web tools: discovers tools (evidence: `void/tools/registry.py`)
- Web tools → DuckDuckGo: searches web (evidence: `README.md`)
- Command interface → Configuration: reads and sets (evidence: `void/cli.py`)
- Command interface → Provider resolution: resolves provider (evidence: `void/cli.py`)
- Provider resolution → Configuration: reads and saves (evidence: `void/providers.py`)
- Command interface → Model commands: routes model commands (evidence: `README.md`)
- Command interface → Auth commands: routes auth commands (evidence: `README.md`)
- Command interface → Fallback commands: routes fallback commands (evidence: `README.md`)
- Auth commands → Provider resolution: manages providers (evidence: `void/commands/auth_cmd.py`)
- Fallback commands → Provider resolution: manages fallback chain (evidence: `void/commands/fallback_cmd.py`)
- Model commands → Provider resolution: manages models (evidence: `README.md`)
- Command interface → Session commands: routes sessions commands (evidence: `README.md`)
- Session commands → Session store: reads and writes sessions (evidence: `void/commands/sessions_cmd.py`)
- Command interface → Skill management: routes skill commands (evidence: `README.md`)
- Command interface → Scheduled jobs: routes cron commands (evidence: `README.md`)
- Scheduled jobs → Cron job store: reads and writes jobs (evidence: `README.md`)
- Command interface → Terminal theme: uses terminal styling (evidence: `void/cli.py`)
