# huzaifaashraf13/penzer-cli architecture

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

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

## Overview

Penzer CLI is an interactive shell agent: a user submits a task, the CLI runs the agent loop, the agent consults the model and memory, and tool execution produces results for the terminal. Its major branches include model configuration, reusable skills and plugins, persistent memory, browser automation, and terminal/file operations. The graph follows relationships named by the SOURCE INDEX and README; unsampled subsystem links are omitted where their callers cannot be verified.

Main entry points: [`agent/agent.py`](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/agent.py) (Agent orchestration), [`agent/penzermodule/execution.py`](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/penzermodule/execution.py) (Tool dispatch), [`cli.py`](https://github.com/huzaifaashraf13/penzer-cli/blob/main/cli.py) (Interactive CLI), [`tools/browser/tool.py`](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/tool.py) (Browser tool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["Interactive CLI<br/>[cli.py]"]
  node_config["Settings and credentials<br/>[config.py]"]
  node_terminal_ui["Terminal interface<br/>[terminal.py]"]
end

subgraph group_agent["Agent reasoning"]
  node_agent_loop["Agent orchestration<br/>[agent.py]"]
  node_llm["LLM interface<br/>[llm.py]"]
  node_prompts["System prompts<br/>[system_prompts.py]"]
  node_execution["Tool dispatch<br/>[execution.py]"]
  node_skills["Skill loading and runtime<br/>[loader.py]"]
end

subgraph group_memory["Persistent memory"]
  node_memory_api["Memory orchestration<br/>[memory.py]"]
  node_memory_core["Memory semantics<br/>[memory_core.py]"]
  node_memory_graph["Memory graph<br/>[memory_graph.py]"]
  node_memory_storage[("Memory storage<br/>[memory_storage.py]")]
end

subgraph group_tools["Tools and execution"]
  node_plugins["Plugin discovery<br/>[__init__.py]"]
  node_executor["Safe command executor<br/>[executor.py]"]
  node_terminal_tool["Terminal tool<br/>[tool.py]"]
  node_file_editor["File editor<br/>[tool.py]"]
end

subgraph group_browser["Browser automation"]
  node_browser_tool["Browser tool<br/>[tool.py]"]
  node_browser_runtime["Browser runtime<br/>[runtime.py]"]
  node_web_search["Web search<br/>[search.py]"]
end

node_user(("Shell user"))
node_model_service{{"Local or cloud model"}}
node_chrome{{"Chrome browser"}}
node_web{{"Web search providers"}}

node_user -->|"submits tasks"| node_cli
node_cli -->|"renders interface"| node_terminal_ui
node_cli -->|"loads settings"| node_config
node_cli -->|"starts agent"| node_agent_loop
node_cli -->|"accesses memory"| node_memory_api
node_agent_loop -->|"requests completions"| node_llm
node_agent_loop -->|"builds prompts"| node_prompts
node_agent_loop -->|"dispatches tools"| node_execution
node_agent_loop -->|"uses skills"| node_skills
node_agent_loop -->|"loads plugins"| node_plugins
node_agent_loop -->|"reads and writes"| node_memory_api
node_llm -->|"calls model API"| node_model_service
node_execution -->|"runs commands"| node_executor
node_execution -->|"dispatches plugins"| node_plugins
node_execution -->|"dispatches terminal"| node_terminal_tool
node_execution -->|"dispatches edits"| node_file_editor
node_execution -->|"dispatches browser"| node_browser_tool
node_memory_api -->|"uses semantics"| node_memory_core
node_memory_api -->|"uses graph"| node_memory_graph
node_memory_core -->|"reads and writes"| node_memory_storage
node_memory_graph -->|"reads and writes"| node_memory_storage
node_terminal_tool -->|"executes commands"| node_executor
node_browser_tool -->|"uses runtime"| node_browser_runtime
node_browser_tool -->|"searches web"| node_web_search
node_browser_tool -->|"controls browser"| node_chrome
node_web_search -->|"queries providers"| node_web

click node_cli "https://github.com/huzaifaashraf13/penzer-cli/blob/main/cli.py"
click node_config "https://github.com/huzaifaashraf13/penzer-cli/blob/main/config.py"
click node_terminal_ui "https://github.com/huzaifaashraf13/penzer-cli/blob/main/ui/terminal.py"
click node_agent_loop "https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/agent.py"
click node_llm "https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/llm.py"
click node_prompts "https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/system_prompts.py"
click node_execution "https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/penzermodule/execution.py"
click node_skills "https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/skills/loader.py"
click node_plugins "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/plugins/__init__.py"
click node_memory_api "https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory.py"
click node_memory_core "https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_core.py"
click node_memory_graph "https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_graph.py"
click node_memory_storage "https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_storage.py"
click node_executor "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/executor.py"
click node_terminal_tool "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/terminal/tool.py"
click node_file_editor "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/file_editor/tool.py"
click node_browser_tool "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/tool.py"
click node_browser_runtime "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/runtime.py"
click node_web_search "https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/search.py"

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_config,node_terminal_ui,node_user,node_chrome toneBlue
class node_agent_loop,node_llm,node_prompts,node_execution,node_skills toneAmber
class node_memory_api,node_memory_core,node_memory_graph,node_memory_storage toneMint
class node_plugins,node_executor,node_terminal_tool,node_file_editor toneRose
class node_browser_tool,node_browser_runtime,node_web_search,node_model_service,node_web toneIndigo
```

## Components

### CLI and configuration

- [Interactive CLI](https://github.com/huzaifaashraf13/penzer-cli/blob/main/cli.py): `cli.py`
- [Settings and credentials](https://github.com/huzaifaashraf13/penzer-cli/blob/main/config.py): `config.py`
- [Terminal interface](https://github.com/huzaifaashraf13/penzer-cli/blob/main/ui/terminal.py): `ui/terminal.py`

### Agent reasoning

- [Agent orchestration](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/agent.py): `agent/agent.py`
- [LLM interface](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/llm.py): `agent/llm.py`
- [System prompts](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/system_prompts.py): `agent/system_prompts.py`
- [Tool dispatch](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/penzermodule/execution.py): `agent/penzermodule/execution.py`
- [Skill loading and runtime](https://github.com/huzaifaashraf13/penzer-cli/blob/main/agent/skills/loader.py): `agent/skills/loader.py`

### Persistent memory

- [Memory orchestration](https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory.py): `session/memory.py`
- [Memory semantics](https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_core.py): `session/memory_core.py`
- [Memory graph](https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_graph.py): `session/memory_graph.py`
- [Memory storage](https://github.com/huzaifaashraf13/penzer-cli/blob/main/session/memory_storage.py): `session/memory_storage.py`

### Tools and execution

- [Plugin discovery](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/plugins/__init__.py): `tools/plugins/__init__.py`
- [Safe command executor](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/executor.py): `tools/executor.py`
- [Terminal tool](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/terminal/tool.py): `tools/terminal/tool.py`
- [File editor](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/file_editor/tool.py): `tools/file_editor/tool.py`

### Browser automation

- [Browser tool](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/tool.py): `tools/browser/tool.py`
- [Browser runtime](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/runtime.py): `tools/browser/runtime.py`
- [Web search](https://github.com/huzaifaashraf13/penzer-cli/blob/main/tools/browser/search.py): `tools/browser/search.py`

### Other components

- **Shell user**
- **Local or cloud model**
- **Chrome browser**
- **Web search providers**

## Connections

- Shell user → Interactive CLI: submits tasks
- Interactive CLI → Terminal interface: renders interface (evidence: `cli.py`)
- Interactive CLI → Settings and credentials: loads settings (evidence: `cli.py`)
- Interactive CLI → Agent orchestration: starts agent (evidence: `cli.py`)
- Interactive CLI → Memory orchestration: accesses memory (evidence: `cli.py`)
- Agent orchestration → LLM interface: requests completions (evidence: `agent/agent.py`)
- Agent orchestration → System prompts: builds prompts (evidence: `agent/agent.py`)
- Agent orchestration → Tool dispatch: dispatches tools (evidence: `agent/agent.py`)
- Agent orchestration → Skill loading and runtime: uses skills (evidence: `agent/agent.py`)
- Agent orchestration → Plugin discovery: loads plugins (evidence: `agent/agent.py`)
- Agent orchestration → Memory orchestration: reads and writes (evidence: `agent/agent.py`)
- LLM interface → Local or cloud model: calls model API
- Tool dispatch → Safe command executor: runs commands (evidence: `agent/penzermodule/execution.py`)
- Tool dispatch → Plugin discovery: dispatches plugins (evidence: `agent/penzermodule/execution.py`)
- Tool dispatch → Terminal tool: dispatches terminal (evidence: `agent/penzermodule/execution.py`)
- Tool dispatch → File editor: dispatches edits (evidence: `agent/penzermodule/execution.py`)
- Tool dispatch → Browser tool: dispatches browser (evidence: `agent/penzermodule/execution.py`)
- Memory orchestration → Memory semantics: uses semantics (evidence: `session/memory.py`)
- Memory orchestration → Memory graph: uses graph (evidence: `session/memory.py`)
- Memory semantics → Memory storage: reads and writes (evidence: `session/memory_core.py`)
- Memory graph → Memory storage: reads and writes (evidence: `session/memory_graph.py`)
- Terminal tool → Safe command executor: executes commands (evidence: `tools/terminal/tool.py`)
- Browser tool → Browser runtime: uses runtime (evidence: `tools/browser/tool.py`)
- Browser tool → Web search: searches web (evidence: `tools/browser/tool.py`)
- Browser tool → Chrome browser: controls browser
- Web search → Web search providers: queries providers (evidence: `tools/browser/search.py`)
