OMP (Oh My Pi) — Tool System¶
Built-in tools¶
Full set (24): ast_edit, ast_grep, bash, browser, debug, edit, eval, find, generate_image, github, inspect_image, irc, job, lsp, read, recipe, report_tool_issue, resolve, search, task, todo, web_search, write.
Enable/disable model¶
debugis off by default; enable in~/.omp/agent/config.yml:- CLI:
--tools read,find,search(restrict),--no-lsp. tools.discoveryModecontrols MCP tool loading (see below).tools.approvalMode/--approval-mode always-ask|write|yolo/--yolo/--auto-approve.- SDK:
createAgentSession({ toolNames: [...] }). - In-session:
/tools. - No per-tool allow/deny YAML except MCP
disabledServers.
Custom tools¶
TypeScript factory (default export). The host injects pi.zod.
| Scope | Path |
|---|---|
| User | ~/.omp/agent/tools/<name>/index.ts |
| Project | .omp/tools/<name>/index.ts |
| Also read | .claude/tools/<name>/index.ts, .codex/tools/<name>/index.ts |
import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
const factory: CustomToolFactory = (pi) => ({
name: "repo_stats",
label: "Repo Stats",
description: "Count tracked files matching a glob",
parameters: pi.zod.object({ glob: pi.zod.string().optional().default("**/*.ts") }),
async execute(_toolCallId, params, onUpdate, _ctx, signal) {
onUpdate?.({ content: [{ type: "text", text: `Listing ${params.glob}` }] });
const result = await pi.exec("git", ["ls-files", params.glob], { signal, cwd: pi.cwd });
if (result.code !== 0) throw new Error(result.stderr || "git ls-files failed");
const files = result.stdout.split("\n").filter(Boolean);
return { content: [{ type: "text", text: `Found ${files.length} files` }], details: { count: files.length } };
},
});
export default factory;
Fields: name (req, no collision with built-ins/other customs), label, description (req), parameters (Zod via pi.zod), execute(toolCallId, params, onUpdate, ctx, signal), optional renderCall/renderResult. Return { content, details, isError } — content is model-visible, details is not. Name collisions are rejected at load; built-ins always win. Inspect with omp -p '/extensions'.
Other authoring surfaces¶
- Skills:
<scope>/skills/<name>/SKILL.md. Frontmattername(opt),description(req),hide(opt). Non-recursive, one skill per dir. Disable via--no-skills,skills.enabled:false,skills.ignoredSkills/includeSkills. - Hooks:
<scope>/hooks/pre/*.ts(gate) +hooks/post/*.ts(rewrite). Events:tool_call({block,reason}),tool_result,context,session_before_compact/branch/switch/tree, lifecycle events,ttsr_triggered.HookAPIvs fullExtensionAPI. - Prompt templates (slash commands):
<scope>/commands/<name>.mdor<name>/index.ts. Also reads~/.claude/commands/,.claude/commands/,.codex/commands/. Placeholders$1/$2/$@/$ARGUMENTS. - Subagents:
<scope>/agents/<name>.md. Frontmattername/description(req),tools,model,spawns,thinkingLevel,output,blocking,autoloadSkills,read-summarize. Resolution: project → user → plugin → bundled. - TTSR rules:
.omp/rules/<rule>.md,~/.omp/agent/rules/<rule>.md. Frontmattercondition(regex) orastCondition,scope. Disable viattsr.disabledRules. - Extension packages / plugins:
package.jsonwithomp.extensions[](legacypi.extensions), or full plugin layout;omp install ./my-extension.
MCP tools¶
Config priority (highest → lowest):
| Priority | Scope | Path |
|---|---|---|
| 1 | Project (omp-managed) | .omp/mcp.json |
| 2 | User (omp-managed) | ~/.omp/agent/mcp.json |
| 3 | Other harnesses (auto-discovered) | .claude/mcp.json, .cursor/mcp.json, .vscode/mcp.json, .gemini/mcp.json, .windsurf/mcp.json, opencode.json |
| 4 | Repo-root standalone | mcp.json or .mcp.json |
Project entries shadow user entries by server key. Disable a server via disabledServers in the user file only.
stdio¶
{
"$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
"mcpServers": {
"fs": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/projects"],
"env": { "LOG_LEVEL": "info" },
"cwd": "${HOME}"
}
}
}
type defaults to stdio when command set. ${VAR} / ${VAR:-default} expand across command, args, env, cwd, url, headers, auth, oauth. A leading ! in a header/env value runs a shell command and uses trimmed stdout.
Streamable HTTP¶
{
"mcpServers": {
"linear": { "type": "http", "url": "https://mcp.linear.app/sse",
"headers": { "Authorization": "Bearer ${LINEAR_TOKEN}" } },
"github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/",
"oauth": { "clientId": "${GH_CLIENT_ID}", "clientSecret": "${GH_CLIENT_SECRET}" } }
}
}
OAuth tokens land in ~/.omp/agent/agent.db (SQLite), not the JSON; complete the flow with /mcp reauth <name>. No separate sse type — type:"http" handles SSE endpoints.
Tool names & discovery¶
Tool names: mcp__<server>_<tool> (lowercased, non-[a-z_]→_, collapsed, redundant <server>_ prefix stripped once).
tools.discoveryMode in config.yml: auto (default — BM25 discovery past 40 tools), mcp-only (all MCP behind discovery), off, all.
Management¶
Slash commands: /mcp add|remove|enable|disable|test|reauth|unauth|reconnect|reload|list|resources|prompts|notifications|smithery-*. Connections are parallel with a 250 ms fast-start gate; failures isolated per server; transports auto-reconnect with backoff.
Config files & locations¶
| Scope | Path | Format |
|---|---|---|
| User settings | ~/.omp/agent/config.yml |
YAML |
| User MCP | ~/.omp/agent/mcp.json |
JSON (disabledServers here) |
| Credentials | ~/.omp/agent/agent.db |
SQLite |
| User custom tools | ~/.omp/agent/tools/<name>/index.ts |
TypeScript |
| User context | ~/.omp/agent/AGENTS.md / RULES.md / SYSTEM.md / APPEND_SYSTEM.md |
Markdown |
| Project MCP | .omp/mcp.json |
JSON (highest priority) |
| Project custom tools | .omp/tools/<name>/index.ts |
TypeScript |
| Project context | <repo>/AGENTS.md, .omp/RULES.md/SYSTEM.md/APPEND_SYSTEM.md |
Markdown |
Overrides: PI_CODING_AGENT_DIR (moves ~/.omp/agent), PI_CONFIG_DIR (renames .omp). Note: no project-level config.yml; project uses the global one.
Gotchas¶
type:"stdio"is default whencommandset; if you settype:"http"but includecommand, http wins and command is ignored — be explicit.- Sanitized MCP tool-name collisions are last-write-wins.
disabledServersis user-file-only; adding it to.omp/mcp.jsonis [INFERENCE] silently ignored.- Built-in tools always win name collisions; custom
bash/readrejected at load. - Malformed
config.ymlsilently falls back to defaults — runomp config listafter edits. - Hook + skill discovery is non-recursive.
SYSTEM.mdremoves built-in tool-usage guidance; preferAPPEND_SYSTEM.md.- OAuth creds in
agent.dbbeat env vars;/logout <provider>to force env precedence. discoveryMode: mcp-onlyhides MCP tools until searched.- Redundant
<server>_prefix stripped once only — plan tool names accordingly. - Plugins run arbitrary TypeScript every turn — install only from trusted sources.
!-prefixed env/header that fails resolves to empty string, not an error.- omp-managed project file is
.omp/mcp.json; repo-rootmcp.json/.mcp.jsonis lowest priority and other-harness files can outrank it.
Sources¶
- https://omp.sh/docs
- https://omp.sh/docs/tools
- https://omp.sh/docs/custom-tools
- https://omp.sh/docs/mcp
- https://omp.sh/docs/mcp-authoring
- https://omp.sh/docs/skills
- https://omp.sh/docs/hooks
- https://omp.sh/docs/settings
- https://omp.sh/docs/plugins
- https://omp.sh/docs/extension-authoring
- https://omp.sh/docs/context-files
- https://omp.sh/docs/prompt-templates
- https://omp.sh/docs/subagent-authoring
- https://omp.sh/docs/ttsr
- https://omp.sh/docs/env
- https://omp.sh/docs/secrets
- https://omp.sh/docs/providers
- https://omp.sh/docs/custom-models
- https://omp.sh/docs/cli
- https://omp.sh/docs/slash
- https://omp.sh/docs/sdk