How kiwizariudev/venty-cli works
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: agent.py Agent · executor.py Executor · crossplatform.py Cross-platform · plugins.py Plugins
Components 27
CLI runtime
Terminal entrypoint and presentation layer.
Core orchestration
LLM control flow, parsing, execution, memory, and background tasks.
- Agent · Builds prompts, streams model responses, and drives the assistant conversation.
core/agent.py - Prompt · Constructs provider-aware system prompts and model instructions.
core/prompt.py - JSON parser · Extracts structured JSON actions from model output.
core/jsonutil.py - Executor · Maps parsed actions to handlers and executes them locally.
core/executor.py - History · Tracks session context and short-lived dialogue state.
core/history.py - Memory · Persists longer-lived notes across sessions.
core/memory.py - Tasks · Expands model output into sequences of actions.
core/tasks.py - Scheduler · Stores and runs scheduled or repeating jobs.
core/scheduler.py
Action catalog
Built-in system and application actions exposed to the agent.
- Cross-platform · Portable action implementations shared across platforms.
actions/crossplatform.py - Windows · Windows-specific action implementations and boundary.
actions/windows.py - Files · File and sandbox-oriented operations.
actions/files.py - System · Processes, system info, power, control, and environment actions.
actions/system.py - Network · Browser, web fetch/search, SSH, and network-facing helpers.
actions/network.py - Dev tools · Git, encoding, compile, Docker, and package-manager actions.
actions/git.py - Config actions · Lets the assistant modify session settings and behavior.
actions/config_actions.py - 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 · Stored themes, keybinds, provider settings, and user configuration.
data/config/themes.json - Sandbox · Default isolated workspace for generated and edited files.
data/sandbox/.gitkeep - State data · Session logs, memory, cache, and scheduler job persistence.
data/runtime/.gitkeep
Extensions and bridge
Plugin loading, extension APIs, and the auxiliary web bridge.
- Plugins · Loads and manages extension plugins and their action catalog.
core/plugins.py - Plugin SDK · Defines the interface used by external plugins.
core/plugin_sdk.py - Bridge · Auxiliary Node/TypeScript server and browser assets for a local web UI bridge.
bridge/src/server.ts - API ext · Example server/client integration surface for external automation.
extensions/api/server.py
Connections 28
- 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.