# yanghoeg/usix-termux architecture

> Architecture diagram of the GitHub repository yanghoeg/usix-termux, 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/yanghoeg/usix-termux
- Repository: https://github.com/yanghoeg/usix-termux

## Overview

usix-code is a local coding and automation harness for Linux and Android Termux. Users submit prompts through the CLI/TUI; the agent consults a local model, dispatches registered tools, and pauses for approval before mutations. A separate task workflow saves, schedules, and runs prompts, with checkpoints and approval handling. Host adapters supply OS-specific tools and services; optional Termux capabilities include messaging, email, UI control, and companion-app access. The README documents the hexagonal boundaries; unsampled implementation details and some runtime wiring are not asserted here.

Main entry points: [`src/domain/agent.rs`](https://github.com/yanghoeg/usix-termux/blob/main/src/domain/agent.rs) (Agent loop), [`src/ports.rs`](https://github.com/yanghoeg/usix-termux/blob/main/src/ports.rs) (Core ports), [`src/adapters/host/termux.rs`](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/termux.rs) (Termux host), [`src/tui.rs`](https://github.com/yanghoeg/usix-termux/blob/main/src/tui.rs) (Interactive TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_tui["Interactive TUI<br/>[tui.rs]"]
  node_editor["Input editor<br/>[editor.rs]"]
  node_markdown["Markdown rendering<br/>[markdown.rs]"]
end

subgraph group_core["Agent core"]
  node_agent["Agent loop<br/>[agent.rs]"]
  node_registry["Tool registry<br/>[registry.rs]"]
  node_skills["Skill selection<br/>[skills.rs]"]
  node_ports["Core ports<br/>[ports.rs]"]
end

subgraph group_execution["Tasks and tools"]
  node_task_cli["Task commands<br/>[mod.rs]"]
  node_task_runner["Task runner<br/>[runner.rs]"]
  node_task_store[("Saved task state<br/>[store.rs]")]
  node_local_tools["Local tools<br/>[shell.rs]"]
  node_task_tools["Task tools<br/>[tasks.rs]"]
end

subgraph group_adapters["Host and model adapters"]
  node_bootstrap["Setup and lifecycle<br/>[bootstrap.rs]"]
  node_host_select["Host selection<br/>[mod.rs]"]
  node_linux_host["Linux host<br/>[linux.rs]"]
  node_termux_host["Termux host<br/>[termux.rs]"]
  node_skills_io["Skill file I/O<br/>[skills.rs]"]
  node_runtime_io["Process runtime<br/>[runtime.rs]"]
  node_llama["llama.cpp adapter<br/>[llama.rs]"]
  node_ollama["Ollama adapter<br/>[ollama.rs]"]
end

subgraph group_integrations["Device integrations"]
  node_termux_tools["Phone tools<br/>[comms.rs]"]
  node_companion_tools["Companion tools<br/>[companion.rs]"]
  node_bridge["Companion bridge client<br/>[bridge.rs]"]
  node_ui_tools["Android UI tools<br/>[ui.rs]"]
  node_email_tools["Email tools<br/>[email.rs]"]
end

node_user(("User"))
node_model_service["Local model service"]
node_companion_app["Companion app"]

node_user -->|"submits commands"| node_cli
node_cli -->|"selects host"| node_host_select
node_cli -->|"starts chat"| node_tui
node_user -->|"enters prompts"| node_tui
node_tui -->|"uses editor"| node_editor
node_tui -->|"renders answers"| node_markdown
node_tui -->|"advances turns"| node_agent
node_agent -->|"looks up tools"| node_registry
node_agent -->|"uses LLM contract"| node_ports
node_agent -->|"selects guidance"| node_skills
node_registry -->|"registers tools"| node_ports
node_cli -->|"routes task commands"| node_task_cli
node_task_cli -->|"manages saved tasks"| node_task_store
node_task_cli -->|"runs tasks"| node_task_runner
node_task_runner -->|"loads checkpoints"| node_task_store
node_task_runner -->|"resumes agent"| node_agent
node_task_tools -->|"reads and changes tasks"| node_task_store
node_host_select -->|"selects on Linux"| node_linux_host
node_host_select -->|"selects on Android"| node_termux_host
node_termux_host -->|"registers phone tools"| node_termux_tools
node_termux_host -->|"registers companion tools"| node_companion_tools
node_termux_host -->|"registers UI tools"| node_ui_tools
node_termux_host -->|"registers email tools"| node_email_tools
node_companion_tools -->|"uses bridge client"| node_bridge
node_email_tools -->|"uses bridge client"| node_bridge
node_ui_tools -->|"uses bridge client"| node_bridge
node_bridge -->|"sends loopback requests"| node_companion_app
node_bootstrap -->|"uses host services"| node_host_select
node_bootstrap -->|"uses host contracts"| node_ports
node_skills_io -->|"parses skill files"| node_skills
node_runtime_io -->|"implements runtime I/O"| node_ports
node_llama -->|"implements LLM port"| node_ports
node_ollama -->|"implements LLM port"| node_ports
node_bootstrap -->|"starts selected backend"| node_llama
node_bootstrap -->|"starts selected backend"| node_ollama
node_llama -.->|"calls local model"| node_model_service
node_ollama -.->|"calls local model"| node_model_service
node_agent -.->|"dispatches registered tools"| node_local_tools

click node_cli "https://github.com/yanghoeg/usix-termux/blob/main/src/main.rs"
click node_tui "https://github.com/yanghoeg/usix-termux/blob/main/src/tui.rs"
click node_editor "https://github.com/yanghoeg/usix-termux/blob/main/src/tui/editor.rs"
click node_markdown "https://github.com/yanghoeg/usix-termux/blob/main/src/tui/markdown.rs"
click node_agent "https://github.com/yanghoeg/usix-termux/blob/main/src/domain/agent.rs"
click node_registry "https://github.com/yanghoeg/usix-termux/blob/main/src/domain/registry.rs"
click node_skills "https://github.com/yanghoeg/usix-termux/blob/main/src/domain/skills.rs"
click node_ports "https://github.com/yanghoeg/usix-termux/blob/main/src/ports.rs"
click node_task_cli "https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/mod.rs"
click node_task_runner "https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/runner.rs"
click node_task_store "https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/store.rs"
click node_local_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/shell.rs"
click node_task_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/tasks.rs"
click node_bootstrap "https://github.com/yanghoeg/usix-termux/blob/main/src/bootstrap.rs"
click node_host_select "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/mod.rs"
click node_linux_host "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/linux.rs"
click node_termux_host "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/termux.rs"
click node_skills_io "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/skills.rs"
click node_runtime_io "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/runtime.rs"
click node_llama "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/llama.rs"
click node_ollama "https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/ollama.rs"
click node_termux_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/comms.rs"
click node_companion_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/companion.rs"
click node_bridge "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/bridge.rs"
click node_ui_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/ui.rs"
click node_email_tools "https://github.com/yanghoeg/usix-termux/blob/main/src/tools/email.rs"

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_tui,node_editor,node_markdown,node_user toneBlue
class node_agent,node_registry,node_skills,node_ports toneAmber
class node_task_cli,node_task_runner,node_task_store,node_local_tools,node_task_tools toneMint
class node_bootstrap,node_host_select,node_linux_host,node_termux_host,node_skills_io,node_runtime_io,node_llama,node_ollama toneRose
class node_termux_tools,node_companion_tools,node_bridge,node_ui_tools,node_email_tools,node_model_service,node_companion_app toneIndigo
```

## Components

### User interaction

- [CLI entry](https://github.com/yanghoeg/usix-termux/blob/main/src/main.rs): `src/main.rs`
- [Interactive TUI](https://github.com/yanghoeg/usix-termux/blob/main/src/tui.rs): `src/tui.rs`
- [Input editor](https://github.com/yanghoeg/usix-termux/blob/main/src/tui/editor.rs): `src/tui/editor.rs`
- [Markdown rendering](https://github.com/yanghoeg/usix-termux/blob/main/src/tui/markdown.rs): `src/tui/markdown.rs`

### Agent core

- [Agent loop](https://github.com/yanghoeg/usix-termux/blob/main/src/domain/agent.rs): `src/domain/agent.rs`
- [Tool registry](https://github.com/yanghoeg/usix-termux/blob/main/src/domain/registry.rs): `src/domain/registry.rs`
- [Skill selection](https://github.com/yanghoeg/usix-termux/blob/main/src/domain/skills.rs): `src/domain/skills.rs`
- [Core ports](https://github.com/yanghoeg/usix-termux/blob/main/src/ports.rs): `src/ports.rs`

### Tasks and tools

- [Task commands](https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/mod.rs): `src/tasks/mod.rs`
- [Task runner](https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/runner.rs): `src/tasks/runner.rs`
- [Saved task state](https://github.com/yanghoeg/usix-termux/blob/main/src/tasks/store.rs): `src/tasks/store.rs`
- [Local tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/shell.rs): `src/tools/shell.rs`
- [Task tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/tasks.rs): `src/tools/tasks.rs`

### Host and model adapters

- [Setup and lifecycle](https://github.com/yanghoeg/usix-termux/blob/main/src/bootstrap.rs): `src/bootstrap.rs`
- [Host selection](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/mod.rs): `src/adapters/host/mod.rs`
- [Linux host](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/linux.rs): `src/adapters/host/linux.rs`
- [Termux host](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/host/termux.rs): `src/adapters/host/termux.rs`
- [Skill file I/O](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/skills.rs): `src/adapters/skills.rs`
- [Process runtime](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/runtime.rs): `src/adapters/runtime.rs`
- [llama.cpp adapter](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/llama.rs): `src/adapters/llama.rs`
- [Ollama adapter](https://github.com/yanghoeg/usix-termux/blob/main/src/adapters/ollama.rs): `src/adapters/ollama.rs`

### Device integrations

- [Phone tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/comms.rs): `src/tools/comms.rs`
- [Companion tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/companion.rs): `src/tools/companion.rs`
- [Companion bridge client](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/bridge.rs): `src/tools/bridge.rs`
- [Android UI tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/ui.rs): `src/tools/ui.rs`
- [Email tools](https://github.com/yanghoeg/usix-termux/blob/main/src/tools/email.rs): `src/tools/email.rs`

### Other components

- **User**
- **Local model service**
- **Companion app**

## Connections

- User → CLI entry: submits commands (evidence: `README.md`)
- CLI entry → Host selection: selects host (evidence: `src/main.rs`)
- CLI entry → Interactive TUI: starts chat (evidence: `src/main.rs`)
- User → Interactive TUI: enters prompts (evidence: `README.md`)
- Interactive TUI → Input editor: uses editor (evidence: `src/tui.rs`)
- Interactive TUI → Markdown rendering: renders answers (evidence: `src/tui.rs`)
- Interactive TUI → Agent loop: advances turns (evidence: `src/tui.rs`)
- Agent loop → Tool registry: looks up tools (evidence: `src/domain/agent.rs`)
- Agent loop → Core ports: uses LLM contract (evidence: `src/domain/agent.rs`)
- Agent loop → Skill selection: selects guidance (evidence: `README.md`)
- Tool registry → Core ports: registers tools (evidence: `src/domain/registry.rs`)
- CLI entry → Task commands: routes task commands (evidence: `src/main.rs`)
- Task commands → Saved task state: manages saved tasks (evidence: `src/tasks/mod.rs`)
- Task commands → Task runner: runs tasks (evidence: `src/tasks/mod.rs`)
- Task runner → Saved task state: loads checkpoints (evidence: `src/tasks/runner.rs`)
- Task runner → Agent loop: resumes agent (evidence: `src/tasks/runner.rs`)
- Task tools → Saved task state: reads and changes tasks (evidence: `src/tools/tasks.rs`)
- Host selection → Linux host: selects on Linux (evidence: `src/adapters/host/mod.rs`)
- Host selection → Termux host: selects on Android (evidence: `src/adapters/host/mod.rs`)
- Termux host → Phone tools: registers phone tools (evidence: `src/adapters/host/termux.rs`)
- Termux host → Companion tools: registers companion tools (evidence: `src/adapters/host/termux.rs`)
- Termux host → Android UI tools: registers UI tools (evidence: `src/adapters/host/termux.rs`)
- Termux host → Email tools: registers email tools (evidence: `src/adapters/host/termux.rs`)
- Companion tools → Companion bridge client: uses bridge client (evidence: `src/tools/companion.rs`)
- Email tools → Companion bridge client: uses bridge client (evidence: `src/tools/email.rs`)
- Android UI tools → Companion bridge client: uses bridge client (evidence: `src/tools/ui.rs`)
- Companion bridge client → Companion app: sends loopback requests (evidence: `src/tools/bridge.rs`)
- Setup and lifecycle → Host selection: uses host services (evidence: `src/bootstrap.rs`)
- Setup and lifecycle → Core ports: uses host contracts (evidence: `src/bootstrap.rs`)
- Skill file I/O → Skill selection: parses skill files (evidence: `src/adapters/skills.rs`)
- Process runtime → Core ports: implements runtime I/O (evidence: `src/adapters/runtime.rs`)
- llama.cpp adapter → Core ports: implements LLM port (evidence: `src/adapters/llama.rs`)
- Ollama adapter → Core ports: implements LLM port (evidence: `src/adapters/ollama.rs`)
- Setup and lifecycle → llama.cpp adapter: starts selected backend (evidence: `src/bootstrap.rs`)
- Setup and lifecycle → Ollama adapter: starts selected backend (evidence: `src/bootstrap.rs`)
- llama.cpp adapter → Local model service: calls local model
- Ollama adapter → Local model service: calls local model
- Agent loop → Local tools: dispatches registered tools
