# stakpak/agent architecture

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

- Interactive diagram: https://gitdiagram.com/stakpak/agent
- Repository: https://github.com/stakpak/agent

## Overview

Stakpak is a DevOps agent that runs locally, interactively or as an always-on autopilot, to investigate infrastructure and perform operational work under configurable guardrails. The main workflow is: a user starts a CLI or TUI session; the agent builds context, consults an AI provider, and uses tools to inspect or change the environment; session state and results are retained or delivered through configured channels. The graph also captures documented search, indexing, knowledge, and task-management capabilities. README claims guide unsampled feature branches; edges are limited to documented relationships and workspace structure.

Main entry points: [`libs/agent-core/src/tools.rs`](https://github.com/stakpak/agent/blob/main/libs/agent-core/src/tools.rs) (Agent tools), [`cli/src/commands/agent/run/mod.rs`](https://github.com/stakpak/agent/blob/main/cli/src/commands/agent/run/mod.rs) (Agent run), [`libs/agent-core/src/agent.rs`](https://github.com/stakpak/agent/blob/main/libs/agent-core/src/agent.rs) (Agent engine), [`cli/src/commands/autopilot/mod.rs`](https://github.com/stakpak/agent/blob/main/cli/src/commands/autopilot/mod.rs) (Autopilot scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_tui["Terminal UI<br/>[app.rs]"]
end

subgraph group_agent["Agent runtime"]
  node_run["Agent run<br/>[mod.rs]"]
  node_core["Agent engine<br/>[agent.rs]"]
  node_ai["Model dispatch<br/>[dispatcher.rs]"]
  node_providers["AI providers<br/>[mod.rs]"]
  node_sessions[("Session storage<br/>[storage.rs]")]
  node_server["Session API<br/>[routes.rs]"]
end

subgraph group_knowledge["Context and knowledge"]
  node_context["Local context<br/>[builder.rs]"]
  node_search["Web research<br/>[search_service.rs]"]
  node_index["Code indexing<br/>[code_index.rs]"]
  node_knowledge_store[("Knowledge store<br/>[mod.rs]")]
end

subgraph group_operations["Operations and safety"]
  node_tools["Agent tools<br/>[tools.rs]"]
  node_mcp["MCP tools<br/>[tool_container.rs]"]
  node_approvals["Shell approvals<br/>[lib.rs]"]
  node_tasks["Background tasks<br/>[task_manager.rs]"]
end

subgraph group_autopilot["Autopilot and delivery"]
  node_autopilot["Autopilot scheduler<br/>[mod.rs]"]
  node_gateway["Message routing<br/>[dispatcher.rs]"]
  node_channels["Chat channels<br/>[mod.rs]"]
end

node_user(("Operator"))
node_llm_service{{"Model services"}}
node_environment{{"Machine and cloud"}}

node_user -->|"starts"| node_cli
node_user -->|"interacts"| node_tui
node_cli -->|"dispatches"| node_run
node_run -->|"runs"| node_core
node_core -->|"requests completion"| node_ai
node_ai -->|"dispatches"| node_providers
node_providers -->|"sends requests"| node_llm_service
node_core -->|"invokes tools"| node_tools
node_tools -.->|"uses MCP tools"| node_mcp
node_tools -->|"checks policy"| node_approvals
node_tools -->|"manages tasks"| node_tasks
node_run -->|"builds context"| node_context
node_tools -.->|"researches web"| node_search
node_run -.->|"indexes projects"| node_index
node_core -->|"stores session state"| node_sessions
node_server -->|"reads and writes"| node_sessions
node_autopilot -->|"starts agent runs"| node_run
node_autopilot -->|"routes notifications"| node_gateway
node_gateway -->|"dispatches messages"| node_channels
node_channels -->|"delivers updates"| node_user
node_tools -->|"operates on"| node_environment
node_run -.->|"uses persistent knowledge"| node_knowledge_store

click node_cli "https://github.com/stakpak/agent/blob/main/cli/src/main.rs"
click node_tui "https://github.com/stakpak/agent/blob/main/tui/src/app.rs"
click node_run "https://github.com/stakpak/agent/blob/main/cli/src/commands/agent/run/mod.rs"
click node_core "https://github.com/stakpak/agent/blob/main/libs/agent-core/src/agent.rs"
click node_ai "https://github.com/stakpak/agent/blob/main/libs/ai/src/provider/dispatcher.rs"
click node_providers "https://github.com/stakpak/agent/blob/main/libs/ai/src/providers/mod.rs"
click node_tools "https://github.com/stakpak/agent/blob/main/libs/agent-core/src/tools.rs"
click node_mcp "https://github.com/stakpak/agent/blob/main/libs/mcp/server/src/tool_container.rs"
click node_approvals "https://github.com/stakpak/agent/blob/main/libs/shell-tool-approvals/src/lib.rs"
click node_tasks "https://github.com/stakpak/agent/blob/main/libs/shared/src/task_manager.rs"
click node_context "https://github.com/stakpak/agent/blob/main/libs/server/src/context/builder.rs"
click node_search "https://github.com/stakpak/agent/blob/main/libs/shared/src/models/integrations/search_service.rs"
click node_index "https://github.com/stakpak/agent/blob/main/cli/src/code_index.rs"
click node_knowledge_store "https://github.com/stakpak/agent/blob/main/libs/api/src/stakpak/knowledge/mod.rs"
click node_sessions "https://github.com/stakpak/agent/blob/main/libs/api/src/storage.rs"
click node_server "https://github.com/stakpak/agent/blob/main/libs/server/src/routes.rs"
click node_autopilot "https://github.com/stakpak/agent/blob/main/cli/src/commands/autopilot/mod.rs"
click node_gateway "https://github.com/stakpak/agent/blob/main/libs/gateway/src/dispatcher.rs"
click node_channels "https://github.com/stakpak/agent/blob/main/libs/gateway/src/channels/mod.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 toneBlue
class node_run,node_core,node_ai,node_providers,node_sessions,node_server toneAmber
class node_context,node_search,node_index,node_knowledge_store toneMint
class node_tools,node_mcp,node_approvals,node_tasks toneRose
class node_autopilot,node_gateway,node_channels,node_user,node_llm_service,node_environment toneIndigo
```

## Components

### User interaction

- [CLI commands](https://github.com/stakpak/agent/blob/main/cli/src/main.rs): `cli/src/main.rs`
- [Terminal UI](https://github.com/stakpak/agent/blob/main/tui/src/app.rs): `tui/src/app.rs`

### Agent runtime

- [Agent run](https://github.com/stakpak/agent/blob/main/cli/src/commands/agent/run/mod.rs): `cli/src/commands/agent/run/mod.rs`
- [Agent engine](https://github.com/stakpak/agent/blob/main/libs/agent-core/src/agent.rs): `libs/agent-core/src/agent.rs`
- [Model dispatch](https://github.com/stakpak/agent/blob/main/libs/ai/src/provider/dispatcher.rs): `libs/ai/src/provider/dispatcher.rs`
- [AI providers](https://github.com/stakpak/agent/blob/main/libs/ai/src/providers/mod.rs): `libs/ai/src/providers/mod.rs`
- [Session storage](https://github.com/stakpak/agent/blob/main/libs/api/src/storage.rs): `libs/api/src/storage.rs`
- [Session API](https://github.com/stakpak/agent/blob/main/libs/server/src/routes.rs): `libs/server/src/routes.rs`

### Context and knowledge

- [Local context](https://github.com/stakpak/agent/blob/main/libs/server/src/context/builder.rs): `libs/server/src/context/builder.rs`
- [Web research](https://github.com/stakpak/agent/blob/main/libs/shared/src/models/integrations/search_service.rs): `libs/shared/src/models/integrations/search_service.rs`
- [Code indexing](https://github.com/stakpak/agent/blob/main/cli/src/code_index.rs): `cli/src/code_index.rs`
- [Knowledge store](https://github.com/stakpak/agent/blob/main/libs/api/src/stakpak/knowledge/mod.rs): `libs/api/src/stakpak/knowledge/mod.rs`

### Operations and safety

- [Agent tools](https://github.com/stakpak/agent/blob/main/libs/agent-core/src/tools.rs): `libs/agent-core/src/tools.rs`
- [MCP tools](https://github.com/stakpak/agent/blob/main/libs/mcp/server/src/tool_container.rs): `libs/mcp/server/src/tool_container.rs`
- [Shell approvals](https://github.com/stakpak/agent/blob/main/libs/shell-tool-approvals/src/lib.rs): `libs/shell-tool-approvals/src/lib.rs`
- [Background tasks](https://github.com/stakpak/agent/blob/main/libs/shared/src/task_manager.rs): `libs/shared/src/task_manager.rs`

### Autopilot and delivery

- [Autopilot scheduler](https://github.com/stakpak/agent/blob/main/cli/src/commands/autopilot/mod.rs): `cli/src/commands/autopilot/mod.rs`
- [Message routing](https://github.com/stakpak/agent/blob/main/libs/gateway/src/dispatcher.rs): `libs/gateway/src/dispatcher.rs`
- [Chat channels](https://github.com/stakpak/agent/blob/main/libs/gateway/src/channels/mod.rs): `libs/gateway/src/channels/mod.rs`

### Other components

- **Operator**
- **Model services**
- **Machine and cloud**

## Connections

- Operator → CLI commands: starts
- Operator → Terminal UI: interacts
- CLI commands → Agent run: dispatches
- Agent run → Agent engine: runs
- Agent engine → Model dispatch: requests completion
- Model dispatch → AI providers: dispatches
- AI providers → Model services: sends requests
- Agent engine → Agent tools: invokes tools
- Agent tools → MCP tools: uses MCP tools
- Agent tools → Shell approvals: checks policy
- Agent tools → Background tasks: manages tasks
- Agent run → Local context: builds context
- Agent tools → Web research: researches web
- Agent run → Code indexing: indexes projects
- Agent engine → Session storage: stores session state
- Session API → Session storage: reads and writes
- Autopilot scheduler → Agent run: starts agent runs
- Autopilot scheduler → Message routing: routes notifications
- Message routing → Chat channels: dispatches messages
- Chat channels → Operator: delivers updates
- Agent tools → Machine and cloud: operates on
- Agent run → Knowledge store: uses persistent knowledge