# armaganakcann/pocket-agent architecture

> Architecture diagram of the GitHub repository armaganakcann/pocket-agent, 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/armaganakcann/pocket-agent
- Repository: https://github.com/armaganakcann/pocket-agent

## Overview

pocket-agent is a local-first, tool-calling assistant for llama.cpp, with an optional remote fallback for complex requests. A user submits a request through the CLI; the loop chooses a backend, sends prompted conversation to it, parses a possible tool call, dispatches one tool, and feeds its result back until the model answers or reaches the step limit. Tools cover Termux notifications, speech and battery status, plus guarded file and shell access. Source excerpts show the runtime wiring; roadmap items such as Telegram, RAG and voice input are not implemented capabilities.

Main entry points: [`agent.py`](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py) (Agent loop), [`tools.py`](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py) (Tool dispatcher), [`prompts.py`](https://github.com/armaganakcann/pocket-agent/blob/main/prompts.py) (Prompt and schema)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI<br/>[agent.py]"]
end

subgraph group_agent["Agent runtime"]
  node_loop["Agent loop<br/>[agent.py]"]
  node_router["Complexity router<br/>[agent.py]"]
  node_parser["Tool-call parser<br/>[agent.py]"]
  node_backend["LLM backend<br/>[agent.py]"]
  node_prompt["Prompt and schema<br/>[prompts.py]"]
end

subgraph group_tools["Tools and device access"]
  node_dispatch["Tool dispatcher<br/>[tools.py]"]
  node_notifications["Notifications<br/>[tools.py]"]
  node_speech["Text to speech<br/>[tools.py]"]
  node_file_tools["File access<br/>[tools.py]"]
  node_shell_tool["Shell tool<br/>[tools.py]"]
  node_battery_tool["Battery status<br/>[tools.py]"]
end

node_user(("User"))
node_local_server["llama.cpp server"]
node_remote_api["Remote API"]
node_termux["Termux APIs"]
node_filesystem[("Home filesystem")]
node_shell["System shell"]

node_user -->|"submits request"| node_cli
node_cli -->|"runs request"| node_loop
node_loop -->|"checks complexity"| node_router
node_loop -->|"uses instructions"| node_prompt
node_loop -->|"sends messages"| node_backend
node_backend -->|"posts chat"| node_local_server
node_router -.->|"selects fallback"| node_remote_api
node_loop -->|"parses reply"| node_parser
node_loop -->|"dispatches tool"| node_dispatch
node_dispatch -->|"invokes"| node_notifications
node_dispatch -->|"invokes"| node_speech
node_dispatch -->|"invokes"| node_file_tools
node_dispatch -->|"invokes"| node_shell_tool
node_dispatch -->|"invokes"| node_battery_tool
node_notifications -->|"runs command"| node_termux
node_speech -->|"runs command"| node_termux
node_battery_tool -->|"runs command"| node_termux
node_file_tools -->|"reads and writes"| node_filesystem
node_shell_tool -->|"runs command"| node_shell

click node_cli "https://github.com/armaganakcann/pocket-agent/blob/main/agent.py"
click node_loop "https://github.com/armaganakcann/pocket-agent/blob/main/agent.py"
click node_router "https://github.com/armaganakcann/pocket-agent/blob/main/agent.py"
click node_parser "https://github.com/armaganakcann/pocket-agent/blob/main/agent.py"
click node_backend "https://github.com/armaganakcann/pocket-agent/blob/main/agent.py"
click node_prompt "https://github.com/armaganakcann/pocket-agent/blob/main/prompts.py"
click node_dispatch "https://github.com/armaganakcann/pocket-agent/blob/main/tools.py"
click node_notifications "https://github.com/armaganakcann/pocket-agent/blob/main/tools.py"
click node_speech "https://github.com/armaganakcann/pocket-agent/blob/main/tools.py"
click node_file_tools "https://github.com/armaganakcann/pocket-agent/blob/main/tools.py"
click node_shell_tool "https://github.com/armaganakcann/pocket-agent/blob/main/tools.py"
click node_battery_tool "https://github.com/armaganakcann/pocket-agent/blob/main/tools.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_user toneBlue
class node_loop,node_router,node_parser,node_backend,node_prompt,node_filesystem toneAmber
class node_dispatch,node_notifications,node_speech,node_file_tools,node_shell_tool,node_battery_tool,node_local_server,node_remote_api,node_termux toneMint
class node_shell toneIndigo
```

## Components

### User interaction

- [CLI](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py): `agent.py`

### Agent runtime

- [Agent loop](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py): `agent.py`
- [Complexity router](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py): `agent.py`
- [Tool-call parser](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py): `agent.py`
- [LLM backend](https://github.com/armaganakcann/pocket-agent/blob/main/agent.py): `agent.py`
- [Prompt and schema](https://github.com/armaganakcann/pocket-agent/blob/main/prompts.py): `prompts.py`

### Tools and device access

- [Tool dispatcher](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`
- [Notifications](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`
- [Text to speech](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`
- [File access](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`
- [Shell tool](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`
- [Battery status](https://github.com/armaganakcann/pocket-agent/blob/main/tools.py): `tools.py`

### Other components

- **User**
- **llama.cpp server**
- **Remote API**
- **Termux APIs**
- **Home filesystem**
- **System shell**

## Connections

- User → CLI: submits request (evidence: `README.md`)
- CLI → Agent loop: runs request (evidence: `agent.py`)
- Agent loop → Complexity router: checks complexity (evidence: `agent.py`)
- Agent loop → Prompt and schema: uses instructions (evidence: `agent.py`)
- Agent loop → LLM backend: sends messages (evidence: `agent.py`)
- LLM backend → llama.cpp server: posts chat (evidence: `agent.py`)
- Complexity router → Remote API: selects fallback (evidence: `README.md`)
- Agent loop → Tool-call parser: parses reply (evidence: `agent.py`)
- Agent loop → Tool dispatcher: dispatches tool (evidence: `agent.py`)
- Tool dispatcher → Notifications: invokes (evidence: `tools.py`)
- Tool dispatcher → Text to speech: invokes (evidence: `tools.py`)
- Tool dispatcher → File access: invokes (evidence: `tools.py`)
- Tool dispatcher → Shell tool: invokes (evidence: `tools.py`)
- Tool dispatcher → Battery status: invokes (evidence: `tools.py`)
- Notifications → Termux APIs: runs command (evidence: `tools.py`)
- Text to speech → Termux APIs: runs command (evidence: `tools.py`)
- Battery status → Termux APIs: runs command (evidence: `tools.py`)
- File access → Home filesystem: reads and writes (evidence: `tools.py`)
- Shell tool → System shell: runs command (evidence: `tools.py`)
