# kiwizariudev/venty-cli architecture

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

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

## Overview

1. **Primary runtime is a Python CLI assistant**
   - `cli.py` is the user-facing entry point.
   - The main interaction loop is terminal-based: user text goes into the agent, and the assistant responds by choosing an action to execute locally.
   - `ui/` only handles presentation concerns such as colors, banners, and command formatting.

2. **Core control flow is: prompt → LLM → JSON → executor → OS**
   - `core/agent.py` talks to the model provider and supports streaming responses.
   - `core/jsonutil.py` extracts structured JSON from model output, which is critical because the LLM does not return plain text instructions.
   - `core/executor.py` maps the parsed action into the actual Python action handler and runs it.
   - This is the central architecture boundary: natural language is translated into deterministic local operations.

3. **The action layer is the main capability surface**
   - `actions/` contains the built-in operation catalog, split by domain: files, processes, networking, browser, web fetch/search, git, encoding, clipboard, system info, power, Windows registry, and more.
   - These modules are effectively adapters from abstract action names to concrete platform/system APIs.
   - `actions/crossplatform.py` and `actions/windows.py` define the main portability boundary between shared actions and Windows-specific ones.

4. **Config-changing actions are first-class**
   - `actions/config_actions.py` lets the agent modify runtime settings from within the assistant itself.
   - This is not just a static config file approach; the model can influence behavior such as streaming, provider choice, working directory, and token limits during a session.
   - The architecture therefore includes self-modifying control paths, but still routes them through a dedicated config subsystem.

5. **Persistent state is separated from code under `data/`**
   - `data/config/` stores user settings, themes, API/provider configuration, and keybinds.
   - `data/sandbox/` is the default working area for file actions, which acts as a containment boundary for generated or edited files.
   - `data/memory/`, `data/logs/`, `data/cache/`, and `data/scheduler/` hold session history, notes, logs, action usage stats, and scheduled jobs.
   - This separation is important for diagrams because code, mutable runtime state, and user content are intentionally isolated.

6. **Conversation and memory are distinct subsystems**
   - `core/history.py` tracks session conversation context.
   - `core/memory.py` persists longer-lived notes that survive across sessions.
   - The assistant therefore has two memory scopes: transient dialogue state and durable user memory.

7. **Task planning and scheduling introduce asynchronous control**
   - `core/tasks.py` handles multi-step plans returned by the model, so one prompt can expand into a sequence of actions.
   - `core/scheduler.py` stores and executes delayed or repeating jobs.
   - These are separate from the immediate request/response loop and should be treated as background orchestration paths in the architecture.

8. **Plugins extend the action catalog without changing core code**
   - `core/plugins.py` loads plugins from `extensions/plugins/`.
   - `core/plugin_sdk.py` provides the extension contract.
   - Bundled plugins add dev tools, system info, clipboard history, media controls, notes, browser helpers, and fun actions.
   - The plugin boundary is important: core capabilities remain stable, while plugins add domain-specific actions and can be hot-reloaded.

9. **There is a web/bridge subsystem alongside the CLI**
   - `bridge/` contains a separate Node/TypeScript server plus static browser assets.
   - `bridge/src/server.ts` and `bridge/public/` suggest a lightweight web UI or local bridge service, independent of the main Python runtime.
   - `extensions/api/` also provides API server/client examples, implying an external integration surface beyond the terminal app.
   - In a diagram, this should appear as an auxiliary interface layer rather than the main execution path.

10. **A native component exists for platform-specific or performance-sensitive work**
   - `engine/venty_engine.cpp` and its build scripts indicate a compiled C++ component.
   - `core/native.py` likely connects Python code to that native layer.
   - This is a separate boundary from pure Python modules and matters if diagramming cross-language dependencies.

11. **Provider integration is external and pluggable**
   - The assistant supports multiple LLM providers and both cloud and local endpoints.
   - `core/prompt.py` builds the system prompt differently depending on provider constraints, including shortened prompts for local models.
   - The external network boundary here is the model API; everything after that is internal parsing and execution.

