# qwen-code-dev-bot/oh-my-cli architecture

> Architecture diagram of the GitHub repository qwen-code-dev-bot/oh-my-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qwen-code-dev-bot/oh-my-cli
- Repository: https://github.com/qwen-code-dev-bot/oh-my-cli

## Overview

#### Purpose and entry points
`oh-my-cli` is a Node.js 22, TypeScript/ESM code-agent CLI: it sends model requests, executes confined file/shell tools, persists sessions, and provides deterministic read-only planning, verification, review, and delivery commands. The main CLI dispatcher is `src/index.ts`; the agent execution loop is `src/agent.ts`. It supports interactive terminal UI, non-interactive prompts, NDJSON automation output, optional desktop packaging, and a loopback-only delivery web surface.
Paths: `src/index.ts`, `src/agent.ts`, `src/tui-shell.ts`

#### Model-backed agent loop
The core control flow is: resolve settings/model → compose workspace and instruction context → call an OpenAI-compatible provider → aggregate text/tool calls → gate and execute tools → append session events → repeat, capped at 30 rounds and governed by a spend budget. Provider retries, token/cost estimation, and headless event reporting wrap this loop.
Paths: `src/config.ts`, `src/provider.ts`, `src/cost.ts`

#### Workspace tools and safety boundary
Built-in read/list/glob/grep/write/edit/shell tools are confined to the canonical workspace and reject symlink escapes. Mutations pass layered controls: folder-trust/sandbox posture, deterministic shell command policy, approval mode, and redacted impact preview. Read-only discovery remains available without approval.
Paths: `src/tools.ts`, `src/workspace.ts`, `src/folder-trust.ts`
Paths: `src/command-policy.ts`, `src/approval.ts`, `src/permission-impact.ts`

#### Durable session and recovery subsystem
Sessions are persisted as JSONL in the user state directory. Supporting sidecars provide fail-closed transcript compaction, atomic export, turn-scoped content checkpoints for undo/redo, and isolated side questions that receive no workspace/session mutation handles. Session stats, task monitoring, and LSP status are read-only projections over persisted or runtime state.
Paths: `src/session.ts`, `src/compaction.ts`, `src/turn-checkpoint.ts`
Paths: `src/side-question.ts`, `src/session-stats.ts`, `src/task-runtime.ts`

#### Repository intelligence and delivery pipeline
A read-only repository layer derives context, ranked symbol maps, trusted instruction context, and canonical verification commands. The delivery pipeline composes deterministic stages: plan → run canonical verification → Git-based change review → CI handoff → delivery verdict. These commands are head-bound, bounded, redacted, and generally avoid model calls.
Paths: `src/repo-context.ts`, `src/repo-map.ts`, `src/instruction-context.ts`
Paths: `src/task-plan.ts`, `src/task-verify.ts`, `src/change-review.ts`
Paths: `src/ci-handoff.ts`, `src/delivery-brief.ts`

#### Extensions, automation, and external services
Primary external service is an OpenAI-compatible HTTP model endpoint configured from environment variables and user-owned settings. Versioned contracts also govern provider, local command-tool, stdio MCP, and workflow integrations; contract resolution is read-only, while invocation is approval/policy-gated and timeout-bounded. Workflows execute sequential isolated headless prompt steps.
Paths: `src/provider-contract.ts`, `src/mcp-contract.ts`, `src/tool-contract.ts`
Paths: `src/provider-invocation.ts`, `src/mcp-invocation.ts`, `src/workflow-runner.ts`

#### Interfaces and infrastructure
The terminal interface includes a TUI shell and a versioned NDJSON protocol for CI/automation. Optional Electron-style desktop separation uses main, preload, renderer, and service layers. A delivery web server exposes constrained browser-native feature pages on loopback only. Git is material infrastructure for readiness, review, recovery evidence, and leased worktree isolation.
Paths: `src/headless-protocol.ts`, `src/desktop/main.ts`, `src/desktop/preload.ts`
Paths: `src/delivery-web.ts`, `src/worktree-lease.ts`, `src/evidence-archive.ts`

