# tailscale/aperture-cli architecture

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

- Interactive diagram: https://gitdiagram.com/tailscale/aperture-cli
- Repository: https://github.com/tailscale/aperture-cli

## Overview

Aperture CLI is an interactive launcher that configures coding-agent clients to use Aperture providers and models. The principal flow is startup into the TUI, connection selection and endpoint verification (directly or through an embedded Tailscale bridge), then client-specific provider/backend/model selection and agent launch. Settings preserve endpoints, bridges, provider data, and launch preferences. The README documents the supported clients and bridge behavior; some client implementations and bridge wiring were not sampled, so those relationships are shown only where documented or supported by the index.

Main entry points: [`internal/tui/tui.go`](https://github.com/tailscale/aperture-cli/blob/main/internal/tui/tui.go) (Interactive launcher), [`internal/clients/registry.go`](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/registry.go) (Client registry), [`internal/config/global.go`](https://github.com/tailscale/aperture-cli/blob/main/internal/config/global.go) (Global settings), [`internal/bridges/attempt.go`](https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/attempt.go) (Connection attempt)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launcher and UI"]
  node_main["CLI entrypoint<br/>[main.go]"]
  node_tui["Interactive launcher<br/>[tui.go]"]
  node_menus["Connection menus<br/>[menus.go]"]
  node_removal["Removal flows<br/>[removal.go]"]
end

subgraph group_connections["Connections and bridges"]
  node_attempt["Connection attempt<br/>[attempt.go]"]
  node_machine["Bridge machine<br/>[machine.go]"]
  node_node["Embedded node<br/>[node.go]"]
  node_machines["Bridge manager<br/>[machines.go]"]
end

subgraph group_clients["Agent clients"]
  node_registry["Client registry<br/>[registry.go]"]
  node_claude["Claude Code<br/>[claudecode.go]"]
  node_codex["Codex<br/>[codex.go]"]
  node_codexcatalog["Codex model catalog<br/>[catalog.go]"]
  node_gemini["Gemini CLI<br/>[gemini.go]"]
  node_otherclients["Other agent clients"]
  node_pilike["Pi-like harnesses<br/>[pilike.go]"]
  node_extension["Provider extension<br/>[extension.go]"]
  node_desktop["Claude Cowork profile<br/>[adapter.go]"]
end

subgraph group_state["Configuration and profiles"]
  node_config[("Global settings<br/>[global.go]")]
  node_endpoints["Endpoint settings<br/>[endpoint.go]"]
  node_providers["Provider settings<br/>[providers.go]"]
  node_profiles["Desktop profiles<br/>[profiles.go]"]
end

node_user(("User"))
node_aperture{{"Aperture endpoint"}}
node_tailscale{{"Tailscale control plane"}}

node_user -->|"runs"| node_main
node_main -->|"starts"| node_tui
node_main -->|"registers"| node_profiles
node_tui -->|"renders"| node_menus
node_tui -->|"uses picker"| node_registry
node_tui -->|"starts connection"| node_attempt
node_menus -->|"requests connection"| node_attempt
node_menus -->|"offers removal"| node_removal
node_removal -->|"destroys bridge"| node_machines
node_tui -->|"reads active settings"| node_config
node_attempt -->|"updates endpoints"| node_config
node_attempt -->|"runs bridge"| node_machines
node_machines -.->|"manages"| node_machine
node_machine -->|"brings up"| node_node
node_node -.->|"joins tailnet"| node_tailscale
node_attempt -.->|"verifies models"| node_aperture
node_tui -.->|"checks endpoint"| node_aperture
node_registry -->|"registers"| node_claude
node_registry -.->|"registers"| node_codex
node_registry -->|"registers"| node_gemini
node_registry -.->|"provides clients"| node_otherclients
node_registry -->|"adds platform client"| node_desktop
node_claude -->|"selects provider"| node_providers
node_claude -.->|"records launch"| node_config
node_codex -.->|"updates catalog"| node_codexcatalog
node_codex -->|"selects provider"| node_providers
node_gemini -->|"selects provider"| node_providers
node_otherclients -.->|"configures routing"| node_providers
node_pilike -->|"writes extension"| node_extension
node_desktop -->|"records launch"| node_config
node_desktop -.->|"routes requests"| node_aperture
node_main -.->|"loads settings"| node_config
node_endpoints -.->|"persists endpoint data"| node_config

click node_main "https://github.com/tailscale/aperture-cli/blob/main/cmd/aperture/main.go"
click node_tui "https://github.com/tailscale/aperture-cli/blob/main/internal/tui/tui.go"
click node_menus "https://github.com/tailscale/aperture-cli/blob/main/internal/tui/menus.go"
click node_removal "https://github.com/tailscale/aperture-cli/blob/main/internal/tui/removal.go"
click node_registry "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/registry.go"
click node_claude "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/claudecode/claudecode.go"
click node_codex "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/codex/codex.go"
click node_codexcatalog "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/codex/catalog.go"
click node_gemini "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/gemini/gemini.go"
click node_otherclients "https://github.com/tailscale/aperture-cli/tree/main/internal/clients"
click node_pilike "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/pilike/pilike.go"
click node_extension "https://github.com/tailscale/aperture-cli/blob/main/internal/clients/pilike/extension.go"
click node_desktop "https://github.com/tailscale/aperture-cli/blob/main/internal/profiles/adapter.go"
click node_config "https://github.com/tailscale/aperture-cli/blob/main/internal/config/global.go"
click node_endpoints "https://github.com/tailscale/aperture-cli/blob/main/internal/config/endpoint.go"
click node_providers "https://github.com/tailscale/aperture-cli/blob/main/internal/config/providers.go"
click node_profiles "https://github.com/tailscale/aperture-cli/blob/main/internal/profiles/profiles.go"
click node_attempt "https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/attempt.go"
click node_machine "https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/machine.go"
click node_node "https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/node.go"
click node_machines "https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/machines.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_main,node_tui,node_menus,node_removal,node_user toneBlue
class node_attempt,node_machine,node_node,node_machines toneAmber
class node_registry,node_claude,node_codex,node_codexcatalog,node_gemini,node_otherclients,node_pilike,node_extension,node_desktop toneMint
class node_config,node_endpoints,node_providers,node_profiles toneRose
class node_aperture,node_tailscale toneIndigo
```

## Components

### Launcher and UI

- [CLI entrypoint](https://github.com/tailscale/aperture-cli/blob/main/cmd/aperture/main.go): `cmd/aperture/main.go`
- [Interactive launcher](https://github.com/tailscale/aperture-cli/blob/main/internal/tui/tui.go): `internal/tui/tui.go`
- [Connection menus](https://github.com/tailscale/aperture-cli/blob/main/internal/tui/menus.go): `internal/tui/menus.go`
- [Removal flows](https://github.com/tailscale/aperture-cli/blob/main/internal/tui/removal.go): `internal/tui/removal.go`

### Connections and bridges

- [Connection attempt](https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/attempt.go): `internal/bridges/attempt.go`
- [Bridge machine](https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/machine.go): `internal/bridges/machine.go`
- [Embedded node](https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/node.go): `internal/bridges/node.go`
- [Bridge manager](https://github.com/tailscale/aperture-cli/blob/main/internal/bridges/machines.go): `internal/bridges/machines.go`

### Agent clients

- [Client registry](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/registry.go): `internal/clients/registry.go`
- [Claude Code](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/claudecode/claudecode.go): `internal/clients/claudecode/claudecode.go`
- [Codex](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/codex/codex.go): `internal/clients/codex/codex.go`
- [Codex model catalog](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/codex/catalog.go): `internal/clients/codex/catalog.go`
- [Gemini CLI](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/gemini/gemini.go): `internal/clients/gemini/gemini.go`
- [Other agent clients](https://github.com/tailscale/aperture-cli/tree/main/internal/clients): `internal/clients`
- [Pi-like harnesses](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/pilike/pilike.go): `internal/clients/pilike/pilike.go`
- [Provider extension](https://github.com/tailscale/aperture-cli/blob/main/internal/clients/pilike/extension.go): `internal/clients/pilike/extension.go`
- [Claude Cowork profile](https://github.com/tailscale/aperture-cli/blob/main/internal/profiles/adapter.go): `internal/profiles/adapter.go`

### Configuration and profiles

- [Global settings](https://github.com/tailscale/aperture-cli/blob/main/internal/config/global.go): `internal/config/global.go`
- [Endpoint settings](https://github.com/tailscale/aperture-cli/blob/main/internal/config/endpoint.go): `internal/config/endpoint.go`
- [Provider settings](https://github.com/tailscale/aperture-cli/blob/main/internal/config/providers.go): `internal/config/providers.go`
- [Desktop profiles](https://github.com/tailscale/aperture-cli/blob/main/internal/profiles/profiles.go): `internal/profiles/profiles.go`

### Other components

- **User**
- **Aperture endpoint**
- **Tailscale control plane**

## Connections

- User → CLI entrypoint: runs (evidence: `README.md`)
- CLI entrypoint → Interactive launcher: starts (evidence: `cmd/aperture/main.go`)
- CLI entrypoint → Desktop profiles: registers (evidence: `cmd/aperture/main.go`)
- Interactive launcher → Connection menus: renders (evidence: `internal/tui/tui.go`)
- Interactive launcher → Client registry: uses picker (evidence: `internal/tui/tui.go`)
- Interactive launcher → Connection attempt: starts connection (evidence: `internal/tui/tui.go`)
- Connection menus → Connection attempt: requests connection (evidence: `internal/tui/menus.go`)
- Connection menus → Removal flows: offers removal (evidence: `internal/tui/menus.go`)
- Removal flows → Bridge manager: destroys bridge (evidence: `internal/tui/removal.go`)
- Interactive launcher → Global settings: reads active settings (evidence: `internal/tui/tui.go`)
- Connection attempt → Global settings: updates endpoints (evidence: `internal/bridges/attempt.go`)
- Connection attempt → Bridge manager: runs bridge
- Bridge manager → Bridge machine: manages
- Bridge machine → Embedded node: brings up (evidence: `internal/bridges/machine.go`)
- Embedded node → Tailscale control plane: joins tailnet (evidence: `README.md`)
- Connection attempt → Aperture endpoint: verifies models (evidence: `README.md`)
- Interactive launcher → Aperture endpoint: checks endpoint
- Client registry → Claude Code: registers (evidence: `internal/clients/claudecode/claudecode.go`)
- Client registry → Codex: registers
- Client registry → Gemini CLI: registers (evidence: `internal/clients/gemini/gemini.go`)
- Client registry → Other agent clients: provides clients
- Client registry → Claude Cowork profile: adds platform client (evidence: `internal/profiles/adapter.go`)
- Claude Code → Provider settings: selects provider (evidence: `internal/clients/claudecode/claudecode.go`)
- Claude Code → Global settings: records launch
- Codex → Codex model catalog: updates catalog
- Codex → Provider settings: selects provider (evidence: `internal/clients/codex/codex.go`)
- Gemini CLI → Provider settings: selects provider (evidence: `internal/clients/gemini/gemini.go`)
- Other agent clients → Provider settings: configures routing
- Pi-like harnesses → Provider extension: writes extension (evidence: `internal/clients/pilike/pilike.go`)
- Claude Cowork profile → Global settings: records launch (evidence: `internal/profiles/adapter.go`)
- Claude Cowork profile → Aperture endpoint: routes requests (evidence: `README.md`)
- CLI entrypoint → Global settings: loads settings
- Endpoint settings → Global settings: persists endpoint data
