# vasiniks/sprint architecture

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

- Interactive diagram: https://gitdiagram.com/vasiniks/sprint
- Repository: https://github.com/vasiniks/sprint

## Overview

sprint is a two-module terminal coding agent for local Ollama models. A user enters a request in the terminal UI; the agent sends it to the model, checks proposed tool calls against the selected permission mode, runs approved actions, and returns results in the conversation. The README also describes direct shell input, file and image attachments, plan mode, settings, usage, and update checks. The excerpts expose only selected implementation details, so README-documented relationships are cited there; unsampled internal call paths are not inferred.

Main entry points: [`sprint.py`](https://github.com/vasiniks/sprint/blob/main/sprint.py) (Agent loop), [`sprint_tui.py`](https://github.com/vasiniks/sprint/blob/main/sprint_tui.py) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Terminal interaction"]
  node_cli["CLI entry<br/>[sprint.py]"]
  node_terminal["Terminal UI<br/>[sprint_tui.py]"]
  node_attachments["Message attachments<br/>[sprint.py]"]
  node_conversation["Conversation view<br/>[sprint_tui.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agent["Agent loop<br/>[sprint.py]"]
  node_context["Context budgeting<br/>[sprint.py]"]
  node_model{{"Ollama model"}}
end

subgraph group_actions["Tools and permissions"]
  node_tool_calls["Tool-call checks<br/>[sprint.py]"]
  node_approval["Permission approval<br/>[sprint.py]"]
  node_tool_runner["Tool execution<br/>[sprint.py]"]
  node_plan["Plan mode<br/>[sprint.py]"]
end

subgraph group_state["Settings and services"]
  node_settings["Settings and commands<br/>[sprint.py]"]
  node_config_store[("Config file<br/>[sprint.py]")]
  node_usage_store[("Usage records<br/>[sprint.py]")]
  node_update_check["Version check<br/>[sprint.py]"]
end

node_user(("User"))
node_version_service{{"Repository version"}}

node_user -->|"starts"| node_cli
node_user -->|"enters request"| node_terminal
node_cli -->|"opens"| node_terminal
node_terminal -->|"attaches files"| node_attachments
node_terminal -->|"submits turn"| node_agent
node_agent -->|"fits context"| node_context
node_agent -->|"requests reply"| node_model
node_model -->|"returns response"| node_agent
node_agent -->|"checks calls"| node_tool_calls
node_tool_calls -->|"requests permission"| node_approval
node_approval -->|"allows action"| node_tool_runner
node_tool_runner -->|"returns results"| node_agent
node_agent -->|"shows reply"| node_conversation
node_user -->|"runs shell mode"| node_terminal
node_terminal -->|"selects mode"| node_plan
node_user -->|"configures"| node_settings
node_settings -->|"reads and writes"| node_config_store
node_agent -.->|"records usage"| node_usage_store
node_settings -->|"controls check"| node_update_check
node_update_check -->|"checks version"| node_version_service

click node_cli "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_terminal "https://github.com/vasiniks/sprint/blob/main/sprint_tui.py"
click node_attachments "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_conversation "https://github.com/vasiniks/sprint/blob/main/sprint_tui.py"
click node_agent "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_context "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_tool_calls "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_approval "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_tool_runner "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_plan "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_settings "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_config_store "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_usage_store "https://github.com/vasiniks/sprint/blob/main/sprint.py"
click node_update_check "https://github.com/vasiniks/sprint/blob/main/sprint.py"

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_terminal,node_attachments,node_conversation,node_user toneBlue
class node_agent,node_context,node_model toneAmber
class node_tool_calls,node_approval,node_tool_runner,node_plan toneMint
class node_settings,node_config_store,node_usage_store,node_update_check toneRose
class node_version_service toneIndigo
```

## Components

### Terminal interaction

- [CLI entry](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Terminal UI](https://github.com/vasiniks/sprint/blob/main/sprint_tui.py): `sprint_tui.py`
- [Message attachments](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Conversation view](https://github.com/vasiniks/sprint/blob/main/sprint_tui.py): `sprint_tui.py`

### Agent runtime

- [Agent loop](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Context budgeting](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- **Ollama model**

### Tools and permissions

- [Tool-call checks](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Permission approval](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Tool execution](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Plan mode](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`

### Settings and services

- [Settings and commands](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Config file](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Usage records](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`
- [Version check](https://github.com/vasiniks/sprint/blob/main/sprint.py): `sprint.py`

### Other components

- **User**
- **Repository version**

## Connections

- User → CLI entry: starts (evidence: `README.md`)
- User → Terminal UI: enters request (evidence: `README.md`)
- CLI entry → Terminal UI: opens (evidence: `README.md`)
- Terminal UI → Message attachments: attaches files (evidence: `README.md`)
- Terminal UI → Agent loop: submits turn (evidence: `README.md`)
- Agent loop → Context budgeting: fits context (evidence: `sprint.py`)
- Agent loop → Ollama model: requests reply (evidence: `README.md`)
- Ollama model → Agent loop: returns response (evidence: `sprint.py`)
- Agent loop → Tool-call checks: checks calls (evidence: `README.md`)
- Tool-call checks → Permission approval: requests permission (evidence: `README.md`)
- Permission approval → Tool execution: allows action (evidence: `README.md`)
- Tool execution → Agent loop: returns results (evidence: `README.md`)
- Agent loop → Conversation view: shows reply (evidence: `README.md`)
- User → Terminal UI: runs shell mode (evidence: `README.md`)
- Terminal UI → Plan mode: selects mode (evidence: `README.md`)
- User → Settings and commands: configures (evidence: `README.md`)
- Settings and commands → Config file: reads and writes (evidence: `sprint.py`)
- Agent loop → Usage records: records usage (evidence: `sprint.py`)
- Settings and commands → Version check: controls check (evidence: `README.md`)
- Version check → Repository version: checks version (evidence: `README.md`)