# spenceriam/impulse architecture

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

- Interactive diagram: https://gitdiagram.com/spenceriam/impulse
- Repository: https://github.com/spenceriam/impulse

## Overview

Impulse is a provider-flexible terminal coding agent. The principal workflow starts in the interactive terminal, sends user turns through the agent’s tool-execution loop and configured model provider, then presents responses and tool results in the terminal while retaining session history. Separate branches cover shell and web research, vision, planning/advisor workflows, parallel tasks, and session management. The graph combines README capability statements with the supplied excerpts and SOURCE INDEX; links to unsampled subsystems are included only where documented, and evidence limits leave some internal calls unspecified.

Main entry points: [`src/agent/loop.ts`](https://github.com/spenceriam/impulse/blob/main/src/agent/loop.ts) (Agent turn loop), [`src/api/manager.ts`](https://github.com/spenceriam/impulse/blob/main/src/api/manager.ts) (Provider routing), [`src/session/manager.ts`](https://github.com/spenceriam/impulse/blob/main/src/session/manager.ts) (Session lifecycle), [`src/tools/registry.ts`](https://github.com/spenceriam/impulse/blob/main/src/tools/registry.ts) (Tool registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_terminal["Terminal experience"]
  node_entry["CLI startup<br/>[index.ts]"]
  node_renderer["Terminal renderer<br/>[renderer.ts]"]
  node_prompt["Prompt input<br/>[prompt-input.ts]"]
  node_commands["Slash commands<br/>[slash-dispatch.ts]"]
end

subgraph group_agent["Agent workflows"]
  node_agentloop["Agent turn loop<br/>[loop.ts]"]
  node_orchestrator["Tool orchestrator<br/>[orchestrator.ts]"]
  node_advisor["Advisor workflow<br/>[advisor.ts]"]
  node_vision["Vision routing<br/>[vision-probe.ts]"]
  node_task["Parallel subagents<br/>[task.ts]"]
end

subgraph group_models["Model connectivity"]
  node_provider_manager["Provider routing<br/>[manager.ts]"]
  node_provider_api["Provider interface<br/>[provider.ts]"]
  node_provider_impl["Provider adapters<br/>[ollama.ts]"]
  node_capabilities["Model capabilities<br/>[capabilities.ts]"]
end

subgraph group_sessions["Sessions and state"]
  node_config["Configuration<br/>[config.ts]"]
  node_session_manager["Session lifecycle<br/>[manager.ts]"]
  node_session_store[("Session store<br/>[store.ts]")]
  node_compact["Context compaction<br/>[compact.ts]"]
  node_active_marker["Resume marker"]
  node_bus["Event bus<br/>[bus.ts]"]
  node_storage[("Storage backend<br/>[storage.ts]")]
end

subgraph group_tools["Tools and permissions"]
  node_registry["Tool registry<br/>[registry.ts]"]
  node_tool_notes["Tool guidance<br/>[tool-notes.ts]"]
  node_permissions["Permission handling<br/>[index.ts]"]
  node_shell["Shell commands<br/>[bash.ts]"]
  node_web["Web research<br/>[web-search.ts]"]
end

node_user(("Developer"))

node_user -->|"starts"| node_entry
node_entry -->|"starts interface"| node_renderer
node_user -->|"enters turns"| node_prompt
node_prompt -.->|"submits turn"| node_agentloop
node_renderer -.->|"presents agent workflow"| node_agentloop
node_agentloop -.->|"requests model"| node_provider_manager
node_provider_manager -->|"loads configuration"| node_config
node_provider_manager -->|"registers providers"| node_provider_impl
node_provider_impl -->|"implements interface"| node_provider_api
node_provider_manager -->|"routes capabilities"| node_capabilities
node_agentloop -.->|"dispatches tools"| node_orchestrator
node_orchestrator -->|"uses registry"| node_registry
node_registry -->|"loads guidance"| node_tool_notes
node_registry -.->|"offers command tool"| node_shell
node_registry -->|"offers research tools"| node_web
node_agentloop -.->|"requests approval"| node_permissions
node_user -->|"issues commands"| node_commands
node_commands -.->|"manages sessions"| node_session_manager
node_session_manager -->|"reads and writes"| node_session_store
node_session_manager -->|"updates resume marker"| node_active_marker
node_session_manager -->|"compacts context"| node_compact
node_session_store -->|"uses storage"| node_storage
node_session_store -->|"publishes events"| node_bus
node_agentloop -->|"supports advisor mode"| node_advisor
node_agentloop -->|"routes image input"| node_vision
node_agentloop -->|"runs parallel tasks"| node_task
node_shell -->|"shows command output"| node_user

click node_entry "https://github.com/spenceriam/impulse/blob/main/src/index.ts"
click node_renderer "https://github.com/spenceriam/impulse/blob/main/src/cli/renderer.ts"
click node_prompt "https://github.com/spenceriam/impulse/blob/main/src/cli/prompt-input.ts"
click node_commands "https://github.com/spenceriam/impulse/blob/main/src/cli/slash-dispatch.ts"
click node_agentloop "https://github.com/spenceriam/impulse/blob/main/src/agent/loop.ts"
click node_orchestrator "https://github.com/spenceriam/impulse/blob/main/src/agent/orchestrator.ts"
click node_advisor "https://github.com/spenceriam/impulse/blob/main/src/agent/advisor.ts"
click node_vision "https://github.com/spenceriam/impulse/blob/main/src/api/vision-probe.ts"
click node_task "https://github.com/spenceriam/impulse/blob/main/src/tools/task.ts"
click node_provider_manager "https://github.com/spenceriam/impulse/blob/main/src/api/manager.ts"
click node_provider_api "https://github.com/spenceriam/impulse/blob/main/src/api/provider.ts"
click node_provider_impl "https://github.com/spenceriam/impulse/blob/main/src/api/providers/ollama.ts"
click node_capabilities "https://github.com/spenceriam/impulse/blob/main/src/api/capabilities.ts"
click node_config "https://github.com/spenceriam/impulse/blob/main/src/util/config.ts"
click node_session_manager "https://github.com/spenceriam/impulse/blob/main/src/session/manager.ts"
click node_session_store "https://github.com/spenceriam/impulse/blob/main/src/session/store.ts"
click node_compact "https://github.com/spenceriam/impulse/blob/main/src/session/compact.ts"
click node_active_marker "https://github.com/spenceriam/impulse/blob/main/src/util/active-session-marker.ts"
click node_registry "https://github.com/spenceriam/impulse/blob/main/src/tools/registry.ts"
click node_tool_notes "https://github.com/spenceriam/impulse/blob/main/src/tools/tool-notes.ts"
click node_permissions "https://github.com/spenceriam/impulse/blob/main/src/permission/index.ts"
click node_shell "https://github.com/spenceriam/impulse/blob/main/src/tools/bash.ts"
click node_web "https://github.com/spenceriam/impulse/blob/main/src/tools/web-search.ts"
click node_bus "https://github.com/spenceriam/impulse/blob/main/src/bus/bus.ts"
click node_storage "https://github.com/spenceriam/impulse/blob/main/src/storage/storage.ts"

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_entry,node_renderer,node_prompt,node_commands toneBlue
class node_agentloop,node_orchestrator,node_advisor,node_vision,node_task toneAmber
class node_provider_manager,node_provider_api,node_provider_impl,node_capabilities toneMint
class node_config,node_session_manager,node_session_store,node_compact,node_active_marker,node_bus,node_storage toneRose
class node_registry,node_tool_notes,node_permissions,node_shell,node_web,node_user toneIndigo
```

## Components

### Terminal experience

- [CLI startup](https://github.com/spenceriam/impulse/blob/main/src/index.ts): `src/index.ts`
- [Terminal renderer](https://github.com/spenceriam/impulse/blob/main/src/cli/renderer.ts): `src/cli/renderer.ts`
- [Prompt input](https://github.com/spenceriam/impulse/blob/main/src/cli/prompt-input.ts): `src/cli/prompt-input.ts`
- [Slash commands](https://github.com/spenceriam/impulse/blob/main/src/cli/slash-dispatch.ts): `src/cli/slash-dispatch.ts`

### Agent workflows

- [Agent turn loop](https://github.com/spenceriam/impulse/blob/main/src/agent/loop.ts): `src/agent/loop.ts`
- [Tool orchestrator](https://github.com/spenceriam/impulse/blob/main/src/agent/orchestrator.ts): `src/agent/orchestrator.ts`
- [Advisor workflow](https://github.com/spenceriam/impulse/blob/main/src/agent/advisor.ts): `src/agent/advisor.ts`
- [Vision routing](https://github.com/spenceriam/impulse/blob/main/src/api/vision-probe.ts): `src/api/vision-probe.ts`
- [Parallel subagents](https://github.com/spenceriam/impulse/blob/main/src/tools/task.ts): `src/tools/task.ts`

### Model connectivity

- [Provider routing](https://github.com/spenceriam/impulse/blob/main/src/api/manager.ts): `src/api/manager.ts`
- [Provider interface](https://github.com/spenceriam/impulse/blob/main/src/api/provider.ts): `src/api/provider.ts`
- [Provider adapters](https://github.com/spenceriam/impulse/blob/main/src/api/providers/ollama.ts): `src/api/providers/ollama.ts`
- [Model capabilities](https://github.com/spenceriam/impulse/blob/main/src/api/capabilities.ts): `src/api/capabilities.ts`

### Sessions and state

- [Configuration](https://github.com/spenceriam/impulse/blob/main/src/util/config.ts): `src/util/config.ts`
- [Session lifecycle](https://github.com/spenceriam/impulse/blob/main/src/session/manager.ts): `src/session/manager.ts`
- [Session store](https://github.com/spenceriam/impulse/blob/main/src/session/store.ts): `src/session/store.ts`
- [Context compaction](https://github.com/spenceriam/impulse/blob/main/src/session/compact.ts): `src/session/compact.ts`
- [Resume marker](https://github.com/spenceriam/impulse/blob/main/src/util/active-session-marker.ts): `src/util/active-session-marker.ts`
- [Event bus](https://github.com/spenceriam/impulse/blob/main/src/bus/bus.ts): `src/bus/bus.ts`
- [Storage backend](https://github.com/spenceriam/impulse/blob/main/src/storage/storage.ts): `src/storage/storage.ts`

### Tools and permissions

- [Tool registry](https://github.com/spenceriam/impulse/blob/main/src/tools/registry.ts): `src/tools/registry.ts`
- [Tool guidance](https://github.com/spenceriam/impulse/blob/main/src/tools/tool-notes.ts): `src/tools/tool-notes.ts`
- [Permission handling](https://github.com/spenceriam/impulse/blob/main/src/permission/index.ts): `src/permission/index.ts`
- [Shell commands](https://github.com/spenceriam/impulse/blob/main/src/tools/bash.ts): `src/tools/bash.ts`
- [Web research](https://github.com/spenceriam/impulse/blob/main/src/tools/web-search.ts): `src/tools/web-search.ts`

### Other components

- **Developer**

## Connections

- Developer → CLI startup: starts (evidence: `README.md`)
- CLI startup → Terminal renderer: starts interface (evidence: `src/index.ts`)
- Developer → Prompt input: enters turns (evidence: `README.md`)
- Prompt input → Agent turn loop: submits turn
- Terminal renderer → Agent turn loop: presents agent workflow
- Agent turn loop → Provider routing: requests model
- Provider routing → Configuration: loads configuration (evidence: `src/api/manager.ts`)
- Provider routing → Provider adapters: registers providers (evidence: `src/api/manager.ts`)
- Provider adapters → Provider interface: implements interface (evidence: `src/api/providers/ollama.ts`)
- Provider routing → Model capabilities: routes capabilities
- Agent turn loop → Tool orchestrator: dispatches tools
- Tool orchestrator → Tool registry: uses registry (evidence: `src/agent/orchestrator.ts`)
- Tool registry → Tool guidance: loads guidance (evidence: `src/tools/registry.ts`)
- Tool registry → Shell commands: offers command tool
- Tool registry → Web research: offers research tools (evidence: `src/tools/web-search.ts`)
- Agent turn loop → Permission handling: requests approval
- Developer → Slash commands: issues commands (evidence: `README.md`)
- Slash commands → Session lifecycle: manages sessions
- Session lifecycle → Session store: reads and writes (evidence: `src/session/manager.ts`)
- Session lifecycle → Resume marker: updates resume marker (evidence: `src/session/manager.ts`)
- Session lifecycle → Context compaction: compacts context (evidence: `src/session/manager.ts`)
- Session store → Storage backend: uses storage (evidence: `src/session/store.ts`)
- Session store → Event bus: publishes events (evidence: `src/session/store.ts`)
- Agent turn loop → Advisor workflow: supports advisor mode (evidence: `README.md`)
- Agent turn loop → Vision routing: routes image input (evidence: `README.md`)
- Agent turn loop → Parallel subagents: runs parallel tasks (evidence: `README.md`)
- Shell commands → Developer: shows command output (evidence: `README.md`)
