can1357--oh-my-pi/packages/coding-agent/DEVELOPMENT.md

Developing @oh-my-pi/pi-coding-agent

This package is the omp CLI. This file is a developer's map: where things live in src/, how to run the local loops, and — for each subsystem — which document in the repo docs/ tree is the authoritative reference.

The long architecture walkthrough that used to live here drifted out of date faster than anyone re-read it. The docs/ tree is kept current (and indexed for the in-agent docs:// / /docs surface), so this file links there instead of duplicating prose that goes stale.

Local development

Run from packages/coding-agent/ (or add --cwd=packages/coding-agent):

Task	Command
Typecheck + lint (the gate)	bun run check
Types only	bun run check:types
Lint only	bun run lint
Tests	bun run test
Autofix: lint + format prompts + docs index	bun run fix
Reformat prompt .md assets	bun run format-prompts
Regenerate the docs:// index	bun run gen:docs
Build the dist/omp binary	bun run build

Never invoke tsc/npx tsc directly — bun run check is the typecheck gate. After changing the React tool renderers under collab-web/src/tool-render/, rebuild them with bun run gen:tool-views.

Boot flow

process argv
   │
   ▼
src/cli.ts (runCli)            ── worker-host dispatch + Bun version guard;
   │  default subcommand: launch    argv normalization
   ▼
src/commands/* (+ src/cli/)   ── per-command adapters
   │
   ▼
src/main.ts (runRootCommand)  ── theme / settings / model registry / session opts
   │
   ▼
createAgentSession(...)        ── src/sdk.ts → AgentSession
   │
   ├── InteractiveMode   (src/modes/, TUI event loop)
   ├── runPrintMode      (one-shot text/json)
   └── runRpcMode        (JSONL stdin/stdout server)

cli.ts doubles as the worker host: it declares itself via declareWorkerHostEntry() and dispatches the hidden __omp_worker_* argv selectors before loading the command registry (see AGENTS.md → Worker scripts).

Source layout (src/)

Top-level entry modules: cli.ts, main.ts, sdk.ts, index.ts (SDK barrel), config.ts, system-prompt.ts, thinking.ts, workspace-tree.ts, cli-commands.ts, telemetry-export.ts.

Directory	Responsibility	Reference
cli/, commands/, commit/, export/	Command-line adapters and concrete subcommands	—
modes/	Interactive TUI, print, and RPC runtimes	rpc.md, sdk.md
session/	AgentSession, JSONL session tree, storage, history	session.md, session-tree-plan.md
config/, registry/, secrets/	Settings, model/provider registry, secret obfuscation	settings.md, config-usage.md, models.md, secrets.md
tools/	Built-in tool implementations + render/meta helpers	custom-tools.md, tools/
exec/, eval/, ssh/, dap/, debug/	Execution backends (shell, py/js kernels, ssh, debugger)	bash-tool-runtime.md, python-repl.md
lsp/	Language-server client/runtime	lsp-config.md, tools/lsp.md
task/, swarm/, irc/, goals/, plan-mode/	Subagent delegation, parallelism, inter-agent IRC, plan mode	task-agent-discovery.md, tools/task.md
web/, exa/	Fetch, browser automation, search providers, scrapers	tools/web_search.md, tools/browser.md
mcp/	MCP transport / manager / loader / tool bridge	mcp-config.md, mcp-runtime-lifecycle.md
extensibility/, slash-commands/	Extensions, hooks, custom tools/commands, skills, plugins	extensions.md, hooks.md, skills.md
capability/, discovery/, tool-discovery/	Capability registry + provider discovery modules	extension-loading.md, context-files.md
advisor/, autolearn/, autoresearch/	Advisor/watchdog, managed skills, background research	advisor-watchdog.md
memories/, memory-backend/, mnemopi/, hindsight/	Memory subsystems and backends	memory.md, mnemosyne-memory-backend.md
internal-urls/	Router + handlers (agent://, docs://, rule://, …)	tree.md
tui/, collab/	Low-level TUI primitives, live session sharing	tui.md, collab.md
tts/, stt/	Text-to-speech / speech-to-text	—
tiny/, auto-thinking/	Embedded tiny-model experiments, auto thinking level	local-models.md
async/, lib/, utils/, prompts/, edit/	Shared plumbing, prompt assets, patch/diff engine	tools/edit.md

Subsystem reference

Sessions, persistence, and turn lifecycle

• session.md — storage and entry model
• session-tree-plan.md — branch/tree architecture
• session-switching-and-recent-listing.md
• session-operations-export-share-fork-resume.md
• compaction.md — compaction and branch summaries
• ttsr-injection-lifecycle.md
• non-compaction-retry-policy.md
• handoff-generation-pipeline.md

Configuration, models, providers, auth

• settings.md, config-usage.md
• environment-variables.md
• models.md, providers.md, adding-a-provider.md
• local-models.md
• provider-streaming-internals.md, ai-schema-normalize.md
• toolconv/ — per-family tool-call conversion (anthropic, harmony, qwen3, deepseek, glm-4.5, kimi-k2, gemini, gemma, pi-native); see also ERRATA-GPT5-HARMONY.md
• keybindings.md
• secrets.md, auth-broker-gateway.md, install-id.md
• system-prompt-customization.md

Tools framework and built-in tools

• Authoring + registry: custom-tools.md
• Output/artifacts: blob-artifact-architecture.md
• Gating/approval: approval-mode.md, resolve-tool-runtime.md
• Per-tool reference: docs/tools/ — read, write, edit, ast-edit, ast-grep, search, search_tool_bm25, find, bash, eval, job, lsp, debug, task, irc, web_search, browser, github, ssh, inspect_image, ask, resolve, todo, recall, retain, reflect, checkpoint, rewind

Execution backends

• bash-tool-runtime.md, tools/bash.md
• python-repl.md, notebook-tool-runtime.md, tools/eval.md, tools/job.md
• tools/ssh.md
• tools/debug.md, tools/lsp.md, lsp-config.md

Task delegation and subagents

• task-agent-discovery.md, tools/task.md
• collab.md, tools/irc.md

Web I/O and retrieval

• tools/web_search.md, tools/browser.md, tools/github.md

MCP

• mcp-config.md, mcp-runtime-lifecycle.md
• mcp-protocol-transports.md, mcp-server-tool-authoring.md

Memory

• memory.md, mnemosyne-memory-backend.md
• Memory tools: tools/recall.md, tools/retain.md, tools/reflect.md

Discovery, context, and rules

• context-files.md, rulebook-matching-pipeline.md
• advisor-watchdog.md, fs-scan-cache-architecture.md, tree.md

TUI and theming

• tui.md, tui-core-renderer.md, tui-runtime-internals.md
• theme.md

Natives (crates/pi-natives, packages/natives)

• natives-architecture.md, natives-addon-loader-runtime.md, natives-binding-contract.md
• natives-text-search-pipeline.md, natives-shell-pty-process.md, natives-media-system-utils.md
• natives-build-release-debugging.md, natives-rust-task-cancellation.md, porting-to-natives.md

Build, release, and porting

• macos-signing-notarization.md
• porting-from-pi-mono.md

Extending omp

To add…	Start here
A built-in tool	src/tools/index.ts (BUILTIN_TOOLS / HIDDEN_TOOLS) + custom-tools.md
An extension (TS/JS module)	extensions.md, extension-loading.md, skills/authoring-extensions.md
A hook	src/extensibility/hooks/types.ts + hooks.md, skills/authoring-hooks.md
A slash command	slash-command-internals.md
An RPC command	src/modes/rpc/rpc-types.ts + rpc.md
A skill	skills.md
A marketplace plugin	marketplace.md, plugin-manager-installer-plumbing.md, skills/authoring-marketplaces.md, gemini-manifest-extensions.md
A custom MCP tool/server	mcp-server-tool-authoring.md, custom-tools.md
A provider	adding-a-provider.md
Programmatic/SDK use	sdk.md

See also AGENTS.md at the repo root for repo-wide conventions (Bun-over-Node, logging, TUI sanitization, generated files, changelog, releasing).