12. **Configuration and management are exposed as separate tools**
   - `setup.py` is the onboarding wizard for API keys, models, and build/setup tasks.
   - `config.py` is a richer configuration management UI.
   - The repo also includes CLI commands for viewing state, logs, plugins, jobs, aliases, and memory, which means observability and admin flows are built into the product rather than being external tooling.

13. **Testing is organized around the core logic**
   - `tests/` covers actions, agent behavior, config, JSON parsing, and memory.
   - That suggests the most important stable contracts are: LLM output parsing, action execution, config persistence, and memory handling.
   - For an architecture diagram, these are the riskiest seams and the best places to show explicit boundaries.

14. **Operationally, this is a local-assistant system with strong OS reach**
   - The design is centered on local machine control: file system, shell/processes, browser, network, registry, power, and clipboard.
   - Because those actions can be destructive or system-wide, the sandbox directory and trusted-provider model are part of the architecture, not just UX details.
   - The overall shape is a command-and-control desktop assistant with persistent state, extensible actions, and optional web/native companions.

Main entry points: [`core/agent.py`](https://github.com/kiwizariudev/venty-cli/blob/main/core/agent.py) (Agent), [`core/executor.py`](https://github.com/kiwizariudev/venty-cli/blob/main/core/executor.py) (Executor), [`actions/crossplatform.py`](https://github.com/kiwizariudev/venty-cli/blob/main/actions/crossplatform.py) (Cross-platform), [`core/plugins.py`](https://github.com/kiwizariudev/venty-cli/blob/main/core/plugins.py) (Plugins)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI runtime"]
  node_cli_py["CLI<br/>Python entrypoint<br/>[cli.py]"]
  node_ui_mod["UI<br/>presentation<br/>[colors.py]"]
end

subgraph group_grp_core["Core orchestration"]
  node_agent["Agent<br/>LLM loop<br/>[agent.py]"]
  node_prompt["Prompt<br/>[prompt.py]"]
  node_jsonutil["JSON parser<br/>output parsing<br/>[jsonutil.py]"]
  node_executor["Executor<br/>action dispatcher<br/>[executor.py]"]
  node_history["History<br/>conversation state<br/>[history.py]"]
  node_memory[("Memory<br/>durable notes<br/>[memory.py]")]
  node_tasks["Tasks<br/>multi-step plans<br/>[tasks.py]"]
  node_scheduler["Scheduler<br/>delayed jobs<br/>[scheduler.py]"]
end

subgraph group_grp_actions["Action catalog"]
  node_crossplatform["Cross-platform<br/>shared actions<br/>[crossplatform.py]"]
  node_windows["Windows<br/>platform actions<br/>[windows.py]"]
  node_files["Files<br/>[files.py]"]
  node_system_actions["System<br/>OS actions<br/>[system.py]"]
  node_net_actions["Network<br/>[network.py]"]
  node_dev_actions["Dev tools<br/>dev actions<br/>[git.py]"]
  node_config_actions["Config actions<br/>runtime config<br/>[config_actions.py]"]
  node_registry["Registry<br/>[registry.py]"]
end

subgraph group_grp_state["State and config"]
  node_data_config[("Config data<br/>persistent settings<br/>[themes.json]")]
  node_data_sandbox[("Sandbox<br/>working area<br/>[.gitkeep]")]
  node_data_memory[("State data<br/>runtime stores<br/>[.gitkeep]")]
end

subgraph group_grp_ext["Extensions and bridge"]
  node_plugins["Plugins<br/>plugin loader<br/>[plugins.py]"]
  node_plugin_sdk["Plugin SDK<br/>extension contract<br/>[plugin_sdk.py]"]
  node_bridge["Bridge<br/>[server.ts]"]
  node_api_ext["API ext<br/>external API<br/>[server.py]"]
end

subgraph group_grp_native["Native layer"]
  node_native["Native<br/>C++ bridge<br/>[native.py]"]
  node_engine_cpp["Engine<br/>C++ core<br/>[venty_engine.cpp]"]
end

node_cli_py -->|"renders"| node_ui_mod
node_cli_py -->|"starts"| node_agent
node_agent -->|"builds"| node_prompt
node_agent -->|"parses"| node_jsonutil
node_agent -->|"reads/writes"| node_history
node_agent -->|"dispatches"| node_executor
node_executor -->|"calls"| node_crossplatform
node_executor -->|"calls"| node_windows
node_executor -->|"calls"| node_config_actions
node_executor -->|"plans"| node_tasks
node_executor -->|"queues"| node_scheduler
node_crossplatform -->|"includes"| node_files
node_crossplatform -->|"includes"| node_system_actions
node_crossplatform -->|"includes"| node_net_actions
node_crossplatform -->|"includes"| node_dev_actions
node_crossplatform -->|"delegates"| node_registry
node_windows -->|"uses"| node_registry
node_agent -->|"loads"| node_plugins
node_plugins -->|"implements"| node_plugin_sdk
node_plugins -.->|"exposes"| node_api_ext
node_plugins -.->|"extends"| node_bridge
node_native -->|"bridges"| node_engine_cpp
node_agent -.->|"may use"| node_native
node_history -->|"persists"| node_data_memory
node_memory -->|"persists"| node_data_memory
node_config_actions -->|"updates"| node_data_config
node_files -->|"targets"| node_data_sandbox
node_scheduler -->|"stores"| node_data_memory

click node_cli_py "https://github.com/kiwizariudev/venty-cli/blob/main/cli.py"
click node_ui_mod "https://github.com/kiwizariudev/venty-cli/blob/main/ui/colors.py"
click node_agent "https://github.com/kiwizariudev/venty-cli/blob/main/core/agent.py"
click node_prompt "https://github.com/kiwizariudev/venty-cli/blob/main/core/prompt.py"
click node_jsonutil "https://github.com/kiwizariudev/venty-cli/blob/main/core/jsonutil.py"
click node_executor "https://github.com/kiwizariudev/venty-cli/blob/main/core/executor.py"
click node_history "https://github.com/kiwizariudev/venty-cli/blob/main/core/history.py"
click node_memory "https://github.com/kiwizariudev/venty-cli/blob/main/core/memory.py"
click node_tasks "https://github.com/kiwizariudev/venty-cli/blob/main/core/tasks.py"
click node_scheduler "https://github.com/kiwizariudev/venty-cli/blob/main/core/scheduler.py"
click node_crossplatform "https://github.com/kiwizariudev/venty-cli/blob/main/actions/crossplatform.py"
click node_windows "https://github.com/kiwizariudev/venty-cli/blob/main/actions/windows.py"
click node_files "https://github.com/kiwizariudev/venty-cli/blob/main/actions/files.py"
click node_system_actions "https://github.com/kiwizariudev/venty-cli/blob/main/actions/system.py"
click node_net_actions "https://github.com/kiwizariudev/venty-cli/blob/main/actions/network.py"
click node_dev_actions "https://github.com/kiwizariudev/venty-cli/blob/main/actions/git.py"
click node_config_actions "https://github.com/kiwizariudev/venty-cli/blob/main/actions/config_actions.py"
click node_registry "https://github.com/kiwizariudev/venty-cli/blob/main/actions/registry.py"
click node_plugins "https://github.com/kiwizariudev/venty-cli/blob/main/core/plugins.py"
click node_plugin_sdk "https://github.com/kiwizariudev/venty-cli/blob/main/core/plugin_sdk.py"
click node_bridge "https://github.com/kiwizariudev/venty-cli/blob/main/bridge/src/server.ts"
click node_api_ext "https://github.com/kiwizariudev/venty-cli/blob/main/extensions/api/server.py"
click node_native "https://github.com/kiwizariudev/venty-cli/blob/main/core/native.py"
click node_engine_cpp "https://github.com/kiwizariudev/venty-cli/blob/main/engine/venty_engine.cpp"
click node_data_config "https://github.com/kiwizariudev/venty-cli/blob/main/data/config/themes.json"
click node_data_sandbox "https://github.com/kiwizariudev/venty-cli/blob/main/data/sandbox/.gitkeep"
click node_data_memory "https://github.com/kiwizariudev/venty-cli/blob/main/data/runtime/.gitkeep"

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_py,node_ui_mod toneBlue
class node_agent,node_prompt,node_jsonutil,node_executor,node_history,node_memory,node_tasks,node_scheduler toneAmber
class node_crossplatform,node_windows,node_files,node_system_actions,node_net_actions,node_dev_actions,node_config_actions,node_registry toneMint
class node_data_config,node_data_sandbox,node_data_memory toneRose
class node_plugins,node_plugin_sdk,node_bridge,node_api_ext toneIndigo
class node_native,node_engine_cpp toneTeal
```

## Components

### CLI runtime

Terminal entrypoint and presentation layer.

- [CLI](https://github.com/kiwizariudev/venty-cli/blob/main/cli.py): Python entrypoint · User-facing terminal assistant entrypoint. · `cli.py`
- [UI](https://github.com/kiwizariudev/venty-cli/blob/main/ui/colors.py): presentation · Colors, banners, and command formatting for terminal output. · `ui/colors.py`

### Core orchestration

LLM control flow, parsing, execution, memory, and background tasks.

- [Agent](https://github.com/kiwizariudev/venty-cli/blob/main/core/agent.py): LLM loop · Builds prompts, streams model responses, and drives the assistant conversation. · `core/agent.py`
- [Prompt](https://github.com/kiwizariudev/venty-cli/blob/main/core/prompt.py): prompt builder · Constructs provider-aware system prompts and model instructions. · `core/prompt.py`
- [JSON parser](https://github.com/kiwizariudev/venty-cli/blob/main/core/jsonutil.py): output parsing · Extracts structured JSON actions from model output. · `core/jsonutil.py`
- [Executor](https://github.com/kiwizariudev/venty-cli/blob/main/core/executor.py): action dispatcher · Maps parsed actions to handlers and executes them locally. · `core/executor.py`
- [History](https://github.com/kiwizariudev/venty-cli/blob/main/core/history.py): conversation state · Tracks session context and short-lived dialogue state. · `core/history.py`
- [Memory](https://github.com/kiwizariudev/venty-cli/blob/main/core/memory.py): durable notes · Persists longer-lived notes across sessions. · `core/memory.py`
- [Tasks](https://github.com/kiwizariudev/venty-cli/blob/main/core/tasks.py): multi-step plans · Expands model output into sequences of actions. · `core/tasks.py`
- [Scheduler](https://github.com/kiwizariudev/venty-cli/blob/main/core/scheduler.py): delayed jobs · Stores and runs scheduled or repeating jobs. · `core/scheduler.py`

### Action catalog

Built-in system and application actions exposed to the agent.

- [Cross-platform](https://github.com/kiwizariudev/venty-cli/blob/main/actions/crossplatform.py): shared actions · Portable action implementations shared across platforms. · `actions/crossplatform.py`
- [Windows](https://github.com/kiwizariudev/venty-cli/blob/main/actions/windows.py): platform actions · Windows-specific action implementations and boundary. · `actions/windows.py`
- [Files](https://github.com/kiwizariudev/venty-cli/blob/main/actions/files.py): filesystem actions · File and sandbox-oriented operations. · `actions/files.py`
- [System](https://github.com/kiwizariudev/venty-cli/blob/main/actions/system.py): OS actions · Processes, system info, power, control, and environment actions. · `actions/system.py`
- [Network](https://github.com/kiwizariudev/venty-cli/blob/main/actions/network.py): network/browser actions · Browser, web fetch/search, SSH, and network-facing helpers. · `actions/network.py`
- [Dev tools](https://github.com/kiwizariudev/venty-cli/blob/main/actions/git.py): dev actions · Git, encoding, compile, Docker, and package-manager actions. · `actions/git.py`
- [Config actions](https://github.com/kiwizariudev/venty-cli/blob/main/actions/config_actions.py): runtime config · Lets the assistant modify session settings and behavior. · `actions/config_actions.py`
- [Registry](https://github.com/kiwizariudev/venty-cli/blob/main/actions/registry.py): Windows registry · Registry operations for Windows-specific system control. · `actions/registry.py`

### State and config

Persistent user settings, runtime state, logs, and sandboxed data.

- [Config data](https://github.com/kiwizariudev/venty-cli/blob/main/data/config/themes.json): persistent settings · Stored themes, keybinds, provider settings, and user configuration. · `data/config/themes.json`
- [Sandbox](https://github.com/kiwizariudev/venty-cli/blob/main/data/sandbox/.gitkeep): working area · Default isolated workspace for generated and edited files. · `data/sandbox/.gitkeep`
- [State data](https://github.com/kiwizariudev/venty-cli/blob/main/data/runtime/.gitkeep): runtime stores · Session logs, memory, cache, and scheduler job persistence. · `data/runtime/.gitkeep`

### Extensions and bridge

Plugin loading, extension APIs, and the auxiliary web bridge.

- [Plugins](https://github.com/kiwizariudev/venty-cli/blob/main/core/plugins.py): plugin loader · Loads and manages extension plugins and their action catalog. · `core/plugins.py`
- [Plugin SDK](https://github.com/kiwizariudev/venty-cli/blob/main/core/plugin_sdk.py): extension contract · Defines the interface used by external plugins. · `core/plugin_sdk.py`
- [Bridge](https://github.com/kiwizariudev/venty-cli/blob/main/bridge/src/server.ts): web bridge · Auxiliary Node/TypeScript server and browser assets for a local web UI bridge. · `bridge/src/server.ts`
- [API ext](https://github.com/kiwizariudev/venty-cli/blob/main/extensions/api/server.py): external API · Example server/client integration surface for external automation. · `extensions/api/server.py`

### Native layer

Compiled component and Python bridge for platform-specific work.

- [Native](https://github.com/kiwizariudev/venty-cli/blob/main/core/native.py): C++ bridge · Python-facing native component for platform-specific or performance-sensitive work. · `core/native.py`
- [Engine](https://github.com/kiwizariudev/venty-cli/blob/main/engine/venty_engine.cpp): C++ core · Compiled native implementation backing the Python bridge. · `engine/venty_engine.cpp`

## Connections

- CLI → UI: renders · CLI uses UI helpers for presentation.
- CLI → Agent: starts · CLI enters the main assistant loop.
- Agent → Prompt: builds · Prepares provider-aware model instructions.
- Agent → JSON parser: parses · Converts model output into structured actions.
- Agent → History: reads/writes · Uses session conversation context.
- Agent → Executor: dispatches · Sends parsed actions for execution.
- Executor → Cross-platform: calls · Resolves shared action handlers.
- Executor → Windows: calls · Routes Windows-specific operations.
- Executor → Config actions: calls · Allows the assistant to change runtime settings.
- Executor → Tasks: plans · Supports multi-step action sequences.
- Executor → Scheduler: queues · Creates or runs delayed jobs.
- Cross-platform → Files: includes · Filesystem operations are a major shared capability.
- Cross-platform → System: includes · Shared OS and process control actions.
- Cross-platform → Network: includes · Shared network and browser-facing actions.
- Cross-platform → Dev tools: includes · Shared developer workflow actions.
- Cross-platform → Registry: delegates · Windows registry support sits at the platform boundary.
- Windows → Registry: uses · Windows module exposes registry and platform APIs.
- Agent → Plugins: loads · Extends capabilities through plugins.
- Plugins → Plugin SDK: implements · Plugins conform to the extension contract.
- Plugins → API ext: exposes · Provides external integration examples and surfaces.
- Plugins → Bridge: extends · Web bridge and plugin ecosystem complement the CLI.
- Native → Engine: bridges · Python native layer connects to the compiled engine.
- Agent → Native: may use · Assistant can leverage native capabilities when needed.
- History → State data: persists · Session state is written to runtime storage.
- Memory → State data: persists · Durable notes are stored separately from code.
- Config actions → Config data: updates · Runtime config changes are persisted to user settings.
- Files → Sandbox: targets · File actions default to the sandboxed workspace.
- Scheduler → State data: stores · Scheduled jobs are persisted under runtime data.
