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 omp:// docs surface), so this file links there instead of
duplicating prose that goes stale.
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 | bun run fix |
Build the dist/omp binary |
bun run build |
Type checks use Bun's built-in checker (bun check --no-script); the explicit
flag bypasses each package's check script. Stable TypeScript is retained only
for publishing declarations and JavaScript, which bun check does not emit.
Use bun run check for the full typecheck/lint gate.
After changing export HTML/CSS/JS, web themes, or the shared tool/trace renderers, run
bun run gen:export-viewer and include src/export/html/viewer.generated.json
with the change. The generated JS lives in ignored export-assets/; CI verifies
the committed metadata (--check, also implied by CI=true) and publishes the
exact asset from the Linux binary build alongside the release binaries. In a
shell that sets CI=true, such as omp's bash tool, use
bun run gen:export-viewer --write to update the metadata.
Exports from a source checkout inline the generated viewer, so bun gen:export-viewer
followed by /export exercises local changes without publishing or a local
server. Packaged releases reference their versioned build.stencil.so viewer.
Both load Markdown and Highlight.js from immutable content-addressed
stencil.so/assets/omp/ files. Keep those files on the site permanently: older
exports reference them directly.
Scope fake timers to the deadline a test exercises, then restore real timers
before real socket listeners are started. Bun's mocked clock can defer
server.listen callbacks, leaving registry publication and teardown waiting.
Tests that call setAgentDir() must snapshot and restore PI_CODING_AGENT_DIR,
OMP_PROFILE, and PI_PROFILE for each test, then call
__resetDirsFromEnvForTests() after restoration. Home-directory discovery fixtures
must clear and restore PI_CODING_AGENT_DIR so inherited overrides cannot bypass
the fixture. Reuse restoreEnvValue() from test/helpers/settings-test-state.ts
to preserve unset values.
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).
Top-level entry modules: cli.ts, main.ts, sdk.ts, index.ts (SDK barrel),
config.ts, system-prompt.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/, irc/, goals/, plan-mode/ |
Subagent delegation, 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/ |
Capability registry + provider discovery modules | extension-loading.md, context-files.md |
advisor/, autolearn/, autoresearch/ |
Advisor/watchdog, managed skills, background research | advisor-watchdog.md, autoresearch.md |
memories/, memory-backend/, mnemopi/, hindsight/ |
Memory subsystems and backends | memory.md, mnemosyne-memory-backend.md |
internal-urls/ |
Router + handlers (agent://, omp://, rule://, …) |
tools/read.md, tools/write.md |
collab/ |
Live session sharing | 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 |
- session.md — storage and entry model
- session-tree-plan.md — branch/tree architecture
- tree.md —
/treesession navigator and leaf switching - 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
- 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, deepseek, gemini, gemma, glm-4.5, harmony, hermes, kimi-k2, minimax, pi-native, qwen3, xml); see also ERRATA-GPT5-HARMONY.md
- keybindings.md
- secrets.md, auth-broker-gateway.md, install-id.md
- system-prompt-customization.md
- 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,grep,glob,bash,eval,wait,lsp,debug,task,web_search,browser,github,ask,todo,recall,retain,reflect,checkpoint,rewind
- bash-tool-runtime.md, tools/bash.md
- python-repl.md, notebook-tool-runtime.md, tools/eval.md, tools/wait.md
- tools/debug.md, tools/lsp.md, lsp-config.md
- memory.md, mnemosyne-memory-backend.md
- Memory tools: tools/recall.md, tools/retain.md, tools/reflect.md
- 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
| 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).