# rtk-ai/rtk architecture

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

- Interactive diagram: https://gitdiagram.com/rtk-ai/rtk
- Repository: https://github.com/rtk-ai/rtk
- Video tour (about a minute): https://gitdiagram.com/rtk-ai/rtk/video

## Overview

RTK is a Rust CLI proxy that rewrites supported shell commands, runs command-specific filters, and returns compact output to an AI agent. Its main workflow is complemented by agent hook installation, command discovery and learning, savings analytics, and recall storage. README statements establish the user-facing flow; source-index references support selected internal links. Many command handlers and subsystem implementations were not sampled, so their internal call paths are not inferred.

Main entry points: [`src/main.rs`](https://github.com/rtk-ai/rtk/blob/develop/src/main.rs) (RTK CLI), [`src/hooks/hook_cmd.rs`](https://github.com/rtk-ai/rtk/blob/develop/src/hooks/hook_cmd.rs) (Hook runtime), [`src/cmds`](https://github.com/rtk-ai/rtk/tree/develop/src/cmds) (Command handlers), [`src/core/shell.rs`](https://github.com/rtk-ai/rtk/blob/develop/src/core/shell.rs) (Shell execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI workflow"]
  node_rtk["RTK CLI<br/>[main.rs]"]
end

subgraph group_hooks["Agent integration"]
  node_hook_runtime["Hook runtime<br/>[hook_cmd.rs]"]
  node_rewrite_rules["Rewrite registry<br/>[registry.rs]"]
  node_hook_setup["Agent setup<br/>[mod.rs]"]
end

subgraph group_commands["Command filtering"]
  node_command_handlers["Command handlers"]
  node_shell_runner["Shell execution<br/>[shell.rs]"]
  node_output_filters["Output filters<br/>[filter.rs]"]
  node_parser["Output formatting<br/>[formatter.rs]"]
end

subgraph group_intelligence["Discovery and learning"]
  node_discovery["Session discovery<br/>[mod.rs]"]
  node_learning["Command learning<br/>[mod.rs]"]
end

subgraph group_state["Settings and analytics"]
  node_config["Configuration<br/>[config.rs]"]
  node_tracking[("Usage tracking<br/>[tracking.rs]")]
  node_analytics["Savings analytics<br/>[gain.rs]"]
  node_recall[("Output recall<br/>[retriever.rs]")]
  node_telemetry["Telemetry commands<br/>[telemetry_cmd.rs]"]
end

node_agent(("AI agent"))
node_shell(("Shell commands"))

node_agent -->|"submits commands"| node_hook_runtime
node_hook_runtime -->|"checks rewrite"| node_rewrite_rules
node_hook_runtime -->|"rewrites to"| node_rtk
node_rtk -->|"dispatches commands"| node_command_handlers
node_command_handlers -.->|"executes commands"| node_shell_runner
node_shell_runner -->|"runs process"| node_shell
node_command_handlers -->|"filters output"| node_output_filters
node_output_filters -.->|"formats results"| node_parser
node_rtk -->|"installs hooks"| node_hook_setup
node_rtk -->|"loads settings"| node_config
node_rtk -->|"records usage"| node_tracking
node_analytics -->|"reads metrics"| node_tracking
node_rtk -->|"reports savings"| node_analytics
node_rtk -->|"recalls output"| node_recall
node_rtk -->|"discovers commands"| node_discovery
node_discovery -->|"matches commands"| node_rewrite_rules
node_rtk -->|"learns commands"| node_learning
node_rtk -->|"manages telemetry"| node_telemetry

click node_rtk "https://github.com/rtk-ai/rtk/blob/develop/src/main.rs"
click node_hook_runtime "https://github.com/rtk-ai/rtk/blob/develop/src/hooks/hook_cmd.rs"
click node_rewrite_rules "https://github.com/rtk-ai/rtk/blob/develop/src/discover/registry.rs"
click node_hook_setup "https://github.com/rtk-ai/rtk/blob/develop/src/hooks/init/mod.rs"
click node_command_handlers "https://github.com/rtk-ai/rtk/tree/develop/src/cmds"
click node_shell_runner "https://github.com/rtk-ai/rtk/blob/develop/src/core/shell.rs"
click node_output_filters "https://github.com/rtk-ai/rtk/blob/develop/src/core/filter.rs"
click node_parser "https://github.com/rtk-ai/rtk/blob/develop/src/parser/formatter.rs"
click node_config "https://github.com/rtk-ai/rtk/blob/develop/src/core/config.rs"
click node_tracking "https://github.com/rtk-ai/rtk/blob/develop/src/core/tracking.rs"
click node_analytics "https://github.com/rtk-ai/rtk/blob/develop/src/analytics/gain.rs"
click node_recall "https://github.com/rtk-ai/rtk/blob/develop/src/core/retriever.rs"
click node_discovery "https://github.com/rtk-ai/rtk/blob/develop/src/discover/mod.rs"
click node_learning "https://github.com/rtk-ai/rtk/blob/develop/src/learn/mod.rs"
click node_telemetry "https://github.com/rtk-ai/rtk/blob/develop/src/core/telemetry_cmd.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_rtk toneBlue
class node_hook_runtime,node_rewrite_rules,node_hook_setup toneAmber
class node_command_handlers,node_shell_runner,node_output_filters,node_parser toneMint
class node_discovery,node_learning toneRose
class node_config,node_tracking,node_analytics,node_recall,node_telemetry,node_agent,node_shell toneIndigo
```

## Components

### CLI workflow

- [RTK CLI](https://github.com/rtk-ai/rtk/blob/develop/src/main.rs): `src/main.rs`

### Agent integration

- [Hook runtime](https://github.com/rtk-ai/rtk/blob/develop/src/hooks/hook_cmd.rs): `src/hooks/hook_cmd.rs`
- [Rewrite registry](https://github.com/rtk-ai/rtk/blob/develop/src/discover/registry.rs): `src/discover/registry.rs`
- [Agent setup](https://github.com/rtk-ai/rtk/blob/develop/src/hooks/init/mod.rs): `src/hooks/init/mod.rs`

### Command filtering

- [Command handlers](https://github.com/rtk-ai/rtk/tree/develop/src/cmds): `src/cmds`
- [Shell execution](https://github.com/rtk-ai/rtk/blob/develop/src/core/shell.rs): `src/core/shell.rs`
- [Output filters](https://github.com/rtk-ai/rtk/blob/develop/src/core/filter.rs): `src/core/filter.rs`
- [Output formatting](https://github.com/rtk-ai/rtk/blob/develop/src/parser/formatter.rs): `src/parser/formatter.rs`

### Discovery and learning

- [Session discovery](https://github.com/rtk-ai/rtk/blob/develop/src/discover/mod.rs): `src/discover/mod.rs`
- [Command learning](https://github.com/rtk-ai/rtk/blob/develop/src/learn/mod.rs): `src/learn/mod.rs`

### Settings and analytics

- [Configuration](https://github.com/rtk-ai/rtk/blob/develop/src/core/config.rs): `src/core/config.rs`
- [Usage tracking](https://github.com/rtk-ai/rtk/blob/develop/src/core/tracking.rs): `src/core/tracking.rs`
- [Savings analytics](https://github.com/rtk-ai/rtk/blob/develop/src/analytics/gain.rs): `src/analytics/gain.rs`
- [Output recall](https://github.com/rtk-ai/rtk/blob/develop/src/core/retriever.rs): `src/core/retriever.rs`
- [Telemetry commands](https://github.com/rtk-ai/rtk/blob/develop/src/core/telemetry_cmd.rs): `src/core/telemetry_cmd.rs`

### Other components

- **AI agent**
- **Shell commands**

## Connections

- AI agent → Hook runtime: submits commands (evidence: `README.md`)
- Hook runtime → Rewrite registry: checks rewrite (evidence: `src/hooks/hook_cmd.rs`)
- Hook runtime → RTK CLI: rewrites to (evidence: `README.md`)
- RTK CLI → Command handlers: dispatches commands (evidence: `src/main.rs`)
- Command handlers → Shell execution: executes commands (evidence: `src/cmds/system/search.rs`)
- Shell execution → Shell commands: runs process (evidence: `README.md`)
- Command handlers → Output filters: filters output (evidence: `README.md`)
- Output filters → Output formatting: formats results
- RTK CLI → Agent setup: installs hooks (evidence: `README.md`)
- RTK CLI → Configuration: loads settings (evidence: `src/core/config.rs`)
- RTK CLI → Usage tracking: records usage (evidence: `src/core/tracking.rs`)
- Savings analytics → Usage tracking: reads metrics
- RTK CLI → Savings analytics: reports savings (evidence: `README.md`)
- RTK CLI → Output recall: recalls output (evidence: `src/core/retriever.rs`)
- RTK CLI → Session discovery: discovers commands (evidence: `src/main.rs`)
- Session discovery → Rewrite registry: matches commands (evidence: `src/discover/mod.rs`)
- RTK CLI → Command learning: learns commands (evidence: `src/main.rs`)
- RTK CLI → Telemetry commands: manages telemetry (evidence: `src/main.rs`)