Main entry points: [`src/agent.ts`](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/agent.ts) (Agent loop), [`src/index.ts`](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/index.ts) (CLI dispatcher), [`src/tools.ts`](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/tools.ts) (Workspace tools), [`src/session.ts`](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/session.ts) (Session store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & Interfaces"]
  node_cli_dispatcher["CLI dispatcher<br/>Node.js CLI<br/>[index.ts]"]
  node_terminal_ui["Terminal UI<br/>TUI shell<br/>[tui-shell.ts]"]
  node_headless_protocol["Automation protocol<br/>NDJSON protocol"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_loop{{"Agent loop<br/>control loop<br/>[agent.ts]"}}
  node_model_config["Model settings<br/>configuration resolver<br/>[config.ts]"]
  node_provider["Model provider<br/>OpenAI-compatible client<br/>[provider.ts]"]
  node_cost_control["Cost control<br/>token accounting<br/>[cost.ts]"]
end

subgraph group_safety["Workspace Safety"]
  node_workspace_tools["Workspace tools<br/>file and shell tools<br/>[tools.ts]"]
  node_workspace_boundary["Workspace boundary<br/>path confinement<br/>[workspace.ts]"]
  node_mutation_gates{{"Mutation gates<br/>approval and policy<br/>[approval.ts]"}}
end

subgraph group_state["Sessions &amp; Recovery"]
  node_sessions[("Session store<br/>JSONL persistence<br/>[session.ts]")]
  node_compaction["Transcript compaction<br/>recovery sidecar<br/>[compaction.ts]"]
  node_turn_checkpoints["Turn checkpoints<br/>undo/redo store<br/>[turn-checkpoint.ts]"]
end

subgraph group_delivery["Repository Delivery"]
  node_repo_intelligence["Repository intelligence<br/>read-only context<br/>[repo-context.ts]"]
  node_task_plan["Task planning<br/>deterministic stage<br/>[task-plan.ts]"]
  node_task_verify["Canonical verification<br/>deterministic stage<br/>[task-verify.ts]"]
  node_change_review["Change review<br/>Git review stage<br/>[change-review.ts]"]
  node_delivery_brief["Delivery verdict<br/>delivery stage<br/>[delivery-brief.ts]"]
  node_git_infrastructure["Git evidence &amp; worktrees<br/>repository infrastructure<br/>[worktree-lease.ts]"]
end

subgraph group_integrations["Extensions &amp; Services"]
  node_contracts_invocation["Contract invocation<br/>integration boundary"]
  node_workflow_runner["Workflow runner<br/>headless automation<br/>[workflow-runner.ts]"]
  node_model_endpoint(("Model endpoint<br/>external HTTP service"))
end

node_cli_dispatcher -->|"interactive mode"| node_terminal_ui
node_cli_dispatcher -->|"automation output"| node_headless_protocol
node_cli_dispatcher -->|"starts agent"| node_agent_loop
node_cli_dispatcher -->|"planning command"| node_task_plan
node_cli_dispatcher -->|"delivery command"| node_delivery_brief
node_agent_loop -->|"resolves settings"| node_model_config
node_model_config -->|"configures"| node_provider
node_agent_loop -->|"model requests"| node_provider
node_provider -->|"HTTP requests"| node_model_endpoint
node_agent_loop -->|"enforces budget"| node_cost_control
node_agent_loop -->|"composes context"| node_repo_intelligence
node_agent_loop -->|"executes tool calls"| node_workspace_tools
node_workspace_tools -->|"confined by"| node_workspace_boundary
node_workspace_tools -->|"mutations require"| node_mutation_gates
node_agent_loop -->|"appends events"| node_sessions
node_sessions -->|"compacts and exports"| node_compaction
node_sessions -->|"turn recovery"| node_turn_checkpoints
node_repo_intelligence -->|"planning context"| node_task_plan
node_task_plan -->|"plan then verify"| node_task_verify
node_task_verify -->|"verified changes"| node_change_review
node_change_review -->|"review evidence"| node_delivery_brief
node_git_infrastructure -->|"Git state and evidence"| node_change_review
node_contracts_invocation -->|"approval and policy"| node_mutation_gates
node_workflow_runner -->|"isolated prompt steps"| node_agent_loop
node_workflow_runner -->|"headless events"| node_headless_protocol

click node_cli_dispatcher "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/index.ts"
click node_terminal_ui "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/tui-shell.ts"
click node_headless_protocol "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/headless-protocol.ts"
click node_agent_loop "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/agent.ts"
click node_model_config "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/config.ts"
click node_provider "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/provider.ts"
click node_cost_control "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/cost.ts"
click node_workspace_tools "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/tools.ts"
click node_workspace_boundary "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/workspace.ts"
click node_mutation_gates "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/approval.ts"
click node_sessions "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/session.ts"
click node_compaction "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/compaction.ts"
click node_turn_checkpoints "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/turn-checkpoint.ts"
click node_repo_intelligence "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/repo-context.ts"
click node_task_plan "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/task-plan.ts"
click node_task_verify "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/task-verify.ts"
click node_change_review "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/change-review.ts"
click node_delivery_brief "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/delivery-brief.ts"
click node_contracts_invocation "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/provider-invocation.ts"
click node_workflow_runner "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/workflow-runner.ts"
click node_git_infrastructure "https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/worktree-lease.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_cli_dispatcher,node_terminal_ui,node_headless_protocol toneBlue
class node_agent_loop,node_model_config,node_provider,node_cost_control toneAmber
class node_workspace_tools,node_workspace_boundary,node_mutation_gates toneMint
class node_sessions,node_compaction,node_turn_checkpoints toneRose
class node_repo_intelligence,node_task_plan,node_task_verify,node_change_review,node_delivery_brief,node_git_infrastructure toneIndigo
class node_contracts_invocation,node_workflow_runner,node_model_endpoint toneTeal
```

## Components

### CLI & Interfaces

- [CLI dispatcher](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/index.ts): Node.js CLI · Selects interactive, headless, planning, and delivery commands. · `src/index.ts`
- [Terminal UI](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/tui-shell.ts): TUI shell · `src/tui-shell.ts`
- [Automation protocol](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/headless-protocol.ts): NDJSON protocol · `src/headless-protocol.ts`

### Agent Runtime

- [Agent loop](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/agent.ts): control loop · Runs bounded model/tool rounds under a spend budget. · `src/agent.ts`
- [Model settings](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/config.ts): configuration resolver · `src/config.ts`
- [Model provider](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/provider.ts): OpenAI-compatible client · Retries model requests and aggregates text and tool calls. · `src/provider.ts`
- [Cost control](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/cost.ts): token accounting · `src/cost.ts`

### Workspace Safety

- [Workspace tools](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/tools.ts): file and shell tools · Provides confined read, mutation, and shell operations. · `src/tools.ts`
- [Workspace boundary](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/workspace.ts): path confinement · Enforces canonical workspace paths and rejects symlink escapes. · `src/workspace.ts`
- [Mutation gates](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/approval.ts): approval and policy · Combines trust posture, shell policy, approval, and impact preview. · `src/approval.ts`

### Sessions & Recovery

- [Session store](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/session.ts): JSONL persistence · Durable agent event history in the user state directory. · `src/session.ts`
- [Transcript compaction](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/compaction.ts): recovery sidecar · Fail-closed transcript compaction and atomic export. · `src/compaction.ts`
- [Turn checkpoints](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/turn-checkpoint.ts): undo/redo store · `src/turn-checkpoint.ts`

### Repository Delivery

- [Repository intelligence](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/repo-context.ts): read-only context · Derives repository context, symbol maps, instructions, and verification commands. · `src/repo-context.ts`
- [Task planning](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/task-plan.ts): deterministic stage · `src/task-plan.ts`
- [Canonical verification](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/task-verify.ts): deterministic stage · Runs bounded, redacted repository verification commands. · `src/task-verify.ts`
- [Change review](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/change-review.ts): Git review stage · `src/change-review.ts`
- [Delivery verdict](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/delivery-brief.ts): delivery stage · Produces CI handoff and delivery readiness verdict. · `src/delivery-brief.ts`
- [Git evidence & worktrees](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/worktree-lease.ts): repository infrastructure · Supports review, recovery evidence, and leased worktree isolation. · `src/worktree-lease.ts`

### Extensions & Services

- [Contract invocation](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/provider-invocation.ts): integration boundary · Resolves versioned provider, tool, and MCP contracts and invokes them under gates. · `src/provider-invocation.ts`
- [Workflow runner](https://github.com/qwen-code-dev-bot/oh-my-cli/blob/main/src/workflow-runner.ts): headless automation · Executes sequential isolated prompt steps. · `src/workflow-runner.ts`
- **Model endpoint**: external HTTP service · OpenAI-compatible endpoint configured by environment and user settings.

## Connections

- CLI dispatcher → Terminal UI: interactive mode
- CLI dispatcher → Automation protocol: automation output
- CLI dispatcher → Agent loop: starts agent
- CLI dispatcher → Task planning: planning command
- CLI dispatcher → Delivery verdict: delivery command
- Agent loop → Model settings: resolves settings
- Model settings → Model provider: configures
- Agent loop → Model provider: model requests
- Model provider → Model endpoint: HTTP requests
- Agent loop → Cost control: enforces budget
- Agent loop → Repository intelligence: composes context
- Agent loop → Workspace tools: executes tool calls
- Workspace tools → Workspace boundary: confined by
- Workspace tools → Mutation gates: mutations require
- Agent loop → Session store: appends events
- Session store → Transcript compaction: compacts and exports
- Session store → Turn checkpoints: turn recovery
- Repository intelligence → Task planning: planning context
- Task planning → Canonical verification: plan then verify
- Canonical verification → Change review: verified changes
- Change review → Delivery verdict: review evidence
- Git evidence & worktrees → Change review: Git state and evidence
- Contract invocation → Mutation gates: approval and policy
- Workflow runner → Agent loop: isolated prompt steps
- Workflow runner → Automation protocol: headless events