# krypperx/krypper architecture

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

- Interactive diagram: https://gitdiagram.com/krypperx/krypper
- Repository: https://github.com/krypperx/krypper

## Overview

Krypper is an offline-first Rust CLI and in-process task runtime. Users can inspect, list, and create workspace files directly, or run a bounded task: provide decisions interactively or opt into a local model, perform safe workspace actions, and continue, complete, cancel, or checkpoint and resume. The graph also shows task/turn history and checkpoint persistence, plus recursive search. Some subsystem links rely on the SOURCE INDEX or README rather than fully sampled implementations; those evidence limits are reflected by omitting uncertain connections.

Main entry points: [`src/cli.rs`](https://github.com/krypperx/krypper/blob/main/src/cli.rs) (Command Handler), [`src/harness/execution.rs`](https://github.com/krypperx/krypper/blob/main/src/harness/execution.rs) (Turn Execution), [`src/core/lifecycle.rs`](https://github.com/krypperx/krypper/blob/main/src/core/lifecycle.rs) (Task Lifecycle), [`src/tools/workspace_safety.rs`](https://github.com/krypperx/krypper/blob/main/src/tools/workspace_safety.rs) (Safe File Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI Interface"]
  node_cli["Command Handler<br/>[cli.rs]"]
  node_direct_files["Direct File Commands<br/>[cli.rs]"]
end

subgraph group_runtime["Task Runtime"]
  node_loop["Turn Execution<br/>[execution.rs]"]
  node_context["Prompt Context<br/>[context.rs]"]
  node_recovery["Task Recovery<br/>[recovery.rs]"]
  node_verification["Turn Verification<br/>[verification.rs]"]
  node_lifecycle["Task Lifecycle<br/>[lifecycle.rs]"]
  node_task_state["Task State Model<br/>[task.rs]"]
  node_checkpoint["Checkpoint Storage<br/>[checkpoint.rs]"]
end

subgraph group_decision["Decision Sources"]
  node_decision_source["Decision Interface<br/>[agent_loop.rs]"]
  node_providers["Model Providers<br/>[providers.rs]"]
  node_model_adapter["Model Adapter<br/>[mod.rs]"]
end

subgraph group_workspace["Workspace Operations"]
  node_operation_registry["Action Registry<br/>[registry.rs]"]
  node_workspace_safety["Safe File Operations"]
  node_tree_search["Recursive Search<br/>[search.rs]"]
end

node_user(("CLI User"))
node_workspace[("Local Workspace")]
node_ollama{{"Local Ollama"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches file commands"| node_direct_files
node_cli -->|"starts task turns"| node_loop
node_cli -->|"resumes tasks"| node_recovery
node_cli -->|"verifies turns"| node_verification
node_cli -->|"manages task state"| node_lifecycle
node_cli -->|"saves or restores"| node_checkpoint
node_cli -->|"selects decision source"| node_decision_source
node_loop -->|"requests decisions"| node_decision_source
node_loop -->|"builds task context"| node_context
node_loop -->|"records turn activity"| node_lifecycle
node_loop -.->|"executes workspace actions"| node_workspace_safety
node_lifecycle -->|"tracks task transitions"| node_task_state
node_lifecycle -->|"performs safe file operations"| node_workspace_safety
node_lifecycle -->|"serializes session state"| node_checkpoint
node_model_adapter -.->|"adapts provider calls"| node_providers
node_model_adapter -->|"declares model actions"| node_operation_registry
node_model_adapter -->|"builds model prompt"| node_context
node_providers -->|"sends local requests"| node_ollama
node_decision_source -.->|"uses model decisions"| node_model_adapter
node_operation_registry -.->|"defines supported actions"| node_workspace_safety
node_direct_files -->|"reads or writes files"| node_workspace
node_workspace_safety -->|"reads and modifies"| node_workspace
node_workspace_safety -->|"delegates recursive search"| node_tree_search
node_tree_search -->|"searches files"| node_workspace
node_loop -.->|"returns action observations"| node_workspace

click node_cli "https://github.com/krypperx/krypper/blob/main/src/cli.rs"
click node_direct_files "https://github.com/krypperx/krypper/blob/main/src/cli.rs"
click node_loop "https://github.com/krypperx/krypper/blob/main/src/harness/execution.rs"
click node_context "https://github.com/krypperx/krypper/blob/main/src/harness/context.rs"
click node_recovery "https://github.com/krypperx/krypper/blob/main/src/harness/recovery.rs"
click node_verification "https://github.com/krypperx/krypper/blob/main/src/harness/verification.rs"
click node_lifecycle "https://github.com/krypperx/krypper/blob/main/src/core/lifecycle.rs"
click node_task_state "https://github.com/krypperx/krypper/blob/main/src/core/task.rs"
click node_checkpoint "https://github.com/krypperx/krypper/blob/main/src/core/lifecycle/checkpoint.rs"
click node_decision_source "https://github.com/krypperx/krypper/blob/main/src/agent_loop.rs"
click node_providers "https://github.com/krypperx/krypper/blob/main/src/brain/providers.rs"
click node_model_adapter "https://github.com/krypperx/krypper/blob/main/src/brain/mod.rs"
click node_operation_registry "https://github.com/krypperx/krypper/blob/main/src/tools/registry.rs"
click node_workspace_safety "https://github.com/krypperx/krypper/blob/main/src/tools/workspace_safety.rs"
click node_tree_search "https://github.com/krypperx/krypper/blob/main/src/tools/workspace_safety/search.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_direct_files,node_user toneBlue
class node_loop,node_context,node_recovery,node_verification,node_lifecycle,node_task_state,node_checkpoint,node_workspace toneAmber
class node_decision_source,node_providers,node_model_adapter toneMint
class node_operation_registry,node_workspace_safety,node_tree_search toneRose
class node_ollama toneIndigo
```

## Components

### CLI Interface

- [Command Handler](https://github.com/krypperx/krypper/blob/main/src/cli.rs): `src/cli.rs`
- [Direct File Commands](https://github.com/krypperx/krypper/blob/main/src/cli.rs): `src/cli.rs`

### Task Runtime

- [Turn Execution](https://github.com/krypperx/krypper/blob/main/src/harness/execution.rs): `src/harness/execution.rs`
- [Prompt Context](https://github.com/krypperx/krypper/blob/main/src/harness/context.rs): `src/harness/context.rs`
- [Task Recovery](https://github.com/krypperx/krypper/blob/main/src/harness/recovery.rs): `src/harness/recovery.rs`
- [Turn Verification](https://github.com/krypperx/krypper/blob/main/src/harness/verification.rs): `src/harness/verification.rs`
- [Task Lifecycle](https://github.com/krypperx/krypper/blob/main/src/core/lifecycle.rs): `src/core/lifecycle.rs`
- [Task State Model](https://github.com/krypperx/krypper/blob/main/src/core/task.rs): `src/core/task.rs`
- [Checkpoint Storage](https://github.com/krypperx/krypper/blob/main/src/core/lifecycle/checkpoint.rs): `src/core/lifecycle/checkpoint.rs`

### Decision Sources

- [Decision Interface](https://github.com/krypperx/krypper/blob/main/src/agent_loop.rs): `src/agent_loop.rs`
- [Model Providers](https://github.com/krypperx/krypper/blob/main/src/brain/providers.rs): `src/brain/providers.rs`
- [Model Adapter](https://github.com/krypperx/krypper/blob/main/src/brain/mod.rs): `src/brain/mod.rs`

### Workspace Operations

- [Action Registry](https://github.com/krypperx/krypper/blob/main/src/tools/registry.rs): `src/tools/registry.rs`
- [Safe File Operations](https://github.com/krypperx/krypper/blob/main/src/tools/workspace_safety.rs): `src/tools/workspace_safety.rs`
- [Recursive Search](https://github.com/krypperx/krypper/blob/main/src/tools/workspace_safety/search.rs): `src/tools/workspace_safety/search.rs`

### Other components

- **CLI User**
- **Local Workspace**
- **Local Ollama**

## Connections

- CLI User → Command Handler: runs commands (evidence: `README.md`)
- Command Handler → Direct File Commands: dispatches file commands (evidence: `README.md`)
- Command Handler → Turn Execution: starts task turns (evidence: `src/cli.rs`)
- Command Handler → Task Recovery: resumes tasks (evidence: `src/cli.rs`)
- Command Handler → Turn Verification: verifies turns (evidence: `src/cli.rs`)
- Command Handler → Task Lifecycle: manages task state (evidence: `src/cli.rs`)
- Command Handler → Checkpoint Storage: saves or restores (evidence: `README.md`)
- Command Handler → Decision Interface: selects decision source (evidence: `src/cli.rs`)
- Turn Execution → Decision Interface: requests decisions (evidence: `src/agent_loop.rs`)
- Turn Execution → Prompt Context: builds task context (evidence: `src/harness/context.rs`)
- Turn Execution → Task Lifecycle: records turn activity (evidence: `src/harness/execution.rs`)
- Turn Execution → Safe File Operations: executes workspace actions
- Task Lifecycle → Task State Model: tracks task transitions (evidence: `src/core/lifecycle.rs`)
- Task Lifecycle → Safe File Operations: performs safe file operations (evidence: `src/core/lifecycle.rs`)
- Task Lifecycle → Checkpoint Storage: serializes session state (evidence: `src/core/lifecycle/checkpoint.rs`)
- Model Adapter → Model Providers: adapts provider calls (evidence: `src/brain/mod.rs`)
- Model Adapter → Action Registry: declares model actions (evidence: `src/brain/mod.rs`)
- Model Adapter → Prompt Context: builds model prompt (evidence: `src/brain/mod.rs`)
- Model Providers → Local Ollama: sends local requests
- Decision Interface → Model Adapter: uses model decisions (evidence: `src/brain/mod.rs`)
- Action Registry → Safe File Operations: defines supported actions
- Direct File Commands → Local Workspace: reads or writes files (evidence: `README.md`)
- Safe File Operations → Local Workspace: reads and modifies
- Safe File Operations → Recursive Search: delegates recursive search (evidence: `src/tools/workspace_safety.rs`)
- Recursive Search → Local Workspace: searches files (evidence: `README.md`)
- Turn Execution → Local Workspace: returns action observations