# ds-madhavan-ramani/oh-my-pi architecture

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

- Interactive diagram: https://gitdiagram.com/ds-madhavan-ramani/oh-my-pi
- Repository: https://github.com/ds-madhavan-ramani/oh-my-pi

## Overview

oh-my-pi is a coding agent with IDE capabilities. A user asks for work; the agent coordinates model turns and tools, then returns results while persisting session state. The README also describes execution kernels, subagents, LSP and debugger integrations, and stream-rule retries. Provider selection and authentication support model calls, while the bundled catalog supplies model metadata. The graph preserves these documented product branches, plus the sampled shell-output minimizer. Several feature implementations were not sampled, so documented relationships cite the README; unsampled internals are represented by existing source directories.

Main entry points: [`packages/coding-agent/src`](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src) (Agent tools), [`packages/agent/src/agent-loop.ts`](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/agent/src/agent-loop.ts) (Agent loop), [`packages/ai/src/stream.ts`](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/stream.ts) (Model streaming), [`packages/ai/src/providers`](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/ai/src/providers) (Model providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_agent["Agent loop<br/>[agent-loop.ts]"]
  node_agenttools["Agent tools"]
  node_subagents["Subagents"]
  node_execution["Code execution"]
  node_streamrules["Stream rules"]
end

subgraph group_ai["Model access"]
  node_ai_stream["Model streaming<br/>[stream.ts]"]
  node_providers["Model providers"]
  node_auth["Credential handling<br/>[auth-storage.ts]"]
  node_retry["Auth retries<br/>[auth-retry.ts]"]
  node_errors["Error classification<br/>[auth-classify.ts]"]
  node_catalog[("Model catalog<br/>[model-manager.ts]")]
end

subgraph group_coding["Coding capabilities"]
  node_lsp["LSP operations"]
  node_debugger["Debugger tools"]
  node_shell["Shell commands"]
  node_minimizer["Output minimizer<br/>[engine.rs]"]
end

subgraph group_state["Session state"]
  node_sessions[("Session storage<br/>[session-storage.ts]")]
  node_indexed[("Indexed sessions")]
  node_compaction["Context compaction"]
end

subgraph group_native["System integration"]
  node_native["Native capabilities"]
end

node_user(("Developer"))
node_external_model(("Model service"))
node_workspace[("Project workspace")]

node_user -->|"requests work"| node_agent
node_agent -.->|"requests model turn"| node_ai_stream
node_ai_stream -->|"dispatches requests"| node_providers
node_providers -.->|"sends requests"| node_external_model
node_ai_stream -->|"resolves credentials"| node_auth
node_auth -->|"rotates credentials"| node_retry
node_retry -->|"classifies failures"| node_errors
node_agent -->|"invokes tools"| node_agenttools
node_agenttools -.->|"reads and edits"| node_workspace
node_agenttools -->|"fans out tasks"| node_subagents
node_agenttools -->|"runs code"| node_execution
node_execution -->|"calls tools"| node_agenttools
node_agenttools -->|"runs IDE operations"| node_lsp
node_agenttools -->|"drives debugger"| node_debugger
node_agent -->|"applies retry rules"| node_streamrules
node_agent -.->|"persists session"| node_sessions
node_indexed -->|"uses storage interface"| node_sessions
node_agent -.->|"compacts context"| node_compaction
node_ai_stream -.->|"selects model"| node_catalog
node_agenttools -.->|"runs commands"| node_shell
node_shell -.->|"filters output"| node_minimizer
node_agenttools -.->|"uses native features"| node_native

click node_agent "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/agent/src/agent-loop.ts"
click node_agenttools "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src"
click node_subagents "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src"
click node_execution "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src"
click node_streamrules "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/agent/src"
click node_sessions "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/coding-agent/src/session/session-storage.ts"
click node_indexed "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/coding-agent/src/session/indexed-session-storage.ts"
click node_compaction "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/agent/src/compaction"
click node_ai_stream "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/stream.ts"
click node_providers "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/ai/src/providers"
click node_auth "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/auth-storage.ts"
click node_retry "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/auth-retry.ts"
click node_errors "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/error/auth-classify.ts"
click node_catalog "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/catalog/src/model-manager.ts"
click node_lsp "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src"
click node_debugger "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src"
click node_shell "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/crates/pi-shell/src"
click node_minimizer "https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/crates/pi-shell/src/minimizer/engine.rs"
click node_native "https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/crates/pi-natives/src"

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_agent,node_agenttools,node_subagents,node_execution,node_streamrules toneBlue
class node_ai_stream,node_providers,node_auth,node_retry,node_errors,node_catalog,node_workspace toneAmber
class node_lsp,node_debugger,node_shell,node_minimizer toneMint
class node_sessions,node_indexed,node_compaction toneRose
class node_native,node_user,node_external_model toneIndigo
```

## Components

### Agent runtime

- [Agent loop](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/agent/src/agent-loop.ts): `packages/agent/src/agent-loop.ts`
- [Agent tools](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src): `packages/coding-agent/src`
- [Subagents](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src): `packages/coding-agent/src`
- [Code execution](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src): `packages/coding-agent/src`
- [Stream rules](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/agent/src): `packages/agent/src`

### Model access

- [Model streaming](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/stream.ts): `packages/ai/src/stream.ts`
- [Model providers](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/ai/src/providers): `packages/ai/src/providers`
- [Credential handling](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/auth-storage.ts): `packages/ai/src/auth-storage.ts`
- [Auth retries](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/auth-retry.ts): `packages/ai/src/auth-retry.ts`
- [Error classification](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/ai/src/error/auth-classify.ts): `packages/ai/src/error/auth-classify.ts`
- [Model catalog](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/catalog/src/model-manager.ts): `packages/catalog/src/model-manager.ts`

### Coding capabilities

- [LSP operations](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src): `packages/coding-agent/src`
- [Debugger tools](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/coding-agent/src): `packages/coding-agent/src`
- [Shell commands](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/crates/pi-shell/src): `crates/pi-shell/src`
- [Output minimizer](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/crates/pi-shell/src/minimizer/engine.rs): `crates/pi-shell/src/minimizer/engine.rs`

### Session state

- [Session storage](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/coding-agent/src/session/session-storage.ts): `packages/coding-agent/src/session/session-storage.ts`
- [Indexed sessions](https://github.com/ds-madhavan-ramani/oh-my-pi/blob/main/packages/coding-agent/src/session/indexed-session-storage.ts): `packages/coding-agent/src/session/indexed-session-storage.ts`
- [Context compaction](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/packages/agent/src/compaction): `packages/agent/src/compaction`

### System integration

- [Native capabilities](https://github.com/ds-madhavan-ramani/oh-my-pi/tree/main/crates/pi-natives/src): `crates/pi-natives/src`

### Other components

- **Developer**
- **Model service**
- **Project workspace**

## Connections

- Developer → Agent loop: requests work (evidence: `README.md`)
- Agent loop → Model streaming: requests model turn
- Model streaming → Model providers: dispatches requests (evidence: `packages/ai/src/stream.ts`)
- Model providers → Model service: sends requests
- Model streaming → Credential handling: resolves credentials (evidence: `packages/ai/src/stream.ts`)
- Credential handling → Auth retries: rotates credentials (evidence: `packages/ai/src/auth-storage.ts`)
- Auth retries → Error classification: classifies failures (evidence: `packages/ai/src/auth-retry.ts`)
- Agent loop → Agent tools: invokes tools (evidence: `README.md`)
- Agent tools → Project workspace: reads and edits
- Agent tools → Subagents: fans out tasks (evidence: `README.md`)
- Agent tools → Code execution: runs code (evidence: `README.md`)
- Code execution → Agent tools: calls tools (evidence: `README.md`)
- Agent tools → LSP operations: runs IDE operations (evidence: `README.md`)
- Agent tools → Debugger tools: drives debugger (evidence: `README.md`)
- Agent loop → Stream rules: applies retry rules (evidence: `README.md`)
- Agent loop → Session storage: persists session
- Indexed sessions → Session storage: uses storage interface (evidence: `packages/coding-agent/src/session/indexed-session-storage.ts`)
- Agent loop → Context compaction: compacts context
- Model streaming → Model catalog: selects model
- Agent tools → Shell commands: runs commands
- Shell commands → Output minimizer: filters output (evidence: `crates/pi-shell/src/minimizer.rs`)
- Agent tools → Native capabilities: uses native features