# hoangp8/tokless architecture

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

- Interactive diagram: https://gitdiagram.com/hoangp8/tokless
- Repository: https://github.com/hoangp8/tokless

## Overview

Tokless is a Go CLI that configures and manages coding-agent integrations: users select supported agents, Tokless wires specialized tools into their configurations, and commands support diagnosis, updates, and proxy routing. Its principal workflow runs through the CLI into command handlers and agent/tool adapters. Tool-specific modules cover RTK, CodeGraph, Context Mode, and other documented capabilities; Headroom adds shared proxy routing and BYOK support. The README documents broad integrations, while several subsystem links below are documented rather than verified from unsampled implementation.

Main entry points: [`internal/core/core.go`](https://github.com/hoangp8/tokless/blob/main/internal/core/core.go) (Tool registry), [`internal/agents`](https://github.com/hoangp8/tokless/tree/main/internal/agents) (Agent adapters), [`cmd/tokless/main.go`](https://github.com/hoangp8/tokless/blob/main/cmd/tokless/main.go) (Tokless CLI), [`internal/commands/proxy.go`](https://github.com/hoangp8/tokless/blob/main/internal/commands/proxy.go) (Proxy commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI management"]
  node_cli["Tokless CLI<br/>[main.go]"]
  node_commands["Command handlers"]
  node_core["Tool registry<br/>[core.go]"]
end

subgraph group_agents["Agent integrations"]
  node_agent_adapters["Agent adapters"]
  node_agent_configs["Agent configurations<br/>[codex.go]"]
end

subgraph group_tools["Tool integrations"]
  node_rtk["RTK filtering<br/>[rtk.go]"]
  node_codegraph["CodeGraph indexing<br/>[codegraph.go]"]
  node_contextmode["Context Mode<br/>[contextmode.go]"]
  node_tool_suite["Other tools"]
  node_headroom_tool["Headroom integration<br/>[headroom.go]"]
end

subgraph group_routing["Proxy routing"]
  node_proxy_commands["Proxy commands<br/>[proxy.go]"]
  node_headroom_proxy["Headroom proxy<br/>[proxy.go]"]
  node_router["Request router<br/>[router.go]"]
  node_byok["BYOK gateway<br/>[byok_gateway.go]"]
  node_route_state[("Route state<br/>[routing_store.go]")]
end

node_user(("Operator"))

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_commands
node_cli -->|"registers tools"| node_core
node_commands -.->|"configures agents"| node_agent_adapters
node_commands -->|"lists tools"| node_core
node_agent_adapters -.->|"edits settings"| node_agent_configs
node_core -->|"registers"| node_rtk
node_core -->|"registers"| node_codegraph
node_core -->|"registers"| node_contextmode
node_core -->|"registers"| node_tool_suite
node_rtk -->|"wires into"| node_agent_adapters
node_codegraph -->|"configures MCP"| node_agent_adapters
node_user -->|"requests routing"| node_proxy_commands
node_cli -->|"dispatches"| node_proxy_commands
node_proxy_commands -->|"starts and stops"| node_headroom_proxy
node_proxy_commands -->|"wires proxy"| node_agent_adapters
node_headroom_tool -.->|"integrates"| node_headroom_proxy
node_headroom_proxy -.->|"serves routes"| node_router
node_router -.->|"resolves route"| node_route_state
node_headroom_proxy -.->|"supports BYOK"| node_byok

click node_cli "https://github.com/hoangp8/tokless/blob/main/cmd/tokless/main.go"
click node_commands "https://github.com/hoangp8/tokless/tree/main/internal/commands"
click node_core "https://github.com/hoangp8/tokless/blob/main/internal/core/core.go"
click node_agent_adapters "https://github.com/hoangp8/tokless/tree/main/internal/agents"
click node_agent_configs "https://github.com/hoangp8/tokless/blob/main/internal/agents/codex.go"
click node_rtk "https://github.com/hoangp8/tokless/blob/main/internal/tools/rtk.go"
click node_codegraph "https://github.com/hoangp8/tokless/blob/main/internal/tools/codegraph.go"
click node_contextmode "https://github.com/hoangp8/tokless/blob/main/internal/tools/contextmode.go"
click node_tool_suite "https://github.com/hoangp8/tokless/tree/main/internal/tools"
click node_headroom_tool "https://github.com/hoangp8/tokless/blob/main/internal/tools/headroom.go"
click node_proxy_commands "https://github.com/hoangp8/tokless/blob/main/internal/commands/proxy.go"
click node_headroom_proxy "https://github.com/hoangp8/tokless/blob/main/internal/headroom/proxy.go"
click node_router "https://github.com/hoangp8/tokless/blob/main/internal/headroom/router.go"
click node_byok "https://github.com/hoangp8/tokless/blob/main/internal/headroom/byok_gateway.go"
click node_route_state "https://github.com/hoangp8/tokless/blob/main/internal/util/routing_store.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_cli,node_commands,node_core toneBlue
class node_agent_adapters,node_agent_configs toneAmber
class node_rtk,node_codegraph,node_contextmode,node_tool_suite,node_headroom_tool toneMint
class node_proxy_commands,node_headroom_proxy,node_router,node_byok,node_route_state toneRose
class node_user toneIndigo
```

## Components

### CLI management

- [Tokless CLI](https://github.com/hoangp8/tokless/blob/main/cmd/tokless/main.go): `cmd/tokless/main.go`
- [Command handlers](https://github.com/hoangp8/tokless/tree/main/internal/commands): `internal/commands`
- [Tool registry](https://github.com/hoangp8/tokless/blob/main/internal/core/core.go): `internal/core/core.go`

### Agent integrations

- [Agent adapters](https://github.com/hoangp8/tokless/tree/main/internal/agents): `internal/agents`
- [Agent configurations](https://github.com/hoangp8/tokless/blob/main/internal/agents/codex.go): `internal/agents/codex.go`

### Tool integrations

- [RTK filtering](https://github.com/hoangp8/tokless/blob/main/internal/tools/rtk.go): `internal/tools/rtk.go`
- [CodeGraph indexing](https://github.com/hoangp8/tokless/blob/main/internal/tools/codegraph.go): `internal/tools/codegraph.go`
- [Context Mode](https://github.com/hoangp8/tokless/blob/main/internal/tools/contextmode.go): `internal/tools/contextmode.go`
- [Other tools](https://github.com/hoangp8/tokless/tree/main/internal/tools): `internal/tools`
- [Headroom integration](https://github.com/hoangp8/tokless/blob/main/internal/tools/headroom.go): `internal/tools/headroom.go`

### Proxy routing

- [Proxy commands](https://github.com/hoangp8/tokless/blob/main/internal/commands/proxy.go): `internal/commands/proxy.go`
- [Headroom proxy](https://github.com/hoangp8/tokless/blob/main/internal/headroom/proxy.go): `internal/headroom/proxy.go`
- [Request router](https://github.com/hoangp8/tokless/blob/main/internal/headroom/router.go): `internal/headroom/router.go`
- [BYOK gateway](https://github.com/hoangp8/tokless/blob/main/internal/headroom/byok_gateway.go): `internal/headroom/byok_gateway.go`
- [Route state](https://github.com/hoangp8/tokless/blob/main/internal/util/routing_store.go): `internal/util/routing_store.go`

### Other components

- **Operator**

## Connections

- Operator → Tokless CLI: invokes
- Tokless CLI → Command handlers: dispatches (evidence: `cmd/tokless/main.go`)
- Tokless CLI → Tool registry: registers tools (evidence: `cmd/tokless/main.go`)
- Command handlers → Agent adapters: configures agents (evidence: `internal/commands/proxy.go`)
- Command handlers → Tool registry: lists tools (evidence: `internal/commands/index.go`)
- Agent adapters → Agent configurations: edits settings
- Tool registry → RTK filtering: registers
- Tool registry → CodeGraph indexing: registers
- Tool registry → Context Mode: registers (evidence: `internal/tools/contextmode.go`)
- Tool registry → Other tools: registers (evidence: `internal/tools/contextmode.go`)
- RTK filtering → Agent adapters: wires into (evidence: `internal/tools/rtk.go`)
- CodeGraph indexing → Agent adapters: configures MCP (evidence: `internal/tools/codegraph.go`)
- Operator → Proxy commands: requests routing
- Tokless CLI → Proxy commands: dispatches (evidence: `cmd/tokless/main.go`)
- Proxy commands → Headroom proxy: starts and stops (evidence: `internal/commands/proxy.go`)
- Proxy commands → Agent adapters: wires proxy (evidence: `internal/commands/proxy.go`)
- Headroom integration → Headroom proxy: integrates
- Headroom proxy → Request router: serves routes
- Request router → Route state: resolves route
- Headroom proxy → BYOK gateway: supports BYOK