# jdawosx/termux-native-agent architecture

> Architecture diagram of the GitHub repository jdawosx/termux-native-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/jdawosx/termux-native-agent
- Repository: https://github.com/jdawosx/termux-native-agent

## Overview

TNA is a Termux-native AI agent with two runtime implementations: a Python ReAct chat/voice loop and an experimental Go agent using Google ADK. Users provide text or speech; the agent consults an LLM, dispatches selected tools, feeds tool results back for a response, and presents text or speech. The Python path includes shell, telephony, and SMS; Go adds app deep links, camera-based vision, and persistent memory. README capabilities are included, but no separate Python voice or tool modules exist in the tree.

Main entry points: [`go-version/main.go`](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go) (Registered tools), [`main.py`](https://github.com/jdawosx/termux-native-agent/blob/main/main.py) (Conversation loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Agent"]
  node_python_loop["Conversation loop<br/>[main.py]"]
  node_text_io["Text I/O<br/>[main.py]"]
  node_voice_io["Voice I/O<br/>[main.py]"]
  node_python_llm["OpenAI-compatible LLM<br/>[main.py]"]
  node_python_tools["Tool dispatch<br/>[main.py]"]
  node_python_shell["Shell execution<br/>[main.py]"]
  node_python_phone["Telephony and SMS<br/>[main.py]"]
end

subgraph group_go["Go Agent"]
  node_go_launcher["ADK launcher<br/>[main.go]"]
  node_go_agent["ADK agent<br/>[main.go]"]
  node_go_tools["Registered tools<br/>[main.go]"]
  node_go_shell["Shell tool<br/>[main.go]"]
  node_go_telephony["Telephony tools<br/>[main.go]"]
  node_app_links["App deep links<br/>[main.go]"]
  node_vision["Camera vision<br/>[main.go]"]
  node_memory_tools["Memory tools<br/>[main.go]"]
  node_memory_file[("Persistent memory")]
end

node_user(("User"))
node_termux_shell["Termux shell"]
node_termux_api["Termux device APIs"]
node_gemini["Gemini model"]
node_android["Android device"]

node_user -->|"types to"| node_text_io
node_user -->|"speaks to"| node_voice_io
node_text_io -->|"supplies input"| node_python_loop
node_voice_io -->|"supplies input"| node_python_loop
node_python_loop -->|"requests completion"| node_python_llm
node_python_loop -->|"dispatches calls"| node_python_tools
node_python_tools -->|"calls"| node_python_shell
node_python_tools -->|"calls"| node_python_phone
node_python_shell -->|"runs commands"| node_termux_shell
node_python_phone -->|"runs telephony"| node_termux_api
node_python_loop -->|"presents reply"| node_text_io
node_python_loop -->|"presents reply"| node_voice_io
node_voice_io -->|"uses speech services"| node_termux_api
node_user -->|"starts session"| node_go_launcher
node_go_launcher -->|"loads agent"| node_go_agent
node_go_agent -->|"reasons with"| node_gemini
node_go_agent -->|"dispatches tools"| node_go_tools
node_go_tools -->|"invokes"| node_go_shell
node_go_tools -->|"invokes"| node_go_telephony
node_go_tools -->|"invokes"| node_app_links
node_go_tools -->|"invokes"| node_vision
node_go_tools -->|"invokes"| node_memory_tools
node_go_shell -->|"executes commands"| node_termux_shell
node_go_telephony -->|"runs commands"| node_termux_api
node_app_links -->|"opens apps"| node_android
node_vision -->|"captures photo"| node_termux_api
node_vision -->|"analyzes image"| node_gemini
node_memory_tools -->|"reads and writes"| node_memory_file

click node_python_loop "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_text_io "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_voice_io "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_python_llm "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_python_tools "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_python_shell "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_python_phone "https://github.com/jdawosx/termux-native-agent/blob/main/main.py"
click node_go_launcher "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_go_agent "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_go_tools "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_go_shell "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_go_telephony "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_app_links "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_vision "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"
click node_memory_tools "https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go"

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_python_loop,node_text_io,node_voice_io,node_python_llm,node_python_tools,node_python_shell,node_python_phone,node_user toneBlue
class node_go_launcher,node_go_agent,node_go_tools,node_go_shell,node_go_telephony,node_app_links,node_vision,node_memory_tools,node_memory_file toneAmber
class node_termux_shell,node_gemini,node_android toneIndigo
class node_termux_api toneMint
```

## Components

### Python Agent

- [Conversation loop](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [Text I/O](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [Voice I/O](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [OpenAI-compatible LLM](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [Tool dispatch](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [Shell execution](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`
- [Telephony and SMS](https://github.com/jdawosx/termux-native-agent/blob/main/main.py): `main.py`

### Go Agent

- [ADK launcher](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [ADK agent](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [Registered tools](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [Shell tool](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [Telephony tools](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [App deep links](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [Camera vision](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- [Memory tools](https://github.com/jdawosx/termux-native-agent/blob/main/go-version/main.go): `go-version/main.go`
- **Persistent memory**

### Other components

- **User**
- **Termux shell**
- **Termux device APIs**
- **Gemini model**
- **Android device**

## Connections

- User → Text I/O: types to (evidence: `main.py`)
- User → Voice I/O: speaks to (evidence: `README.md`)
- Text I/O → Conversation loop: supplies input (evidence: `main.py`)
- Voice I/O → Conversation loop: supplies input (evidence: `main.py`)
- Conversation loop → OpenAI-compatible LLM: requests completion (evidence: `main.py`)
- Conversation loop → Tool dispatch: dispatches calls (evidence: `main.py`)
- Tool dispatch → Shell execution: calls (evidence: `main.py`)
- Tool dispatch → Telephony and SMS: calls (evidence: `main.py`)
- Shell execution → Termux shell: runs commands (evidence: `main.py`)
- Telephony and SMS → Termux device APIs: runs telephony (evidence: `main.py`)
- Conversation loop → Text I/O: presents reply (evidence: `main.py`)
- Conversation loop → Voice I/O: presents reply (evidence: `main.py`)
- Voice I/O → Termux device APIs: uses speech services (evidence: `main.py`)
- User → ADK launcher: starts session (evidence: `README.md`)
- ADK launcher → ADK agent: loads agent (evidence: `go-version/main.go`)
- ADK agent → Gemini model: reasons with (evidence: `go-version/main.go`)
- ADK agent → Registered tools: dispatches tools (evidence: `go-version/main.go`)
- Registered tools → Shell tool: invokes (evidence: `go-version/main.go`)
- Registered tools → Telephony tools: invokes (evidence: `go-version/main.go`)
- Registered tools → App deep links: invokes (evidence: `go-version/main.go`)
- Registered tools → Camera vision: invokes (evidence: `go-version/main.go`)
- Registered tools → Memory tools: invokes (evidence: `go-version/main.go`)
- Shell tool → Termux shell: executes commands (evidence: `go-version/main.go`)
- Telephony tools → Termux device APIs: runs commands (evidence: `go-version/main.go`)
- App deep links → Android device: opens apps (evidence: `go-version/main.go`)
- Camera vision → Termux device APIs: captures photo (evidence: `go-version/main.go`)
- Camera vision → Gemini model: analyzes image (evidence: `go-version/main.go`)
- Memory tools → Persistent memory: reads and writes (evidence: `go-version/main.go`)
