Skip to content

Latest commit

 

History

History
204 lines (160 loc) · 18.8 KB

DEVELOPMENT.md

File metadata and controls

204 lines (160 loc) · 18.8 KB

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 omp:// 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 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.

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, 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

Subsystem reference

Sessions, persistence, and turn lifecycle

Configuration, models, providers, auth

Tools framework and built-in tools

Execution backends

Task delegation and subagents

Web I/O and retrieval

MCP

Memory

Discovery, context, and rules

TUI and theming

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

Build and release

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).