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

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