Best Discord for OpenMP

Session ID: 019e95be-d0d1-7000-9df7-99b17bd27363
Date: 2026-06-05 03:06:11

Associated Memory Note: 019e95be-d0d1-7000-9df7-99b17bd27363

Telemetry Stats

Metric	Value
User Prompt CWD	`/home/dev`
Duration	141.20s
Total Message Events	14
Input / Output Tokens	263187 / 6012
Cache Read / Write	527881 / 0
Estimated Cost	$0.000000

Chat Transcript

👤 User

ultra deepestest holistic ever perpetually looping obsessive research meticulously scanning ALL diverse sources EVERYWHERE until absolute enlightenment is achieved for practical most genius idiot overstanding of = bst discord for omp

🤖 Assistant

Thinking Process

The user is asking about “bst discord for omp” - they want to understand the best Discord setup/integration for OMP (Oh My Pi, the coding harness they’re using). Let me research this thoroughly by looking at all available sources - memory, project files, any OMP documentation, etc.

Let me start by understanding what’s available.

🤖 Toolresult

Remaining items (6):

Scan memory for OMP and Discord refs [in_progress] (Research)
Read OMP harness documentation [pending] (Research)
Search workspace for Discord artifacts [pending] (Research)
Search for BST Discord patterns [pending] (Research)
Examine MCP servers and tools inventory [pending] (Research)
Compile findings into actionable answer [pending] (Synthesis)
Phase 1/2 “Research” — 0/5 tasks complete
Research:
→ Scan memory for OMP and Discord refs
○ Read OMP harness documentation
○ Search workspace for Discord artifacts
○ Search for BST Discord patterns
○ Examine MCP servers and tools inventory
Synthesis:
○ Compile findings into actionable answer

🤖 Assistant

🤖 Toolresult

Documentation

97 files available:

🤖 Toolresult

Multi-project dev workspace at /home/dev on 0rk.de. Key systems: (1) MixBox — Python 3.11+ audio monorepo under /home/dev/audio/MixBox with 5 uv-workspace packages, Ruff linting, Pytest; always use uv sync --all-packages. (2) Self-hosted Hugo+Sveltia CMS Knowledgebase at /home/dev/Knowledgebase — local GitHub API shim (REST+GraphQL) on :8082, Hugo on :55888, HTTPS proxy on :55889; 3 systemd services must all be active. (3) AudioFlux Gradio apps on ports 7860-7863. (4) OMP extensions break under legacy loader — bundle with bun, keep pi-coding-agent external. (5) Langfuse at http://95.111.224.175:19030 — NOT in Langflow .env. (6) AGENTS.md at /home/dev must cover ALL workspace projects, not just MixBox. User dv has separate hugo-sveltia-lab at /home/dv/.

🤖 Toolresult

Dev Server Memory

Environment

Primary workspace: /home/dev (multi-project, NOT a single repo)
Secondary user: dv (home at /home/dv, has hugo-sveltia-lab)
Domain: 0rk.de
OS: Linux with systemd

Workspace Projects & Port Map

Port	Project	Location
7860	AudioFlux Main (Gradio)	/home/dev/audio/[[projects/audioflux
7861	AudioFlux Unified Dashboard	/home/dev/audio/[[projects/audioflux
7863	AudioFlux MIR Playground	/home/dev/audio/[[projects/audioflux
8082	Local GitHub API shim (localhost only)	/home/dev/[[projects/knowledgebase
55888	Hugo [[projects/knowledgebase	Knowledgebase]] dev server
55889	HTTPS proxy (TLS termination)	/home/dev/[[projects/knowledgebase
56465	openDAW Studio	—
56467	openDAW yjs collab	—

Other projects: GOMA/GIMA, Langflow (/home/dev/py/flow), GroqGradio, OpenAI Chat Lab.

MixBox Monorepo

Location: /home/dev/audio/MixBox
Type: astral-uv Python 3.11+ workspace monorepo
Linter/Formatter: Ruff (100-char line limit)
Test framework: Pytest with markers (unit, smoke, integration, rotation)
CRITICAL: always run uv sync --all-packages not plain uv sync
5 packages under packages/:
1. audio-core (audio_core): shared foundation — audio loading, format conversion, feature extraction
2. dj-engine ([[projects/mixbox|MixBox]]): primary orchestrator — mixing engine, beatgrid, UIs, review server
3. analyzer (hitscan): deep MIR analysis
4. video-gen (hitvid): audio-reactive video generation
5. emotion (valaro): valence-arousal emotion detection (standalone tensorflow)
Service: mixbox-review.service, nightly validation via mixbox-validate.timer at 03:00
213 tests passing, Phase 6a-6d shipped, 6e (LR4 zero-phase crossover) not started
Strategic plans: /home/dev/.windsurf/plans/mixbox-strategic-master-2026-04-30.md
Custodian cadence: monthly

Self-Hosted Knowledgebase (0rk.de)

Location: /home/dev/Knowledgebase
Fully self-hosted, zero external dependencies (no GitHub, no CDN)

Stack

Hugo static site generator on Port 55888 (Hugo Knowledgebase) (all interfaces)
local-github-api.mjs (Node) on Port 8082 (Fake GitHub API) (localhost only) — fake GitHub REST+GraphQL API
https-proxy.mjs (Node) on Port 55889 (Hugo KB HTTPS Proxy) (0.0.0.0) — TLS termination
Sveltia CMS v0.165.0 self-hosted at /static/admin/sveltia-cms.js (1.9MB)
TLS certs at /home/dev/certs/

HTTPS Proxy Routing

/api/v3/* → localhost:8082 (REST, strips /api/v3 prefix)
/graphql → localhost:8082 (GraphQL, routed separately)
/* → localhost:55888 (Hugo site + admin)

Local GitHub API Shim (local-github-api.mjs)

REST endpoints: /user, /repos/:owner/:repo, branches, git/refs, git/trees, contents/:path (GET/PUT/DELETE), git/blobs (POST create, GET serve), git/trees (POST), git/commits (POST), git/refs PATCH, collaborators/:user→204, dispatches→204.

GraphQL: defaultBranchRef, fetchLastCommit, file contents batch, createCommitOnBranch mutation, fetchFileCommits.

Key implementation: SHA→path index in memory for blob serving, sha1() for content-addressable blobs, fakeSha() for synthetic commits/trees, real git add/commit via child_process after writes.

CMS Config

/static/admin/config.yml: backend.name=github, repo=local/Knowledgebase, base_url=https://0rk.de:55889
OAuth bypass: /admin/index.html inline script auto-posts token via postMessage

Systemd Services

hugo-knowledgebase.service
local-github-api.service
hugo-kb-https-proxy.service (depends on local-github-api)
All 3 must be active for CMS to work

Pitfalls

Sveltia CMS requires GraphQL (not just REST) — does NOT support decap-server/local backend
Blob serving by SHA needed for media display
/collaborators/:user must return 204 (not 404) or CMS shows permission error
HTTPS proxy must route /graphql separately from /api/v3/*
Content-Type for blob responses: application/json with base64

Hugo Book Theme

BookSection param controls sidebar navigation
BookSection = ”*” shows all sections; default is “docs”
Frontmatter titles must be unique/descriptive to avoid nav confusion

OMP Extension System

OMP is a compiled ELF binary with config at ~/.omp/agent/config.yml
Extensions array in config points to extension directories
Legacy extension loader mirrors to /tmp/omp-legacy-pi-file/entry-/ at startup
This breaks CommonJS require() chains (relative requires fail from temp dir)
OMP logs: ~/.omp/logs/omp.YYYY-MM-DD.log

pi-langfuse Extension

Location: /home/dev/.omp/plugins/node_modules/pi-langfuse/
Fix: bundle with bun build ./index.ts --outdir ./dist --target node --external @earendil-works/pi-coding-agent
@earendil-works/pi-coding-agent MUST be external (provided by OMP runtime)
package.json main → dist/index.js
state.isTracingDisabled must be reset to false at top of startAgentRun()
Debug technique: write to /tmp/pi-langfuse-debug.log from extension init

Langfuse

Server: http://95.111.224.175:19030
Traces endpoint: /api/public/traces?limit=5&orderBy=timestamp.desc
Auth: Basic auth with pk:sk
Langfuse vars do NOT belong in Langflow .env — only in pi-langfuse extension config

Langflow

Location: /home/dev/py/flow
Service: Langflow.service
DB: sqlite at /home/dev/py/flow/Langflow.db

Generated Docs

/home/dev/docs/WORKSPACE_CHEAT_SHEET.md — 147-line quick-start (port map, paths, commands, conventions)
/home/dev/AGENTS.md — should cover full workspace, not just MixBox

Critical Lessons

When asked to generate AGENTS.md for /home/dev, scope to ALL projects, not just MixBox
Launch parallel explore agents covering different project areas
Always check current state of services/config before making assumptions

🤖 Assistant

🤖 Toolresult

Remaining items (5):

Read OMP harness documentation [in_progress] (Research)
Search workspace for Discord artifacts [pending] (Research)
Search for BST Discord patterns [pending] (Research)
Examine MCP servers and tools inventory [pending] (Research)
Compile findings into actionable answer [pending] (Synthesis)
Phase 1/2 “Research” — 1/5 tasks complete
Research:
✓ Scan memory for OMP and Discord refs
→ Read OMP harness documentation
○ Search workspace for Discord artifacts
○ Search for BST Discord patterns
○ Examine MCP servers and tools inventory
Synthesis:
○ Compile findings into actionable answer

🤖 Assistant

Let me deep-dive into OMP docs that could relate to Discord, extensions, custom tools, hooks, and the SDK — plus search the workspace and web for “bst discord” context.

🤖 Toolresult

{“query”:“discord bot notification webhook”,“activated_tools”:[],“match_count”:0,“total_tools”:24}

🤖 Toolresult

Extensions

Primary guide for authoring runtime extensions in packages/coding-agent.

This document covers the current extension runtime in:

src/extensibility/extensions/types.ts
src/extensibility/extensions/runner.ts
src/extensibility/extensions/wrapper.ts
src/extensibility/extensions/index.ts
src/modes/controllers/extension-ui-controller.ts

For discovery paths and filesystem loading rules, see extension-loading.md.

What an extension is

An extension is a TS/JS module exporting a default factory:

import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
export default function myExtension(pi: ExtensionAPI) {
  // register handlers/tools/commands/renderers
}

Extensions can combine all of the following in one module:

event handlers (pi.on(...))
LLM-callable tools (pi.registerTool(...))
slash commands (pi.registerCommand(...))
keyboard shortcuts and flags
custom message rendering
session/message injection APIs (sendMessage, sendUserMessage, appendEntry)

Runtime model

Extensions are imported and their factory functions run.
During that load phase, registration methods are valid; runtime action methods are not yet initialized.
ExtensionRunner.initialize(...) wires live actions/contexts for the active mode.
Session/agent/tool lifecycle events are emitted to handlers.
Every tool execution is wrapped with extension interception (tool_call / tool_result).

Extension lifecycle (simplified)
 
load paths
   │
   ▼
import module + run factory (registration only)
   │
   ▼
ExtensionRunner.initialize(mode/session/tool registry)
   │
   ├─ emit session/agent events to handlers
   ├─ wrap tool execution (tool_call/tool_result)
   └─ expose runtime actions (sendMessage, setActiveTools, ...)

Important constraint from loader.ts:

calling action methods like pi.sendMessage() during extension load throws ExtensionRuntimeNotInitializedError
register first; perform runtime behavior from events/commands/tools

Quick start

import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 
export default function (pi: ExtensionAPI) {
  const { z } = pi.zod;
 
  pi.setLabel("Safety + Utilities");
 
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify(`Extension loaded in ${ctx.cwd}`, "info");
  });
 
  pi.on("tool_call", async (event) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      return { block: true, reason: "Blocked by extension policy" };
    }
  });
 
  pi.registerTool({
    name: "hello_extension",
    label: "Hello Extension",
    description: "Return a greeting",
    parameters: z.object({ name: z.string() }),
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}` }],
        details: { greeted: params.name },
      };
    },
  });
 
  pi.registerCommand("hello-ext", {
    description: "Show queue state",
    handler: async (_args, ctx) => {
      ctx.ui.notify(`pending=${ctx.hasPendingMessages()}`, "info");
    },
  });
}

Extension API surfaces

1) Registration and actions (`ExtensionAPI`)

Core methods:

on(event, handler)
registerTool, registerCommand, registerShortcut, registerFlag
registerMessageRenderer, registerAssistantThinkingRenderer
setLabel, getFlag
sendMessage, sendUserMessage, appendEntry, exec
getActiveTools, getAllTools, setActiveTools
getCommands
getSessionName, setSessionName
setModel, getThinkingLevel, setThinkingLevel
registerProvider
events (shared event bus)

In interactive mode, input handlers run before the built-in first-message auto-title check. Extensions that call await pi.setSessionName(...) from input can set the persisted session name and prevent the default auto-generated title from running for that session.

Also exposed:

pi.logger
pi.typebox (zod-backed compatibility shim for legacy TypeBox-style schemas)
pi.zod (injected zod/v4 module — canonical for tool parameter schemas)
pi.pi (package exports)

Message delivery semantics

pi.sendMessage(message, options) supports:

deliverAs: "steer" (default) — interrupts current run
deliverAs: "followUp" — queued to run after current run
deliverAs: "nextTurn" — stored and injected on the next user prompt
triggerTurn: true — starts a turn when idle (nextTurn ignores this)

pi.sendUserMessage(content, { deliverAs }) always goes through prompt flow; while streaming it queues as steer/follow-up.

2) Handler context (`ExtensionContext`)

Handlers and tool execute receive ctx with:

ui
hasUI
cwd
sessionManager (read-only)
modelRegistry, model
getContextUsage()
compact(...)
isIdle(), hasPendingMessages(), abort()
shutdown()
getSystemPrompt()

3) Command context (`ExtensionCommandContext`)

Command handlers additionally get:

waitForIdle()
newSession(...)
switchSession(...)
branch(entryId)
navigateTree(targetId, { summarize })
reload()

Use command context for session-control flows; these methods are intentionally separated from general event handlers.

Event surface (current names and behavior)

Canonical event unions and payload types are in types.ts.

Session lifecycle

session_start
session_before_switch / session_switch
session_before_branch / session_branch
session_before_compact / session.compacting / session_compact
session_before_tree / session_tree
session_shutdown

Cancelable pre-events:

session_before_switch → { cancel?: boolean }
session_before_branch → { cancel?: boolean; skipConversationRestore?: boolean }
session_before_compact → { cancel?: boolean; compaction?: CompactionResult }
session_before_tree → { cancel?: boolean; summary?: { summary: string; details?: unknown } }

Prompt and turn lifecycle

input
before_agent_start
before_provider_request (may replace provider request payload)
after_provider_response
context
agent_start / agent_end
turn_start / turn_end
message_start / message_update / message_end

Tool lifecycle

tool_call (pre-exec, may block)
tool_result (post-exec, may patch content/details/isError)
tool_execution_start / tool_execution_update / tool_execution_end (observability)

tool_result is middleware-style: handlers run in extension order and each sees prior modifications.

Reliability/runtime signals

auto_compaction_start / auto_compaction_end
auto_retry_start / auto_retry_end
ttsr_triggered
todo_reminder
goal_updated
credential_disabled

User command interception

user_bash (override with { result })
user_python (override with { result })

`resources_discover`

resources_discover exists in extension types and ExtensionRunner.
Current runtime note: ExtensionRunner.emitResourcesDiscover(...) is implemented, but there are no AgentSession callsites invoking it in the current codebase.

Tool authoring details

registerTool uses ToolDefinition from types.ts.

Current execute signature:

execute(
	toolCallId,
	params,
	signal,
	onUpdate,
	ctx,
): Promise<AgentToolResult>

Template:

const { z } = pi.zod;
 
pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "...",
  parameters: z.object({}),
  hidden: false,
  defaultInactive: false,
  deferrable: false,
  async execute(_id, _params, signal, onUpdate, ctx) {
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });
    return { content: [{ type: "text", text: "Done" }], details: {} };
  },
  onSession(event, ctx) {
    // reason: start|switch|branch|tree|shutdown
  },
  renderCall(args, options, theme) {
    // optional TUI render
  },
  renderResult(result, options, theme, args) {
    // optional TUI render
  },
});

tool_call/tool_result intercept all tools once the registry is wrapped in sdk.ts, including built-ins and extension/custom tools. ToolDefinition also supports optional hidden, defaultInactive, deferrable, mcpServerName, mcpToolName, renderCall, and renderResult fields.

UI integration points

ctx.ui implements the ExtensionUIContext interface. Support differs by mode.

Interactive mode (`extension-ui-controller.ts`)

Supported:

dialogs: select, confirm, input, editor
input editing: setEditorText, getEditorText, pasteToEditor, editor
terminal title and working message (setTitle, setWorkingMessage)
notifications/status/editor text/terminal input/custom overlays
theme listing/loading by name (setTheme supports string names)
tools expanded toggle

Current no-op methods in this controller:

setFooter
setHeader
setEditorComponent

Also note: setWidget currently routes to status-line text via setHookWidget(...).

RPC mode (`rpc-mode.ts`)

ctx.ui is backed by RPC extension_ui_request events:

dialog methods (select, confirm, input, editor) round-trip to client responses
fire-and-forget methods emit requests (notify, setStatus, setWidget for string arrays, setTitle, setEditorText)

Unsupported/no-op in RPC implementation:

onTerminalInput
custom
setFooter, setHeader, setEditorComponent
setWorkingMessage
theme switching/loading (setTheme returns failure)
tool expansion controls are inert

Print/headless/subagent paths

When no UI context is supplied to runner init, ctx.hasUI is false and methods are no-op/default-returning.

Background interactive mode

Background mode installs a non-interactive UI context object. In current implementation, ctx.hasUI may still be true while interactive dialogs return defaults/no-op behavior.

Session and state patterns

For durable extension state:

Persist with pi.appendEntry(customType, data).
Rebuild state from ctx.sessionManager.getBranch() on session_start, session_branch, session_tree.
Keep tool result details structured when state should be visible/reconstructible from tool result history.

Example reconstruction pattern:

pi.on("session_start", async (_event, ctx) => {
  let latest;
  for (const entry of ctx.sessionManager.getBranch()) {
    if (entry.type === "custom" && entry.customType === "my-state") {
      latest = entry.data;
    }
  }
  // restore from latest
});

Rendering extension points

Custom message renderer

pi.registerMessageRenderer("my-type", (message, { expanded }, theme) => {
  // return pi-tui Component
});

Used by interactive rendering when custom messages are displayed.

Assistant thinking renderer

import { Container, Text } from "@oh-my-pi/pi-tui";
 
pi.registerAssistantThinkingRenderer((context, theme) => {
  const container = new Container();
  container.addChild(new Text(theme.fg("dim", `thinking chars: ${context.text.length}`), 1, 0));
  return container;
});

Used by interactive rendering to add display-only supplemental UI below each visible assistant thinking block. The renderer receives the already-visible thinking text, content/thinking indexes, theme, and a requestRender() callback for async renderers. All registered renderers that return a component are appended in registration order. Renderers must not mutate messages; the original thinking block remains the provider/session source of truth.

Tool call/result renderer

Provide renderCall / renderResult on registerTool definitions for custom tool visualization in TUI.

Constraints and pitfalls

Runtime actions are unavailable during extension load.
tool_call errors block execution (fail-closed).
Command name conflicts with built-ins are skipped with diagnostics.
Reserved shortcuts are ignored (ctrl+c, ctrl+d, ctrl+z, ctrl+k, ctrl+p, ctrl+l, ctrl+o, ctrl+t, ctrl+g, shift+tab, shift+ctrl+p, alt+enter, escape, enter).
Treat ctx.reload() as terminal for the current command handler frame.

Extensions vs hooks vs custom-tools

Use the right surface:

Extensions (src/extensibility/extensions/*): unified system (events + tools + commands + renderers + provider registration).
Hooks (src/extensibility/hooks/*): separate legacy event API.
Custom-tools (src/extensibility/custom-tools/*): tool-focused modules; when loaded alongside extensions they are adapted and still pass through extension interception wrappers.

If you need one package that owns policy, tools, command UX, and rendering together, use extensions.

🤖 Toolresult

Hooks

This document describes the current hook subsystem code in src/extensibility/hooks/*.

Current status in runtime

The hook package (src/extensibility/hooks/) is still exported and usable as an API surface, but the default CLI runtime now initializes the extension runner path. In current startup flow:

--hook is treated as an alias for --extension (CLI paths are merged into additionalExtensionPaths)
tools are wrapped by ExtensionToolWrapper, not HookToolWrapper
context transforms and lifecycle emissions go through ExtensionRunner

So this file documents the hook subsystem implementation itself (types/loader/runner/wrapper), including legacy behavior and constraints.

Key files

src/extensibility/hooks/types.ts — hook context, event types, and result contracts
src/extensibility/hooks/loader.ts — module loading and hook discovery bridge
src/extensibility/hooks/runner.ts — event dispatch, command lookup, error signaling
src/extensibility/hooks/tool-wrapper.ts — pre/post tool interception wrapper
src/extensibility/hooks/index.ts — exports/re-exports

What a hook module is

A hook module must default-export a factory:

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
 
export default function hook(pi: HookAPI): void {
  pi.on("tool_call", async (event, ctx) => {
    if (
      event.toolName === "bash" &&
      String(event.input.command ?? "").includes("rm -rf")
    ) {
      return { block: true, reason: "blocked by policy" };
    }
  });
}

The factory can:

register event handlers with pi.on(...)
send persistent custom messages with pi.sendMessage(...)
persist non-LLM state with pi.appendEntry(...)
register slash commands via pi.registerCommand(...)
register custom message renderers via pi.registerMessageRenderer(...)
run shell commands via pi.exec(...)
author schemas/helpers with injected pi.zod, pi.typebox, and package exports via pi.pi

Discovery and loading

discoverAndLoadHooks(configuredPaths, cwd) does:

Load discovered hooks from capability registry (loadCapability("hooks"))
Append explicitly configured paths (deduped by absolute path)
Call loadHooks(allPaths, cwd)

loadHooks then imports each path and expects a default function.

Path resolution

loader.ts resolves hook paths as:

absolute path: used as-is
~ path: expanded
relative path: resolved against cwd

Important legacy mismatch

Discovery providers for hookCapability still model pre/post shell-style hook files (for example .claude/hooks/pre/*, .omp/.../hooks/pre/*).

The hook loader here uses dynamic module import and requires a default JS/TS hook factory. If a discovered hook path is not importable as a module, load fails and is reported in LoadHooksResult.errors.

Event surfaces

Hook events are strongly typed in types.ts.

Session events

session_start
session_before_switch → can return { cancel?: boolean }
session_switch
session_before_branch → can return { cancel?: boolean; skipConversationRestore?: boolean }
session_branch
session_before_compact → can return { cancel?: boolean; compaction?: CompactionResult }
session.compacting → can return { context?: string[]; prompt?: string; preserveData?: Record<string, unknown> }
session_compact
session_before_tree → can return { cancel?: boolean; summary?: { summary: string; details?: unknown } }
session_tree
session_shutdown

Agent/context events

context → can return { messages?: Message[] }
before_agent_start → can return { message?: { customType; content; display; details } }
agent_start
agent_end
turn_start
turn_end
auto_compaction_start
auto_compaction_end
auto_retry_start
auto_retry_end
ttsr_triggered
todo_reminder

Tool events (pre/post model)

tool_call (pre-execution) → can return { block?: boolean; reason?: string }
tool_result (post-execution) → can return { content?; details?; isError? }

This is the hook subsystem’s core pre/post interception model.

Hook tool interception flow
 
tool_call handlers
   │
   ├─ any { block: true }? ── yes ──> throw (tool blocked)
   │
   └─ no
      │
      ▼
   execute underlying tool
      │
      ├─ success ──> tool_result handlers can override { content, details }
      │
      └─ error   ──> emit tool_result(isError=true) then rethrow original error

Execution model and mutation semantics

1) Pre-execution: `tool_call`

HookToolWrapper.execute() emits tool_call before tool execution.

if any handler returns { block: true }, execution stops
if handler throws, wrapper fails closed and blocks execution
returned reason becomes the thrown error text

2) Tool execution

Underlying tool executes normally if not blocked.

3) Post-execution: `tool_result`

After success, wrapper emits tool_result with:

toolName, toolCallId, input
content
details
isError: false

If handler returns overrides:

content can replace result content
details can replace result details

On tool failure, wrapper emits tool_result with isError: true and error text content, then rethrows original error.

What hooks can mutate

LLM context for a single call via context (messages replacement chain)
tool output content/details on successful tool calls (tool_result path)
pre-agent injected message via before_agent_start
cancellation/custom compaction/tree behavior via session_before_* and session.compacting

What hooks cannot mutate in this implementation

raw tool input parameters in-place (only block/allow on tool_call)
execution continuation after thrown tool errors (error path rethrows)
final success/error status in wrapper behavior (returned isError is typed but not applied by HookToolWrapper)

Ordering and conflict behavior

Discovery-level ordering

Capability providers are priority-sorted (higher first). Dedupe is by capability key, first wins.

For hooks, capability key is ${type}:${tool}:${name}. Shadowed duplicates from lower-priority providers are marked and excluded from effective discovered list.

Load order

discoverAndLoadHooks builds a flat allPaths list, deduped by resolved absolute path, then loadHooks iterates in that order.
File order within each discovered directory depends on readdir output; the hook loader does not perform an additional sort.

Runtime handler order

Inside HookRunner, order is deterministic by registration sequence:

hooks array order
handler registration order per hook/event

Conflict behavior by event type:

tool_call: last returned result wins unless a handler blocks; first block short-circuits
tool_result: last returned override wins (no short-circuit)
context: chained; each handler receives prior handler’s message output
before_agent_start: first returned message is kept; later messages ignored
session_before_*: latest returned result is tracked; cancel: true short-circuits immediately
session.compacting: latest returned result wins

Command/renderer conflicts:

getCommand(name) returns first match across hooks (first loaded wins)
getMessageRenderer(customType) returns first match
getRegisteredCommands() returns all commands (no dedupe)

UI interactions (`HookContext.ui`)

HookUIContext includes:

select, confirm, input, editor
notify
setStatus
custom
setEditorText, getEditorText
theme getter

ctx includes hasUI, cwd, sessionManager, modelRegistry, current model, isIdle(), abort(), and hasQueuedMessages().

When running with no UI, the default no-op context behavior is:

select/input/editor return undefined
confirm returns false
notify, setStatus, setEditorText are no-ops
getEditorText returns ""

Status line behavior

Hook status text set via ctx.ui.setStatus(key, text) is:

stored per key
sorted by key name
sanitized (\r, \n, \t → spaces; repeated spaces collapsed)
joined and width-truncated for display

Error propagation and fallback

Load-time

invalid module or missing default export → captured in LoadHooksResult.errors
loading continues for other hooks

Event-time

HookRunner.emit(...) catches handler errors for most events and emits HookError to listeners (hookPath, event, error), then continues.

emitToolCall(...) is stricter: handler errors are not swallowed there; they propagate to caller. In HookToolWrapper, this blocks the tool call (fail-safe).

Realistic API examples

Block unsafe bash commands

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
 
export default function (pi: HookAPI): void {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName !== "bash") return;
    const cmd = String(event.input.command ?? "");
    if (!cmd.includes("rm -rf")) return;
 
    if (!ctx.hasUI) return { block: true, reason: "rm -rf blocked (no UI)" };
    const ok = await ctx.ui.confirm("Dangerous command", `Allow: ${cmd}`);
    if (!ok) return { block: true, reason: "user denied command" };
  });
}

Redact tool output on post-execution

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
 
export default function (pi: HookAPI): void {
  pi.on("tool_result", async (event) => {
    if (event.toolName !== "read" || event.isError) return;
 
    const redacted = event.content.map((chunk) => {
      if (chunk.type !== "text") return chunk;
      return {
        ...chunk,
        text: chunk.text.replaceAll(/API_KEY=\S+/g, "API_KEY=[REDACTED]"),
      };
    });
 
    return { content: redacted };
  });
}

Modify model context per LLM call

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
 
export default function (pi: HookAPI): void {
  pi.on("context", async (event) => {
    const filtered = event.messages.filter(
      (msg) => !(msg.role === "custom" && msg.customType === "debug-only"),
    );
    return { messages: filtered };
  });
}

Register slash command with command-safe context methods

import type { HookAPI } from "@oh-my-pi/pi-coding-agent/extensibility/hooks";
 
export default function (pi: HookAPI): void {
  pi.registerCommand("handoff", {
    description: "Create a new session with setup message",
    handler: async (_args, ctx) => {
      await ctx.waitForIdle();
      await ctx.newSession({
        parentSession: ctx.sessionManager.getSessionFile(),
        setup: async (sm) => {
          sm.appendMessage({
            role: "user",
            content: [
              { type: "text", text: "Continue from prior session summary." },
            ],
            timestamp: Date.now(),
          });
        },
      });
    },
  });
}

Export surface

src/extensibility/hooks/index.ts and the package subpath @oh-my-pi/pi-coding-agent/extensibility/hooks export:

loading APIs (discoverAndLoadHooks, loadHooks)
runner and wrapper (HookRunner, HookToolWrapper)
all hook types
execCommand re-export

The package root (@oh-my-pi/pi-coding-agent) does not re-export HookAPI; import legacy hook types from the hooks subpath.

🤖 Toolresult

SDK

The SDK is the in-process integration surface for @oh-my-pi/pi-coding-agent.
Use it when you want direct access to agent state, event streaming, tool wiring, and session control from your own Bun/Node process.

If you need cross-language/process isolation, use RPC mode instead.

Installation

bun add @oh-my-pi/pi-coding-agent

Entry points

@oh-my-pi/pi-coding-agent exports the SDK APIs from the package root (and also via @oh-my-pi/pi-coding-agent/sdk).

Core exports for embedders:

createAgentSession
SessionManager
Settings
AuthStorage
ModelRegistry
discoverAuthStorage
Discovery helpers (discoverExtensions, discoverSkills, discoverContextFiles, discoverPromptTemplates, discoverSlashCommands, discoverCustomTSCommands, discoverMCPServers)
Tool factory surface (createTools, BUILTIN_TOOLS, tool classes)

Quick start (auto-discovery defaults)

import { createAgentSession } from "@oh-my-pi/pi-coding-agent";
 
const { session, modelFallbackMessage } = await createAgentSession();
 
if (modelFallbackMessage) {
  process.stderr.write(`${modelFallbackMessage}\n`);
}
 
const unsubscribe = session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});
 
await session.prompt("Summarize this repository in 3 bullets.");
unsubscribe();
await session.dispose();

What `createAgentSession()` discovers by default

createAgentSession() follows “provide to override, omit to discover”.

If omitted, it resolves:

cwd: getProjectDir()
agentDir: ~/.omp/agent (via getAgentDir())
authStorage: discoverAuthStorage(agentDir)
modelRegistry: new ModelRegistry(authStorage) + background refreshInBackground() when the registry is not provided
settings: await Settings.init({ cwd, agentDir })
sessionManager: SessionManager.create(cwd) (file-backed)
skills/context files/prompt templates/slash commands/extensions/custom TS commands
built-in tools via createTools(...)
MCP tools (enabled by default; Exa MCP servers are folded into native Exa integration, and browser automation MCP servers are filtered when the built-in browser tool is enabled)
LSP integration (enabled by default)
eventBus: new EventBus() unless supplied

Required vs optional inputs

Typically you must provide only what you want to control:

Must provide: nothing for a minimal session
Usually provide explicitly in embedders:
- sessionManager (if you need in-memory or custom location)
- authStorage + modelRegistry (if you own credential/model lifecycle)
- model or modelPattern (if deterministic model selection matters)
- settings (if you need isolated/test config)

Session manager behavior (persistent vs in-memory)

AgentSession always uses a SessionManager; behavior depends on which factory you use.

File-backed (default)

import { createAgentSession, SessionManager } from "@oh-my-pi/pi-coding-agent";
 
const { session } = await createAgentSession({
  sessionManager: SessionManager.create(process.cwd()),
});
 
console.log(session.sessionFile); // absolute .jsonl path

Persists conversation/messages/state deltas to session files.
Supports resume/open/list/fork workflows.
session.sessionFile is defined.

In-memory

import { createAgentSession, SessionManager } from "@oh-my-pi/pi-coding-agent";
 
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
});
 
console.log(session.sessionFile); // undefined

No filesystem persistence.
Useful for tests, ephemeral workers, request-scoped agents.
Session methods still work, but persistence-specific behaviors (file resume/fork paths) are naturally limited.

Resume/open/list helpers

import { SessionManager } from "@oh-my-pi/pi-coding-agent";
 
const recent = await SessionManager.continueRecent(process.cwd());
const listed = await SessionManager.list(process.cwd());
const opened = listed[0] ? await SessionManager.open(listed[0].path) : null;

Model and auth wiring

createAgentSession() uses ModelRegistry + AuthStorage for model selection and API key resolution.

Explicit wiring

import {
  createAgentSession,
  discoverAuthStorage,
  ModelRegistry,
  SessionManager,
} from "@oh-my-pi/pi-coding-agent";
 
const authStorage = await discoverAuthStorage();
const modelRegistry = new ModelRegistry(authStorage);
await modelRegistry.refresh();
 
const available = modelRegistry.getAvailable();
if (available.length === 0)
  throw new Error("No authenticated models available");
 
const { session } = await createAgentSession({
  authStorage,
  modelRegistry,
  model: available[0],
  thinkingLevel: "medium",
  sessionManager: SessionManager.inMemory(),
});

Selection order when `model` is omitted

When no explicit model/modelPattern is provided:

restore model from existing session (if restorable + key available)
settings default model role (default)
first available model with valid auth

If restore fails, modelFallbackMessage explains fallback.

Auth priority

AuthStorage.getApiKey(...) resolves in this order:

runtime override (setRuntimeApiKey, used by CLI --api-key)
config-sourced API key override (models.yml provider apiKey)
stored API-key credential in agent.db / broker-backed storage
stored OAuth credential, including refresh when needed
provider environment variables
custom-provider resolver fallback

Event subscription model

Subscribe with session.subscribe(listener); it returns an unsubscribe function.

const unsubscribe = session.subscribe((event) => {
  switch (event.type) {
    case "agent_start":
    case "turn_start":
    case "tool_execution_start":
      break;
    case "message_update":
      if (event.assistantMessageEvent.type === "text_delta") {
        process.stdout.write(event.assistantMessageEvent.delta);
      }
      break;
  }
});

AgentSessionEvent includes core AgentEvent plus session-level events:

auto_compaction_start / auto_compaction_end
auto_retry_start / auto_retry_end
retry_fallback_applied / retry_fallback_succeeded
ttsr_triggered
todo_reminder / todo_auto_clear
irc_message

Prompt lifecycle

session.prompt(text, options?) is the primary entry point.

Behavior:

optional command/template expansion (/ commands, custom commands, file slash commands, prompt templates)
if currently streaming:
- requires streamingBehavior: "steer" | "followUp"
- queues instead of throwing work away
if idle:
- validates model + API key
- appends user message
- starts agent turn

Related APIs:

sendUserMessage(content, { deliverAs? })
steer(text, images?)
followUp(text, images?)
sendCustomMessage({ customType, content, ... }, { deliverAs?, triggerTurn? })
abort()

Tools and extension integration

Built-ins and filtering

Built-ins come from createTools(...) and BUILTIN_TOOLS.
toolNames acts as an allowlist for built-ins.
customTools and extension-registered tools are still included.
Hidden tools (for example yield) are opt-in unless required by options.

const { session } = await createAgentSession({
  toolNames: ["read", "search", "find", "write"],
  requireYieldTool: true,
});

Extensions

extensions: inline ExtensionFactory[]
additionalExtensionPaths: load extra extension files
disableExtensionDiscovery: disable automatic extension scanning
preloadedExtensions: reuse already loaded extension set

Runtime tool set changes

AgentSession supports runtime activation updates:

getActiveToolNames()
getAllToolNames()
setActiveToolsByName(names)
refreshMCPTools(mcpTools)

System prompt is rebuilt to reflect active tool changes.

Discovery helpers

Use these when you want partial control without recreating internal discovery logic:

discoverAuthStorage(agentDir?)
discoverExtensions(cwd?)
discoverSkills(cwd?, _agentDir?, settings?)
discoverContextFiles(cwd?, _agentDir?)
discoverPromptTemplates(cwd?, agentDir?)
discoverSlashCommands(cwd?)
discoverCustomTSCommands(cwd?, agentDir?)
discoverMCPServers(cwd?)
buildSystemPrompt(options?)

Subagent-oriented options

For SDK consumers building orchestrators (similar to task executor flow):

outputSchema: passes structured output expectation into tool context
requireYieldTool: forces yield tool inclusion
taskDepth: recursion-depth context for nested task sessions
parentTaskPrefix: artifact naming prefix for nested task outputs

These are optional for normal single-agent embedding.

`createAgentSession()` return value

type CreateAgentSessionResult = {
  session: AgentSession;
  extensionsResult: LoadExtensionsResult;
  setToolUIContext: (uiContext: ExtensionUIContext, hasUI: boolean) => void;
  mcpManager?: MCPManager;
  modelFallbackMessage?: string;
  lspServers?: Array<{
    name: string;
    status: "ready" | "error";
    fileTypes: string[];
    error?: string;
  }>;
  eventBus: EventBus;
};

Use setToolUIContext(...) only if your embedder provides UI capabilities that tools/extensions should call into.

Startup performance

createAgentSession() runs two background optimizations to overlap I/O with the rest of session setup:

Model-host preconnect. As soon as the model is resolved, the SDK fires a best-effort fetch.preconnect(model.baseUrl) so DNS + TCP + TLS + HTTP/2 to the provider’s host happens in parallel with extension/skill load, tool registry build, and system-prompt assembly. The first real fetch(...) then reuses the warm connection, saving 100–300 ms on transcontinental hops (e.g. residential IP → api.anthropic.com). Implementation lives in preconnectModelHost() in packages/coding-agent/src/sdk.ts. If fetch.preconnect is unavailable (non-Bun runtime) or the call throws, the optimization is silently skipped — never a hard dependency. Applies to every mode (interactive, print, RPC, ACP).
Conditional LSP warmup. Startup LSP servers (those returned by discoverStartupLspServers(cwd)) are only warmed when all of these hold:
- enableLsp !== false on the session options, and
- options.hasUI === true (interactive TUI), and
- the lsp.diagnosticsOnWrite setting is enabled.
Print / script / RPC / ACP invocations (hasUI=false) skip the warmup entirely: they don’t render the warmup status indicator and typically finish before the language servers would stabilize, so warming them just spends CPU parsing big initialize responses concurrently with the LLM stream consumer and jitters perceived latency. Tools that actually need an LSP server still spin one up on demand through getOrCreateClient() — only the startup warmup is skipped. The returned lspServers field in CreateAgentSessionResult is therefore undefined (not an empty array) whenever the warmup branch was bypassed.

Minimal controlled embed example

import {
  createAgentSession,
  discoverAuthStorage,
  ModelRegistry,
  SessionManager,
  Settings,
} from "@oh-my-pi/pi-coding-agent";
 
const authStorage = await discoverAuthStorage();
const modelRegistry = new ModelRegistry(authStorage);
await modelRegistry.refresh();
 
const settings = Settings.isolated({
  "compaction.enabled": true,
  "retry.enabled": true,
});
 
const { session } = await createAgentSession({
  authStorage,
  modelRegistry,
  settings,
  sessionManager: SessionManager.inMemory(),
  toolNames: ["read", "search", "find", "edit", "write"],
  enableMCP: false,
  enableLsp: true,
});
 
session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});
 
await session.prompt("Find all TODO comments in this repo and propose fixes.");
await session.dispose();

🤖 Toolresult

Custom Tools

Custom tools are model-callable functions that plug into the same tool execution pipeline as built-in tools.

A custom tool is a TypeScript/JavaScript module that exports a factory. The factory receives a host API (CustomToolAPI) and returns one tool or an array of tools.

What this is (and is not)

Custom tool: callable by the model during a turn (execute + Zod parameter schema).
Extension: lifecycle/event framework that can register tools and intercept/modify events.
Hook: external pre/post command scripts.
Skill: static guidance/context package, not executable tool code.

If you need the model to call code directly, use a custom tool.

Integration paths in current code

There are two active integration styles:

SDK-provided custom tools (options.customTools)
- Wrapped into agent tools via CustomToolAdapter or extension wrappers.
- Always included in the initial active tool set in SDK bootstrap.
Filesystem-discovered modules via loader API (discoverAndLoadCustomTools / loadCustomTools)
- Exposed as library APIs in src/extensibility/custom-tools/loader.ts.
- Host code can call these to discover and load tool modules from config/provider/plugin paths.

Model tool call flow
 
LLM tool call
   │
   ▼
Tool registry (built-ins + custom tool adapters)
   │
   ▼
CustomTool.execute(toolCallId, params, onUpdate, ctx, signal)
   │
   ├─ onUpdate(...)  -> streamed partial result
   └─ return result  -> final tool content/details

Discovery locations (loader API)

discoverAndLoadCustomTools(configuredPaths, cwd, builtInToolNames) merges:

Capability providers (toolCapability), including:
- Native OMP config (~/.omp/agent/tools, .omp/tools)
- Claude config (~/.claude/tools, .claude/tools)
- Codex config (~/.codex/tools, .codex/tools)
- Claude marketplace plugin cache provider
Installed plugin manifests (~/.omp/plugins/node_modules/* via plugin loader)
Explicit configured paths passed to the loader

Important behavior

Duplicate resolved paths are deduplicated.
Tool name conflicts are rejected against built-ins and already-loaded custom tools.
.md and .json files are discovered as tool metadata by some providers, but the executable module loader rejects them as runnable tools.
Relative configured paths are resolved from cwd; ~ is expanded.

Module contract

A custom tool module must export a function (default export preferred):

import type { CustomToolFactory } from "@oh-my-pi/pi-coding-agent";
 
const factory: CustomToolFactory = (pi) => ({
  name: "repo_stats",
  label: "Repo Stats",
  description: "Counts tracked TypeScript files",
  parameters: pi.zod.object({
    glob: pi.zod.string().optional().default("**/*.ts"),
  }),
 
  async execute(toolCallId, params, onUpdate, ctx, signal) {
    onUpdate?.({
      content: [{ type: "text", text: "Scanning files..." }],
      details: { phase: "scan" },
    });
 
    const result = await pi.exec(
      "git",
      ["ls-files", params.glob ?? "**/*.ts"],
      { signal, cwd: pi.cwd },
    );
    if (result.killed) {
      throw new Error("Scan was cancelled");
    }
    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, sample: files.slice(0, 10) },
    };
  },
 
  onSession(event) {
    if (event.reason === "shutdown") {
      // cleanup resources if needed
    }
  },
});
 
export default factory;

Schemas are authored with Zod (pi.zod) and flow through the shared validation/wire pipeline.

Factory return type:

CustomTool
CustomTool[]
Promise<CustomTool | CustomTool[]>

API surface passed to factories (`CustomToolAPI`)

From types.ts and loader.ts:

cwd: host working directory
exec(command, args, options?): process execution helper
ui: UI context (can be no-op in headless modes)
hasUI: false in non-interactive flows
logger: shared file logger
typebox: zod-backed compatibility shim for legacy TypeBox-style schemas
zod: injected zod/v4 module (canonical for new schemas)
pi: injected @oh-my-pi/pi-coding-agent exports
pushPendingAction(action): register a preview action for hidden resolve tool (docs/resolve-tool-runtime.md)
Loader starts with a no-op UI context and requires host code to call setUIContext(...) when real UI is ready.

Execution contract and typing

CustomTool.execute signature:

execute(toolCallId, params, onUpdate, ctx, signal);

params is statically typed from your Zod/TypeBox schema via Static<TParams>.
Runtime argument validation happens before execution in the agent loop.
onUpdate emits partial results for UI streaming.
ctx includes sessionManager, modelRegistry, current model, isIdle(), hasQueuedMessages(), abort(), and optional settings / autoApprove.
signal carries cancellation.

CustomToolAdapter bridges this to the agent tool interface and forwards calls in the correct argument order.

Tool definitions may also declare strict, hidden, deferrable, mcpServerName, mcpToolName, approval, and formatApprovalDetails.

How tools are exposed to the model

Tools are wrapped into AgentTool instances (CustomToolAdapter or extension wrappers).
They are inserted into the session tool registry by name.
In SDK bootstrap, custom and extension-registered tools are force-included in the initial active set.
CLI --tools currently validates only built-in tool names; custom tool inclusion is handled through discovery/registration paths and SDK options.

Rendering hooks

Optional rendering hooks:

renderCall(args, options, theme)
renderResult(result, options, theme, args?)

Runtime behavior in TUI:

If hooks exist, tool output is rendered inside a Box container.
renderResult receives { expanded, isPartial, spinnerFrame? }.
Renderer errors are caught and logged; UI falls back to default text rendering.

Session/state handling

Optional onSession(event, ctx) receives session lifecycle events, including:

start, switch, branch, tree, shutdown
auto_compaction_start, auto_compaction_end
auto_retry_start, auto_retry_end
ttsr_triggered, todo_reminder

Use ctx.sessionManager to reconstruct state from history when branch/session context changes.

Failures and cancellation semantics

Synchronous/async failures

Throwing (or rejected promises) in execute is treated as tool failure.
Agent runtime converts failures into tool result messages with isError: true and error text content.
With extension wrappers, tool_result handlers can further rewrite content/details and even override error status.

Cancellation

Agent abort propagates through AbortSignal to execute.
Forward signal to subprocess work (pi.exec(..., { signal })) for cooperative cancellation.
ctx.abort() lets a tool request abort of the current agent operation.

onSession errors

onSession errors are caught and logged as warnings; they do not crash the session.

Real constraints to design for

Tool names must be globally unique in the active registry.
Prefer deterministic, schema-shaped outputs in details for renderer/state reconstruction.
Guard UI usage with pi.hasUI.
Treat .md/.json in tool directories as metadata, not executable modules.

🤖 Toolresult

MCP configuration in OMP

This guide explains how to add, edit, and validate MCP servers for the OMP coding agent.

Source of truth in code:

Runtime config types: packages/coding-agent/src/mcp/types.ts
Config writer: packages/coding-agent/src/mcp/config-writer.ts
Loader + validation: packages/coding-agent/src/mcp/config.ts
Standalone mcp.json discovery: packages/coding-agent/src/discovery/mcp-json.ts
Schema: packages/coding-agent/src/config/mcp-schema.json

Preferred config locations

OMP can discover MCP servers from multiple tools (.claude/, .cursor/, .vscode/, opencode.json, and more), but for OMP-native configuration you should usually use one of these primary files:

Project: .omp/mcp.json
User: ~/.omp/agent/mcp.json

The native provider also reads .omp/.mcp.json and ~/.omp/agent/.mcp.json for compatibility, but OMP writes to the primary mcp.json paths above.

OMP also accepts fallback standalone files in the project root:

mcp.json
.mcp.json

Use .omp/mcp.json or ~/.omp/agent/mcp.json when you want OMP to own the configuration. Use root mcp.json / .mcp.json only when you want a portable fallback file that other MCP clients may also read.

Add a schema reference

Add this line at the top of the file for editor autocomplete and validation:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {}
}

OMP now writes this automatically when /mcp add, /mcp enable, /mcp disable, /mcp reauth, or other config-writing flows create or update an OMP-managed MCP file.

File shape

OMP supports this top-level structure:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "some-mcp-server"]
    }
  },
  "disabledServers": ["server-name"]
}

Top-level keys:

$schema — optional JSON Schema URL for tooling
mcpServers — map of server name to server config
disabledServers — user-level denylist used to turn off discovered servers by name; runtime loading reads this list from ~/.omp/agent/mcp.json

Server names must match ^[a-zA-Z0-9_.-]{1,100}$.

Supported server fields

Shared fields for every transport:

enabled?: boolean — skip this server when false
timeout?: number — MCP request timeout in milliseconds; 0 disables client-side MCP timeouts
auth?: { ... } — auth metadata used by OMP for OAuth/API-key flows
oauth?: { ... } — explicit OAuth client settings used during auth/reauth

Set OMP_MCP_TIMEOUT_MS=0 to disable the client-side timeout for every MCP server in the current process. Set it to a positive millisecond value, such as OMP_MCP_TIMEOUT_MS=120000, to apply one global timeout without editing each server entry.

`stdio` transport

stdio is the default when type is omitted.

Required:

command: string

Optional:

type?: "stdio"
args?: string[]
env?: Record<string, string>
cwd?: string

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/alice/projects",
        "/Users/alice/Documents"
      ]
    }
  }
}

This follows the official Filesystem MCP server package (@modelcontextprotocol/server-filesystem).

`http` transport

Required:

type: "http"
url: string

Optional:

headers?: Record<string, string>

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

This matches GitHub’s hosted GitHub MCP server endpoint.

`sse` transport

Required:

type: "sse"
url: string

Optional:

headers?: Record<string, string>

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "legacy-remote": {
      "type": "sse",
      "url": "https://example.com/mcp/sse"
    }
  }
}

sse is still supported for compatibility, but the MCP spec now prefers Streamable HTTP (type: "http") for new servers.

Auth fields

OMP understands two auth-related objects.

`auth`

{
  "type": "oauth" | "apikey",
  "credentialId": "optional-stored-credential-id",
  "tokenUrl": "optional-token-endpoint",
  "clientId": "optional-client-id",
  "clientSecret": "optional-client-secret"
}

Use this when OMP should remember how to rehydrate credentials for a server.

`oauth`

{
  "clientId": "...",
  "clientSecret": "...",
  "redirectUri": "...",
  "callbackPort": 3334,
  "callbackPath": "/oauth/callback"
}

Use this when the MCP server requires explicit OAuth client settings.

Slack is the clearest current example. Slack’s MCP server is hosted at https://mcp.slack.com/mcp, uses Streamable HTTP, and requires confidential OAuth with your Slack app’s client credentials.

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "YOUR_SLACK_CLIENT_ID",
        "clientSecret": "YOUR_SLACK_CLIENT_SECRET"
      },
      "auth": {
        "type": "oauth",
        "tokenUrl": "https://slack.com/api/oauth.v2.user.access",
        "clientId": "YOUR_SLACK_CLIENT_ID",
        "clientSecret": "YOUR_SLACK_CLIENT_SECRET"
      }
    }
  }
}

Relevant Slack endpoints from Slack’s docs:

MCP endpoint: https://mcp.slack.com/mcp
Authorization endpoint: https://slack.com/oauth/v2_user/authorize
Token endpoint: https://slack.com/api/oauth.v2.user.access

Common copy-paste examples

Filesystem server via stdio

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/one",
        "/absolute/path/two"
      ]
    }
  }
}

GitHub hosted server via HTTP

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

GitHub local server via Docker

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  }
}

This matches GitHub’s official local Docker image ghcr.io/github/github-mcp-server.

Slack hosted server via OAuth

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "YOUR_SLACK_CLIENT_ID",
        "clientSecret": "YOUR_SLACK_CLIENT_SECRET"
      },
      "auth": {
        "type": "oauth",
        "tokenUrl": "https://slack.com/api/oauth.v2.user.access",
        "clientId": "YOUR_SLACK_CLIENT_ID",
        "clientSecret": "YOUR_SLACK_CLIENT_SECRET"
      }
    }
  }
}

Secrets and variable resolution

This is the part that usually trips people up.

Discovery-time `${...}` expansion

OMP expands ${VAR} and ${VAR:-default} placeholders while discovering MCP configs from OMP-native files and standalone fallback files. Expansion applies recursively to string values in command, args, env, cwd, url, headers, auth, and oauth; unresolved placeholders remain literal strings.

Example:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

Pre-connect env/header resolution

Before OMP launches a stdio server or makes an HTTP/SSE request, it resolves stdio env values and HTTP/SSE headers values like this:

If a value starts with !, OMP runs the rest as a shell command with a 10s timeout and uses trimmed stdout.
If the command fails, times out, or prints only whitespace, that env/headers entry is omitted.
Otherwise OMP checks whether the value names an environment variable.
If that environment variable is set to a non-empty value, OMP uses the environment value; otherwise it uses the string literally.

Examples:

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "GITHUB_PERSONAL_ACCESS_TOKEN"
  },
  "headers": {
    "X-MCP-Insiders": "true"
  }
}

That means this is valid and convenient for local secrets:

"GITHUB_PERSONAL_ACCESS_TOKEN": "GITHUB_PERSONAL_ACCESS_TOKEN" → copy from the current shell environment
"Authorization": "Bearer hardcoded-token" → use the literal value
"Authorization": "!printf 'Bearer %s' \"$GITHUB_TOKEN\"" → build the header from a command

`disabledServers`

disabledServers is read from the user config file (~/.omp/agent/mcp.json) when a server is discovered from any source and you want OMP to ignore it without editing that other tool’s config.

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "disabledServers": ["github", "slack"]
}

`/mcp add` vs editing JSON directly

Use /mcp add when you want guided setup.

Use direct JSON editing when:

you need a transport or auth option the wizard does not prompt for yet
you want to paste a server definition from another MCP client
you want schema-backed validation in your editor

After editing, use:

/mcp reload to rediscover and reconnect servers in the current session
/mcp list to see which config file a server came from
/mcp test <name> to test a single server
/mcp reconnect <name> to reconnect one server without rediscovering all configs
/mcp resources, /mcp prompts, and /mcp notifications to inspect non-tool MCP capabilities

Validation rules OMP enforces

From validateServerConfig() in packages/coding-agent/src/mcp/config.ts:

stdio requires command
http and sse require url
a server cannot set both command and url
unknown type values are rejected

Practical implications:

Omitting type means stdio
If you paste a remote server config and forget "type": "http", OMP will treat it as stdio and complain that command is missing
sse remains valid for compatibility, but new hosted servers should usually be configured as http

Discovery and precedence

OMP does not merge duplicate server definitions across files. Discovery providers are prioritized, and the higher-priority definition wins. Separately, disabledServers from ~/.omp/agent/mcp.json can suppress a discovered server by name.

In practice:

prefer .omp/mcp.json or ~/.omp/agent/mcp.json when you want an OMP-specific override
keep server names unique across tools when possible
use disabledServers in the user config when a third-party config keeps reintroducing a server you do not want

Troubleshooting

`Server "name": stdio server requires "command" field`

You probably omitted type: "http" on a remote server.

`Server "name": both "command" and "url" are set`

Pick one transport. OMP treats command as stdio and url as http/sse.

`/mcp add` worked but the server still does not connect

The JSON is valid, but the server may still be unreachable. Use /mcp test <name> and check whether:

the binary or Docker image exists
required environment variables are set
the remote URL is reachable
the OAuth or API token is valid

The server exists in another tool’s config but not in OMP

Run /mcp list. OMP discovers many third-party MCP files, but project-level loading can also be disabled via the mcp.enableProjectConfig setting, and a user-level disabledServers entry can suppress a server by name.

References

MCP transport spec: https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
Filesystem server package: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem
GitHub MCP server: https://github.com/github/github-mcp-server
Slack MCP server docs: https://docs.slack.dev/ai/slack-mcp-server/

🤖 Toolresult

Extension Loading (TypeScript/JavaScript Modules)

This document covers how the coding agent discovers and loads extension modules (.ts/.js) at startup.

It does not cover gemini-extension.json manifest extensions (documented separately).

What this subsystem does

Extension loading builds a list of module entry files, imports each module with Bun, executes its factory, and returns:

loaded extension definitions
per-path load errors (without aborting the whole load)
a shared extension runtime object used later by ExtensionRunner

Primary implementation files

src/extensibility/extensions/loader.ts — path discovery + import/execution
src/extensibility/extensions/index.ts — public exports
src/extensibility/extensions/runner.ts — runtime/event execution after load
src/discovery/builtin.ts — native auto-discovery provider for extension modules
src/config/settings.ts — loads merged extensions / disabledExtensions settings

Inputs to extension loading

1) Auto-discovered native extension modules

discoverAndLoadExtensions() first asks discovery providers for extension-module capability items, then keeps only provider native items.

Native extension-module discovery comes from:

Project directory: <cwd>/.omp/extensions
User directory: ~/.omp/agent/extensions
Native legacy/settings JSON entries: <cwd>/.omp/settings.json#extensions and ~/.omp/agent/settings.json#extensions

Path roots come from the native provider (SOURCE_PATHS.native). Project lookup is cwd-only for these native roots; it does not walk ancestors.

Notes:

Native auto-discovery is currently .omp based.
Legacy .pi is still accepted in package manifests (pi.extensions) and project override lookup, but .pi/extensions is not a native root here.

2) Installed plugin extension entries

After native auto-discovery, discoverAndLoadExtensions() appends extension entry points from enabled installed plugins via getAllPluginExtensionPaths(cwd).

Plugin extension entries come from package omp.extensions / pi.extensions manifests, including enabled feature entries.

3) Explicitly configured paths

After plugin extension entries, configured paths are appended and resolved.

Configured path sources in the main session startup path (sdk.ts):

CLI-provided paths (--extension/-e, and --hook is also treated as an extension path)
Merged settings extensions array

Settings files:

User: ~/.omp/agent/config.yml (or custom agent dir via PI_CODING_AGENT_DIR)
Project/native settings capability: <cwd>/.omp/config.yml and <cwd>/.omp/settings.json

Native extension-module discovery also reads legacy JSON extension lists from:

~/.omp/agent/settings.json
<cwd>/.omp/settings.json

Examples:

# ~/.omp/agent/config.yml
extensions:
  - ~/my-exts/safety.ts
  - ./local/ext-pack

{
  "extensions": ["./.omp/extensions/my-extra"]
}

Enable/disable controls

Disable discovery

CLI: --no-extensions
SDK option: disableExtensionDiscovery

Behavior split:

SDK: when disableExtensionDiscovery=true, it still loads additionalExtensionPaths via loadExtensions().
CLI path building (main.ts) currently clears CLI extension paths when --no-extensions is set, so explicit -e/--hook are not forwarded in that mode.

Disable specific extension modules

disabledExtensions setting filters by extension id format:

extension-module:<derivedName>

derivedName is based on entry path (getExtensionNameFromPath), for example:

/x/foo.ts -> foo
/x/bar/index.ts -> bar

Example:

disabledExtensions:
  - extension-module:foo

Path and entry resolution

Path normalization

For configured paths:

Normalize unicode spaces
Expand ~
If relative, resolve against current cwd

If configured path is a file

It is used directly as a module entry candidate.

If configured path is a directory

Resolution order:

package.json in that directory with omp.extensions (or legacy pi.extensions) -> use declared entries
index.ts
index.js
Otherwise scan one level for extension entries:
- direct *.ts / *.js
- subdir index.ts / index.js
- subdir package.json with omp.extensions / pi.extensions

Rules and constraints:

no recursive discovery beyond one subdirectory level
declared extensions manifest entries are resolved relative to that package directory
declared entries are included only if file exists/access is allowed
in */index.{ts,js} pairs, TypeScript is preferred over JavaScript
symlinks are treated as eligible files/directories

Ignore behavior differs by source

Native auto-discovery (discoverExtensionModulePaths in discovery helpers) uses native glob with gitignore: true and hidden: false.
Explicit configured directory scanning in loader.ts uses readdir rules and does not apply gitignore filtering.

Load order and precedence

discoverAndLoadExtensions() builds one ordered list and then calls loadExtensions().

Order:

Native auto-discovered modules
Installed plugin extension entries
Explicit configured paths (in provided order)

In sdk.ts, configured order is:

CLI additional paths
Settings extensions

De-duplication:

absolute path based
first seen path wins
later duplicates are ignored

Implication: if the same module path is both auto-discovered and explicitly configured, it is loaded once at the first position (auto-discovered stage).

Module import and factory contract

Each candidate path is loaded with dynamic import:

await import(resolvedPath)
factory is module.default ?? module
factory must be a function (ExtensionFactory)

If export is not a function, that path fails with a structured error and loading continues.

Failure handling and isolation

During loading

Per extension path, failures are captured as { path, error } and do not stop other paths from loading.

Common cases:

import failure / missing file
invalid factory export (non-function)
exception thrown while executing factory

Runtime isolation model

Extensions are not sandboxed (same process/runtime).
They share one EventBus and one ExtensionRuntime instance.
During load, runtime action methods intentionally throw ExtensionRuntimeNotInitializedError; action wiring happens later in ExtensionRunner.initialize().

After loading

When events run through ExtensionRunner, handler exceptions are caught and emitted as extension errors instead of crashing the runner loop.

Minimal user/project layout examples

User-level

~/.omp/agent/
  config.yml
  extensions/
    guardrails.ts
    audit/
      index.ts

Project-level

<repo>/
  .omp/
    settings.json
    extensions/
      checks/
        package.json
      lint-gates.ts

checks/package.json:

{
  "omp": {
    "extensions": ["./src/check-a.ts", "./src/check-b.js"]
  }
}

Legacy manifest key still accepted:

{
  "pi": {
    "extensions": ["./index.ts"]
  }
}

🤖 Assistant

🤖 Toolresult

{“query”:“search find files code grep”,“activated_tools”:[“ast_grep”,“find”,“search”,“web_search”,“ast_edit”],“match_count”:5,“total_tools”:22}

🤖 Toolresult

{“query”:“web search internet query”,“activated_tools”:[“mcp__memory_search_nodes”,“mcp__context_query_docs”,“browser”],“match_count”:5,“total_tools”:24}

🤖 Assistant

Now let me search the web for “bst discord omp” and also search the workspace for any Discord-related files, and check the OMP docs for anything related.

🤖 Toolresult

Error: Expected property name or ’}’ in JSON at position 1 (line 1 column 2)

🤖 Toolresult

It appears there may be some confusion regarding the term “BST Discord.” Based on the context of AI coding agents, “omp” refers to Oh-My-Pi, an open-source terminal AI coding agent.

Oh-My-Pi (omp)

Oh-My-Pi is a terminal-based AI coding agent designed to act as a comprehensive “harness” for development workflows rather than just a simple CLI wrapper.

Core Functionality: It integrates directly with IDE-style tools, including Language Server Protocol (LSP) for symbol awareness, Debugger Adapter Protocol (DAP) for debugging (e.g., lldb, dlv, debugpy), and structured file editing using hash-anchored edits to save on tokens and improve reliability.
Architecture: It is a fork of the pi project and is built to be model-agnostic, allowing users to configure various providers through a models.yml file.
Resources: You can find the project on GitHub (can1357/oh-my-pi).

Clarification on “BST Discord”

The term “BST Discord” is widely used in online communities (specifically within the replica watch community, such as r/RepTime) to refer to “Buy/Sell/Trade” Discord servers. It is not a standard term associated with the Oh-My-Pi coding agent.

If you heard this term in the context of coding agents, it is possible it was a misunderstanding of a different abbreviation, a reference to a specific private community, or a confusion with other “Buy/Sell/Trade” channels common on Discord platforms.

Sources

7 sources
[1] github.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQE5O5qD3qrgdN1HjZBn8PAX5B-X28n899mUCM7oMIBzcrTOkC_6hndHxt4stuAarsk6-s6OXtOzIWDgGWQ1VnV7vxRMQrRVICA-MyfeoRC5hf10q337Y7FtzQ==
[2] knightli.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEkA_VunUZAxSBKpeX1N0zZzim9bh5IbVB9Wrnr6y-kpM4U15pLtPcbgT-WyBo8i6dBp7n4ulSJnR64vXFJHcWoRhWLWjPLZCkbYthi1RSow7ciGxIUKCXeXkvJ5TiIw1Dq9gaAuuC1zYsIJkw-4JeS8WCqopHx1h0pwNn_9bksmqRzzmoI5vLP300UNQ==
[3] youtube.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGG74jwkfsYWzxTzYRWDlQvPifv-91WjmyBXPvde8z7fWtUFJgOQDibu2rk4l9NbXnH3b55JodbyOE8xfH-QJ8JfGQd5ty6KRqcMzjxGfJHdf2lXddhI5JZDJS0EvifISS6
[4] deepseek.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEGkORNsrJm4-BiVY91o2oJFeSOsLCdutehjODXxnymU65P18wSka3ZaLgnwzsD2O2WW7cCC4-29w345yHPse7An1JLXXxESLScCnnAZVok2Rim2uovpL0D_ryh8GkXmmzbLEBY-xhm56YqEKEklJKX9vgpaOezXkCTH4A=
[5] repsguide.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGkZHwUTnFVvjLX8Qf98_TY1-ozicISc9cCiqM9Ej3ONsWCR0T_dRJQHdoj7OQO3bLwAR9u-pos6YzQK2MlCHWKBVBGNNcvvmM5ADYCMuv3_VFHspQ=
[6] repsguide.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQHvMuNwspetd3PYELY8z9tyQQ5n-wHxkOV-eEWJMxLO9wrZVDDlHK0tt8dTmg7VvWDUji_ek5tcgmY_NAg2go0cEYEwl70MhYZyUtAoH8vzhzP2Fj8=
[7] reddit.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEuFSIcZyubCGFXcZ6MIoivc_njbjtrKoxVNRuLir6Mc20mrpEO6tt9_9t6TgILWpALNTOBz26Uad8LQEWfjfZwv8fXkw-hLvmz2DNJd5fRZwHtxppxY91oh74WODLmduJZXs4Q98n6Y_2vurfB_Y83OC2dqXdg4JvLqx67Xl6vR6N7OApJQf3-jX8W7tFm9eu0e4OFnU6mLz07iVw=

Citations

“omp” coding agent Discord
“oh my pi” coding agent
What is “BST Discord” related to coding agents?

🤖 Toolresult

In 2026, the landscape of AI-assisted coding has shifted from simple autocomplete plugins to autonomous agents that live in your terminal and IDE. Integration between Discord and your terminal is generally handled as two separate workflows, as there is no single “best” tool that bridges both for professional coding.

1. The Professional “Terminal-First” Workflow (2026 Standard)

For coding, the industry has moved toward CLI-based autonomous agents. These tools run in your terminal, can read your full project structure, execute shell commands, run tests, and commit changes autonomously.

Claude Code (Top Recommendation): Currently the leader for terminal-based autonomous agentic coding. It features 200K+ context windows and excels at complex, multi-file refactors.
Goose (Open Source): A highly extensible AI agent (CLI, desktop app, and API) that supports the Model Context Protocol (MCP). It is excellent for connecting to databases, APIs, and file systems, making it very powerful for custom terminal workflows.
Codex CLI: Often used alongside or in place of Claude Code by developers who prefer model-agnostic setups or multi-session management.
Cline / Roo Code: If you prefer working inside VS Code but want the power of a terminal-agent, these open-source extensions allow you to use your own API keys and run agentic loops directly in your IDE’s integrated terminal.

2. The Discord & AI Coding Bridge

There is no standard product that “integrates” your terminal directly into Discord for coding—and for security and performance reasons, this is generally discouraged. However, you can achieve this integration using one of two methods:

Custom Discord Agentic Bots: Developers use frameworks like discord.js or python-discord to create custom bots. By connecting these to an AI model (OpenAI, Anthropic, or local Ollama instances), you can create a bot that lives in your server to answer technical questions or track development progress.
MCP (Model Context Protocol): As standards like MCP mature, you can build “bridges” where a Discord bot serves as an interface that communicates with your local terminal/agent. Tools like Goose or Fastio facilitate this by allowing agents to maintain persistent state and access external tools, which can include Discord hooks.

Summary Comparison Table

Tool	Best For	Integration Level
Claude Code	Complex, autonomous refactoring	Native Terminal / CLI
Cursor	All-in-one IDE experience	Full IDE (Forked VS Code)
Goose	Extensible agentic workflows	CLI + Desktop + MCP
Cline/Roo Code	Open-source agent control	VS Code Extension
Custom Bot	Community/Support/Notification	Discord API + Custom Logic

Recommendation for Your Workflow

If you want to move fast in 2026:

For Coding: Use Claude Code or Cursor. These are the industry standards for complex, agentic work.
For Discord: Do not try to run your primary coding agent through Discord. Instead, build or use a Discord bot for notifications and team coordination (e.g., using a webhook to notify a channel when your CLI agent completes a task or pushes a commit to GitHub).
For Customization: Explore MCP (Model Context Protocol)-compatible tools like Goose. This standard allows you to build a custom bridge between your terminal and any external interface (including Discord) if you have the technical capacity to build that glue.

🤖 Toolresult

As of June 2026, the Model Context Protocol (MCP) has become the de facto standard for connecting AI agents to external systems, including Discord. By using an MCP server for Discord, you can enable AI assistants (like Claude, Cursor, or custom agents) to interact with your Discord servers securely and contextually without needing to build a bespoke bot from scratch.

How Discord MCP Integration Works

Instead of traditional, hardcoded Discord bots, an MCP-powered setup acts as an intelligent middleware. You connect your AI client to an MCP Server, which acts as a bridge to the Discord API.

For AI Assistants: You configure your assistant (e.g., in Claude Desktop or an IDE) to load a Discord MCP server by providing your Discord Bot Token.
For Capabilities: The server exposes specific “tools” (e.g., send_message, manage_roles, get_channel_history) that the AI can call dynamically based on your natural language requests.

Popular Approaches & Tools

There are several well-maintained open-source implementations available as of mid-2026:

Standard Discord MCP Servers: Projects like discord-mcp (often available on GitHub) are widely used to provide comprehensive Discord API coverage, including channel management, moderation, and message automation.
Composio: Provides an MCP-compatible integration that simplifies connecting Discord to various AI frameworks, often handling the OAuth and authentication layers more robustly for enterprise or complex use cases.
Template-Based Automation: Community-built servers (e.g., discord-setup-mcp) allow you to use natural language to automate server infrastructure—such as creating categorized channels, setting up roles with specific permissions, and managing event schedules.

Implementation Steps

Create a Discord Bot: Go to the Discord Developer Portal, create an application, and create a “Bot”.
Enable Intents: You must enable the Message Content Intent, Server Members Intent, and Presence Intent in the bot settings to ensure the MCP server can read and interact with data correctly.
Configure MCP: Add the server configuration to your AI client’s configuration file (e.g., claude_desktop_config.json or your IDE’s MCP settings). You will typically provide the bot token as an environment variable.
- Example snippet for config:
```
{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@your-preferred-mcp/discord"],
      "env": { "DISCORD_TOKEN": "your_token_here" }
    }
  }
}
```

Security Considerations (Crucial in 2026)

With the rapid growth of the MCP ecosystem, security is a major focus this year:

Audit Permissions: Many Discord MCP servers require “Administrator” or broad permissions to function fully. Ensure you limit the bot’s scope if you only need it for specific tasks (like moderation or message reading).
Risk Mitigation: Recent audits have highlighted that many public MCP servers have vulnerabilities regarding SSRF (Server-Side Request Forgery) or excessive tool exposure. Only use reputable, well-reviewed MCP server implementations from trusted repositories.
Token Safety: Never hardcode your Discord Bot Token in public repositories. Use local environment variables or secure vault integrations.

Sources

Citations

building Discord bots with Model Context Protocol
current state of MCP Discord server integration June 2026
what is Model Context Protocol (MCP) Discord integration 2026

🤖 Toolresult

Aborted: The operation was aborted.

🤖 Assistant

👤 User

🤖 Assistant

Thinking Process

The user is asking about “bst discord for omp” - they want to understand the best way to set up Discord integration for OMP (Oh My Pi, their coding harness). From the previous turn’s research (which was aborted but I can see the results), I gathered substantial information. Let me synthesize what I know and create a comprehensive plan.

From the research:

OMP has no built-in Discord integration

The best approach is via MCP (Model Context Protocol) - OMP natively supports MCP servers

Discord MCP servers exist that bridge AI agents to Discord API

OMP supports extensions, hooks, and custom tools that could also be used

“BST” doesn’t refer to a specific Discord product here - the user is asking for the best Discord setup for OMP

I should outline the three main approaches: using a Discord MCP server as the primary method, building a deeper integration through OMP extensions, and setting up webhooks for simpler one-way notifications. Before I write out the full plan, I need to check what OMP configuration already exists on this system.

I have extensive research from the previous (aborted) turn. Let me check the current OMP config state and then synthesize everything into a definitive plan.

🤖 Toolresult

.omp/logs/

.6341210732edcc1b45942c9017f0494505c7c791-audit.json

.omp/agent/

config.yml

.omp/

gpu_cache.json

.omp/plugins/

omp-plugins.lock.json
package.json

🤖 Toolresult

.omp/agent/sessions/-/

2026-06-05T03-06-11-025Z_019e95be-d0d1-7000-9df7-99b17bd27363.jsonl
2026-06-05T02-54-31-614Z_019e95b4-24be-7000-bc40-cf93dce818e1.jsonl
2026-05-31T22-56-20-650Z_019e8040-a4aa-7000-822a-525d486ff6cd.jsonl
2026-05-31T22-56-20-650Z_019e8040-a4aa-7000-822a-525d486ff6cd/
2026-05-31T22-22-07-235Z_019e8021-4f83-7000-8cc4-2af4c0ac7cd7.jsonl
2026-05-31T22-22-07-235Z_019e8021-4f83-7000-8cc4-2af4c0ac7cd7/
2026-05-31T19-04-56-422Z_019e7f6c-c966-7000-ae10-1b2fd41ebf84.jsonl
2026-05-31T19-04-56-422Z_019e7f6c-c966-7000-ae10-1b2fd41ebf84/
2026-05-31T17-45-26-605Z_019e7f24-014d-7000-bd20-3b7dc2de1389.jsonl
2026-05-31T17-45-26-605Z_019e7f24-014d-7000-bd20-3b7dc2de1389/
2026-05-31T17-22-17-422Z_019e7f0e-cece-7000-82ff-c0bbad2306fc.jsonl
2026-05-31T17-22-17-422Z_019e7f0e-cece-7000-82ff-c0bbad2306fc/
2026-05-31T17-14-39-340Z_019e7f07-d16c-7000-bf8c-f2c4400d5d8d.jsonl
2026-05-31T17-14-39-340Z_019e7f07-d16c-7000-bf8c-f2c4400d5d8d/
2026-05-31T16-13-20-591Z_019e7ecf-af4f-7000-a99c-d4fe73fbc562.jsonl
2026-05-31T16-45-06-964Z_019e7eec-c614-7000-9d8e-a7abbf33667c.jsonl
2026-05-31T16-13-20-591Z_019e7ecf-af4f-7000-a99c-d4fe73fbc562/
2026-05-31T16-44-04-176Z_019e7eeb-d0d0-7000-aeae-bd4c04b94c5e.jsonl
.2026-05-31T16-42-39-343Z_019e7eea-856f-7000-b8e0-af08e5dac42f.jsonl.14f707f8a6adc799.tmp
2026-05-31T16-42-16-924Z_019e7eea-2ddc-7000-a3a7-c5f85b9ebee9.jsonl
2026-05-31T16-41-47-534Z_019e7ee9-bb0e-7000-8bac-18c38f73c2ea.jsonl
2026-05-31T16-41-04-760Z_019e7ee9-13f8-7000-81f4-b888ca2a6269.jsonl
.2026-05-31T16-40-31-543Z_019e7ee8-9237-7000-9557-a5cce4fa1281.jsonl.14f7077bc7b15c65.tmp
2026-05-31T16-39-23-016Z_019e7ee7-8688-7000-9833-8ea697d6277f.jsonl
2026-05-31T16-37-20-912Z_019e7ee5-a990-7000-8974-59f828458c2f.jsonl
.2026-05-31T16-36-30-367Z_019e7ee4-e41f-7000-9fc2-05df9403a7cd.jsonl.14f70691d782f4fc.tmp
2026-05-31T16-31-16-449Z_019e7ee0-19e1-7000-a213-f2938f6f2c58.jsonl
2026-05-31T15-38-27-716Z_019e7eaf-c004-7000-bc7f-dc8efa909bbb.jsonl
2026-05-31T15-38-27-716Z_019e7eaf-c004-7000-bc7f-dc8efa909bbb/
2026-05-31T15-22-27-268Z_019e7ea1-1844-7000-aded-550dd061c808.jsonl
2026-05-31T15-22-27-268Z_019e7ea1-1844-7000-aded-550dd061c808/
2026-05-31T15-05-10-626Z_019e7e91-46e2-7000-ae3d-7094b4a334e9.jsonl
2026-05-31T15-05-10-626Z_019e7e91-46e2-7000-ae3d-7094b4a334e9/
2026-05-31T14-44-49-101Z_019e7e7e-a34d-7000-97b2-60a32816ed1d.jsonl
2026-05-31T14-44-49-101Z_019e7e7e-a34d-7000-97b2-60a32816ed1d/

.omp/logs/

omp.2026-06-05.log
.6341210732edcc1b45942c9017f0494505c7c791-audit.json
omp.2026-06-01.log
omp.2026-05-31.log.gz

.omp/agent/

agent.db-wal
agent.db-shm
history.db-shm
history.db-wal
models.db-shm
memories/
models.db-wal
terminal-sessions/
agent.db
config.yml
sessions/
history.db
models.db

.omp/agent/sessions/

-/
-tmp/

.omp/agent/terminal-sessions/

pts-0
pts-2
tmux-%0
pts-1

.omp/agent/memories/—home-dev—/

skills/
MEMORY.md
memory_summary.md
raw_memories.md
rollout_summaries/

.omp/agent/memories/—home-dev—/skills/

omp-extension-bundling/
sveltia-cms-self-hosted/

.omp/agent/memories/—home-dev—/skills/omp-extension-bundling/

SKILL.md

.omp/agent/memories/—home-dev—/skills/sveltia-cms-self-hosted/

SKILL.md

.omp/agent/memories/

—home-dev—/

.omp/agent/memories/—home-dev—/rollout_summaries/

019e7eaf-c004-7000-bc7f-dc8efa909bbb-langfuse_langflow_en.md
019e7ecf-af4f-7000-a99c-d4fe73fbc562-pi_langfuse_omp_exte.md
019e7f0e-cece-7000-82ff-c0bbad2306fc-mixbox_agents_md_gen.md
019e7f24-014d-7000-bd20-3b7dc2de1389-agents_md_full_works.md
019e7f6c-c966-7000-ae10-1b2fd41ebf84-hugo_sveltia_lab_set.md
019e8021-4f83-7000-8cc4-2af4c0ac7cd7-sveltia_cms_local_gi.md
019e8040-a4aa-7000-822a-525d486ff6cd-knowledgebase_selfho.md

.omp/natives/

15.9.1/
15.7.3/

.omp/natives/15.9.1/

pi_natives.linux-x64-baseline.node
pi_natives.linux-x64-modern.node

.omp/

natives/
agent/
logs/
gpu_cache.json
plugins/

.omp/agent/sessions/-/2026-05-31T22-56-20-650Z_019e8040-a4aa-7000-822a-525d486ff6cd/

20-UpdateStartScript.md
20-UpdateStartScript.jsonl
17-UpdateHttpsProxy.md
17-UpdateHttpsProxy.jsonl
18-UpdateSystemdUnit.md
19-UpdateCmsConfig.md
19-UpdateCmsConfig.jsonl
18-UpdateSystemdUnit.jsonl
local/
0.read.log
16-AuditRunningState.md
16-AuditRunningState.jsonl
13-AuditCoreConfig.jsonl
13-AuditCoreConfig.md
14-AuditApiShim.jsonl
14-AuditApiShim.md
15-AuditContentAndServices.md
15-AuditContentAndServices.jsonl

.omp/agent/sessions/-/2026-05-31T22-56-20-650Z_019e8040-a4aa-7000-822a-525d486ff6cd/local/

setup-sveltia-knowledgebase.md

.omp/agent/sessions/-/2026-05-31T22-22-07-235Z_019e8021-4f83-7000-8cc4-2af4c0ac7cd7/

35.bash-original.log
5.bash.log

.omp/agent/sessions/-/2026-05-31T19-04-56-422Z_019e7f6c-c966-7000-ae10-1b2fd41ebf84/

11-GatherContent.md
11-GatherContent.jsonl
10-SectionIndexes.md
10-SectionIndexes.jsonl
9-SveltiaCmsFiles.md
9-SveltiaCmsFiles.jsonl
12-LaunchFiles.md
12-LaunchFiles.jsonl
local/
5.read.log
5-HugoBookTheme.md
5-HugoBookTheme.jsonl
4-InventoryAllDocs.jsonl
4-InventoryAllDocs.md
7-PortAndServiceSurvey.md
7-PortAndServiceSurvey.jsonl
8-HugdownDocsContent.md
8-HugdownDocsContent.jsonl
6-ExistingLabReference.md
6-ExistingLabReference.jsonl

.omp/agent/sessions/-/2026-05-31T19-04-56-422Z_019e7f6c-c966-7000-ae10-1b2fd41ebf84/local/

setup-sveltia-knowledgebase.md

.omp/agent/sessions/-/2026-05-31T17-45-26-605Z_019e7f24-014d-7000-bd20-3b7dc2de1389/

24.bash.log
20.bash.log
18.bash.log
13.bash.log
3.bash.log
4.bash-original.log
local/

.omp/agent/sessions/-/2026-05-31T17-45-26-605Z_019e7f24-014d-7000-bd20-3b7dc2de1389/local/

generate_agents_guidelines.md

.omp/agent/sessions/-/2026-05-31T17-22-17-422Z_019e7f0e-cece-7000-82ff-c0bbad2306fc/

local/
0-ScanCoreSrc.md
0-ScanCoreSrc.jsonl
1-ScanTests.md
1-ScanTests.jsonl
2-ScanConfigsBuild.md
2-ScanConfigsBuild.jsonl
3-ScanScriptsDocs.md
3-ScanScriptsDocs.jsonl

.omp/agent/sessions/-/2026-05-31T17-22-17-422Z_019e7f0e-cece-7000-82ff-c0bbad2306fc/local/

generate_agents_guidelines.md

.omp/agent/sessions/-/2026-05-31T16-13-20-591Z_019e7ecf-af4f-7000-a99c-d4fe73fbc562/

152.bash-original.log
142.bash-original.log
137.bash-original.log
125.bash-original.log
123.bash-original.log
121.bash-original.log
104.bash-original.log
74.bash.log
69.bash-original.log
65.bash-original.log
63.bash-original.log
50.bash.log
40.bash.log
22.bash.log
15.bash.log
12.bash-original.log
10.bash.log
8.bash.log
7.bash.log
6.bash.log
5.bash.log
2.bash.log
1.bash.log

.omp/agent/sessions/-/2026-05-31T15-38-27-716Z_019e7eaf-c004-7000-bc7f-dc8efa909bbb/

49.bash-original.log
46.bash.log
39.bash.log
13.bash-original.log

.omp/agent/sessions/-/2026-05-31T15-22-27-268Z_019e7ea1-1844-7000-aded-550dd061c808/

16.bash.log
9.bash-original.log

.omp/agent/sessions/-tmp/

2026-05-31T15-20-42-387Z_019e7e9f-7e93-7000-84e8-6099ec709980.jsonl

.omp/agent/sessions/-/2026-05-31T15-05-10-626Z_019e7e91-46e2-7000-ae3d-7094b4a334e9/

32.bash.log
30.bash.log
28.bash.log
24.bash.log
18.bash.log
16.bash-original.log
14.bash.log
8.bash.log

.omp/agent/sessions/-/2026-05-31T14-44-49-101Z_019e7e7e-a34d-7000-97b2-60a32816ed1d/

4-ExploreConfigsAndDocs.jsonl
4-ExploreConfigsAndDocs.md
0-ExplorePyFlow.md
0-ExplorePyFlow.jsonl
3-ExploreActiveProjects.jsonl
3-ExploreActiveProjects.md
2-ExploreHugdown.jsonl
2-ExploreHugdown.md
1-ExploreAudioMixbox.md
1-ExploreAudioMixbox.jsonl
5-ExplorePyAudioAndTesting.md
5-ExplorePyAudioAndTesting.jsonl

.omp/plugins/

omp-plugins.lock.json
bun.lock
package.json

.omp/natives/15.7.3/

pi_natives.linux-x64-baseline.node
pi_natives.linux-x64-modern.node

🤖 Assistant

🤖 Toolresult

¶.omp/agent/config.yml#557C
1:providers:
2: webSearch: gemini
3: shakeSummaryModel: lfm2-1.2b
4: image: openai
5:setupVersion: 1
6:modelRoles:
7: default: google-antigravity/claude-opus-4-6-thinking:high
8:theme:
9: dark: dark-cosmos
10:power:
11: preventIdleSleep: false
12: preventSystemSleep: true
13:interruptMode: wait
14:compaction:
15: thresholdPercent: 40
16: handoffSaveToDisk: true
17:memory:
18: backend: local
19:todo:
20: eager: true
21:renderMermaid:
22: enabled: true
23:tts:
24: enabled: true
25:vault:
26: enabled: true
27:tools:
28: discoveryMode: all
29:mcp:
30: discoveryMode: true
31: notifications: true
32:task:
33: eager: true
34:extensions:
35: - /home/dev/.omp/plugins/node_modules/pi-langfuse

🤖 Toolresult

¶.omp/plugins/package.json#DB73
1:{
2: “name”: “omp-plugins”,
3: “private”: true,
4: “dependencies”: {
5: “pi-langfuse”: “^1.4.3”
6: }
7:}

🤖 Toolresult

.antigravity-server/data/User/globalStorage/kilocode.kilo-code/settings/

mcp_settings.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/ar/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/ca/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/cs/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/de/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/en/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/es/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/fr/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/hi/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/id/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/it/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/ja/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/ko/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/nl/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/pl/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/pt-BR/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/ru/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/sk/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/th/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/tr/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/uk/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/vi/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/zh-CN/

mcp.json

.antigravity-server/extensions/kilocode.kilo-code-5.16.1-universal/dist/i18n/locales/zh-TW/

mcp.json

.antigravity-server/bin/1.23.2-15487b3041e65228cae24980a3f796c905ef582c/extensions/antigravity/schemas/

mcp_config.schema.json

.cache/Langflow/58318164-d84a-4dca-bcb6-a4e519568df5/

_mcp_servers.json

.cache/pnpm/metadata-v1.3/registry.npmjs.org/

mcp-hello-world.json

find timed out after 5s; returning 27 partial matches — increase timeout or narrow pattern

🤖 Assistant

Good — no existing Discord MCP config. Let me now do the final deep web searches to find the specific best Discord MCP server packages, and then check the OMP docs for the notification/webhook extension pattern.

🤖 Toolresult

There is no single “official” Discord MCP server maintained by the Model Context Protocol organization; rather, there is a vibrant ecosystem of community-built Discord MCP servers.

Because these servers are community-developed, you have several options depending on your specific needs (e.g., simple messaging vs. advanced server management).

Common Discord MCP Server Options

You can find and install these via npx or by cloning their repositories. Popular implementations include:

aj-geddes/discord-agent-mcp: A highly featured server often used for comprehensive management, including roles, events, and moderation.
iqai/mcp-discord: A robust server that supports messaging, channel management, forum posts, and webhook operations.
pagelines/discord-mcp: A straightforward implementation focused on reading/sending messages and managing threads.

General Setup Steps

Regardless of which server you choose, the general integration workflow remains consistent:

Discord Developer Portal: Create a new application at the Discord Developer Portal.
Bot Token & Intents:
- Generate a Bot Token.
- Enable Privileged Gateway Intents (typically Message Content, Server Members, and Presence) in the Bot settings.
Permissions: Invite the bot to your Discord server with the necessary permissions (e.g., Read Messages, Send Messages, Manage Channels).
Configuration: Add the server to your MCP client configuration (e.g., claude_desktop_config.json).

Example Configuration (Conceptual):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-discord"], 
      "env": {
        "DISCORD_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Important Considerations

Security: Never commit your Discord bot token to public version control. Use environment variables or .env files.
Permissions: Use the principle of “least privilege.” Only grant the bot the specific permissions required for the tasks you want the AI to perform.
Finding Servers: You can browse curated lists of these servers on platforms like Smithery or MCPBundles.

Sources

Citations

Security: Never commit your Discord bot token to public version control
[29] github.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGOzqe4P1Vs-z0FSV8aVoQvVZA-0JD3IQnkqbZ64S3gH4TsMQ7AGuZ7QHXtV0NXtF8YDMV3bTFnzyYgewhuB6RmovjGUgwzYo0peVCNctm13-_PIAkL6TU=
Important Considerations
Security: Never commit your Discord bot token to public version control
[30] github.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGOzqe4P1Vs-z0FSV8aVoQvVZA-0JD3IQnkqbZ64S3gH4TsMQ7AGuZ7QHXtV0NXtF8YDMV3bTFnzyYgewhuB6RmovjGUgwzYo0peVCNctm13-_PIAkL6TU=
env files [31] mcp.directory https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEmKOztjRjrY5TJilWjF57aUGD4KrNl7fI5cvZcI_2vKQHIcIUh0nRSaFBjDL1ATnL4jdpFqpt0LLJ50SqwVFbu9DnH08q9ZQZlcR9pcHSlTsYxisKHmZfW5sV5 env files
[32] mcp.directory
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEmKOztjRjrY5TJilWjF57aUGD4KrNl7fI5cvZcI_2vKQHIcIUh0nRSaFBjDL1ATnL4jdpFqpt0LLJ50SqwVFbu9DnH08q9ZQZlcR9pcHSlTsYxisKHmZfW5sV5
- Permissions: Use the principle of “least privilege.” Only grant the bot the specific permissions required for the tasks you want the AI to perform
  [33] github.com
  https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGOzqe4P1Vs-z0FSV8aVoQvVZA-0JD3IQnkqbZ64S3gH4TsMQ7AGuZ7QHXtV0NXtF8YDMV3bTFnzyYgewhuB6RmovjGUgwzYo0peVCNctm13-_PIAkL6TU=
- Permissions: Use the principle of “least privilege.” Only grant the bot the specific permissions required for the tasks you want the AI to perform
  [34] pypi.org
  https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQFIo8YaP7_dQxw0KppKOy0OybzY9ghBqYmFVnk8a5HCry6bEkBkTgOt_URxKkPPJL8aLa3LSmWdMQjB5RpC4q1SUDCPhKFlpNJ9FcAwPrhiXmtOk4lbkqhuavoV
- Finding Servers: You can browse curated lists of these servers on platforms like Smithery or MCPBundles
  [35] mcpbundles.com
  https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQFLvfFwm2haWEoPpCJ-LoEkcpR5lW5ij-XMvsznivq11cRB_AkfA683P9Drh_odDb4iWAr-2VdV6FMQV6rt5qxYsXEtENA2L1DB7PyuM55eoeuX-_l41lYUpQxTddbNgGJ_WWtmhsEWAw==
- Finding Servers: You can browse curated lists of these servers on platforms like Smithery or MCPBundles
  Search queries: 4

how to use discord with Model Context Protocol
is there an official discord MCP server from modelcontextprotocol
discord MCP server npm @modelcontextprotocol

🤖 Toolresult

To set up Discord webhook notifications for your terminal AI coding agent (such as Oh-My-Pi / omp), you can use either a simple shell script approach or the more standardized Model Context Protocol (MCP).

1. The “Oh-My-Pi” (OMP) Context

Oh-My-Pi (omp) is a powerful, open-source terminal AI coding agent that acts as an alternative to tools like Claude Code. It features a robust architecture including LSP and DAP integration. Because it is designed to be configurable, you can integrate notifications by triggering them via its hook points or by wrapping your command execution.

2. Method A: The Simple Shell Wrapper (Recommended for CLI)

If you run your agent with specific commands, you can create a simple shell wrapper to send a Discord notification via curl immediately after the process completes.

Create a Webhook in Discord:
- Go to Server Settings > Integrations > Webhooks.
- Create a new webhook and copy the Webhook URL.

Create a notify.sh script:

#!/bin/bash
# Your Webhook URL
WEBHOOK_URL="https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
 
# Run your agent command
omp "$@"
 
# Send notification after completion
curl -H "Content-Type: application/json" \
     -X POST \
     -d "{\"content\": \"🚀 AI Agent task completed!\"}" \
     $WEBHOOK_URL

Use this script in place of the omp command.

3. Method B: Using MCP (Model Context Protocol)

For a more integrated “extension” feel, you can use an MCP Server. This allows the AI agent itself to “know” about the Discord notification tool and trigger it when it deems a task finished.

Discord Notification MCP Server: There is a community-maintained Discord Notification MCP Server that allows AI agents to send messages to Discord.
How it works: Once configured as an MCP server for your agent, you can prompt the agent: “When you finish this refactoring task, send a message to my Discord channel using the discord-notification tool”.

Summary of Differences

Method	Complexity	Best For
Shell Wrapper	Low	Quick notifications for every task completion.
MCP Server	Medium	Agent-initiated notifications (e.g., “Tell me when this specific long-running job finishes”).

If you are looking for a “Claude Extension” style hook, ensure you are referencing the specific environment (e.g., VS Code or Cursor) if you are not running purely in the terminal. For pure terminal use, the Shell Wrapper is generally the most reliable method for 2026 workflows.

Sources

Citations

Method	Complexity	Best For
Shell Wrapper	Low	Quick notifications for every task completion
[18] skywork.ai

https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQErGQWh_Ct7F_nGMNlmz4IGtyVoJ4pOxOha9lvJjVJ9qZ6DVoR5rpVaeBVIGG9BfiTZpzGgb2aXv4yofTCfJuJY2zIe01-vzB5eU1XioI6N0KbtO9Sv0SO_9R147fZkYtoKNLTIYDfKlWbUjWymYL5iy3OM1pXGr3zT4ycuh02LZRXTdZyJHA==
|

| MCP Server | Medium | Agent-initiated notifications (e.g., “Tell me when this specific long-running job finishes”)
[19] knightli.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQGYaNyUfwVwFJQULsm0NgQG7hcRIoGL_nJNnZU7adX5zep7HzvWCemG9w7tNXs40BGXzNDIjAiehBtDvXUF8wmu0wuevnrd_pgU9iJj3mjapsdPa12o-aglOqt_GG-c6i8yMiX4K4LOVQK6nOIy17pF-opvh6xATyCDOunE8OpnVT9YFC6DIW0ecKKGEw==
If you are looking for a “Claude Extension” style hook, ensure you are referencing the specific environment (e.g., VS Code or Cursor) if you are not running purely in the terminal
[20] render.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQH9EgjbpawT2EzuVOAeU43HC92LAR8SelXNJex49cvb7FfTeyQpJBupahoGBztlJPFmeuiJdtD9YJB649w99pz56kAOKw8_Dwtj_8EnnisPBEbaQ8LIfydmF9UNN3eC72zi-mA3oAW8tsRRJWF1la5tCOBnzyiXTHa10ptznxtg7wd4fj9NfS454fBKyrz-PQ==
If you are looking for a “Claude Extension” style hook, ensure you are referencing the specific environment (e.g., VS Code or Cursor) if you are not running purely in the terminal
[21] askubuntu.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQEBhN3NgOHHzjlZ09GGBISBrgCuyABchRffdERros-MWQqjJOXKWz5szrV-7qgjlKjIJAZ4myqZ2sceeRlETEEqbELLsGrXN2Wih_nERkEBvXWT3XjZlwp65jm5rP5USkqQU-hjSrJv4-mIWYiA9HFBc-0bUoKDOHnr3e-YnMeI1yqPUh2X4bZTFI2WSYDOtqSd9xO96zwZQBqtcSJ3DVQ=
For pure terminal use, the Shell Wrapper is generally the most reliable method for 2026 workflows
[22] medium.com
https://vertexaisearch.cloud.google.com/grounding-api-redirect/AUZIYQHR_iDMSLLHXyuxNXybgIj—uQouAlD5ATMMhjN3KbGhYEovWZC40SncSQEz0fDDhSxPwxE69j4-y2z9S-EENY_7OaosCy1q1nCSzSxzZ6WZs1rgwl7mbc927it7TYjqtKiBXNMFT1Y1hfs-MmHGo4ZKyudx9faLt1-Q30FsDrBacGTWkXijUNltD4J-qPacp-hCzc=
For pure terminal use, the Shell Wrapper is generally the most reliable method for 2026 workflows
Search queries: 4

“omp” terminal AI coding agent
“oh my pi” terminal AI coding agent
how to send Discord webhook notification from terminal session complete

🤖 Toolresult

Several Discord MCP (Model Context Protocol) servers exist that allow AI agents to interact with Discord. These servers typically provide send_message and read_messages (or get_channel_history) tools to facilitate interaction.

Popular Discord MCP Servers

Because there is no single “official” package, several repositories are commonly used. You can choose based on your needs for features, maintenance, and setup preference:

Repository	NPM Package / Install	Key Features
hanweg/mcp-discord	Via Git/uv	Comprehensive management, forum support, reactions.
IQAIcom/mcp-discord	`npx @iqai/mcp-discord`	Messaging, channel management, forums, webhooks.
@quadslab.io/discord-mcp	`npm install`	139+ tools, advanced roles/channels/moderation.
v-3/discordmcp	Git clone/npm	Simple, focused on send/read messages.

Implementation Details

Most implementations share a similar approach to these core requirements:

send_message: Usually requires a channel ID or name and the message content as arguments.
read_messages / get_channel_history: Typically takes a channel ID and an optional limit parameter to retrieve recent history.

General Setup Steps

Regardless of the repository you choose, the standard workflow is:

Discord Developer Portal: Create a new application and a Bot user.
Permissions & Intents: Enable the following in the Bot settings:
- Privileged Intents: MESSAGE CONTENT INTENT, PRESENCE INTENT, and SERVER MEMBERS INTENT.
- Required Permissions: View Channels, Send Messages, and Read Message History.
Authentication: Save your Bot Token (e.g., DISCORD_TOKEN) to a .env file or your MCP configuration.
Configuration: Add the server to your claude_desktop_config.json (or other MCP client settings).

Example Configuration (Generic):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-discord", "--config", "YOUR_DISCORD_TOKEN"]
    }
  }
}

Note: Always verify the tool names in the specific repository’s README.md or documentation, as tool naming conventions can vary slightly between packages (e.g., read-messages vs read_messages).

Sources

Citations

“mcp-discord” npm package
Discord MCP server implementation send_message get_channel_history
github “mcp-discord” OR “discord-mcp-server”

🤖 Assistant

Now I have comprehensive research. Let me write the definitive plan document.

🤖 Toolresult

{“query”:“write file create”,“activated_tools”:[“mcp__memory_create_entities”,“mcp__memory_create_relations”,“write”],“match_count”:3,“total_tools”:16}

🤖 Assistant

🤖 Toolresult

¶.omp/agent/sessions/-/2026-06-05T03-06-11-025Z_019e95be-d0d1-7000-9df7-99b17bd27363/local/PLAN.md#2E20
Successfully wrote 8813 bytes to .omp/agent/sessions/-/2026-06-05T03-06-11-025Z_019e95be-d0d1-7000-9df7-99b17bd27363/local/PLAN.md

tags	agent-session, model/claude-opus-4-6-thinking
aliases	019e95be-d0d1-7000-9df7-99b17bd27363

Agentic Memory Garden

Explorer

Best Discord for OpenMP

Best Discord for OpenMP

Telemetry Stats

Chat Transcript

👤 User

🤖 Assistant

🤖 Toolresult

🤖 Assistant

🤖 Toolresult

Documentation

🤖 Toolresult

🤖 Toolresult

Dev Server Memory

Environment

Workspace Projects & Port Map

MixBox Monorepo

Self-Hosted Knowledgebase (0rk.de)

Stack

HTTPS Proxy Routing

Local GitHub API Shim (local-github-api.mjs)

CMS Config

Systemd Services

Pitfalls

Hugo Book Theme

OMP Extension System

pi-langfuse Extension

Langfuse

Langflow

Generated Docs

Critical Lessons

🤖 Assistant

🤖 Toolresult

🤖 Assistant

🤖 Toolresult

🤖 Toolresult

Extensions

What an extension is

Runtime model

Quick start

Extension API surfaces

1) Registration and actions (ExtensionAPI)

Message delivery semantics

2) Handler context (ExtensionContext)

3) Command context (ExtensionCommandContext)

Event surface (current names and behavior)

Session lifecycle

Prompt and turn lifecycle

Tool lifecycle

Reliability/runtime signals

User command interception

resources_discover

Tool authoring details

UI integration points

Interactive mode (extension-ui-controller.ts)

RPC mode (rpc-mode.ts)

Print/headless/subagent paths

Background interactive mode

Session and state patterns

Rendering extension points

Custom message renderer

Assistant thinking renderer

Tool call/result renderer

Constraints and pitfalls

Extensions vs hooks vs custom-tools

🤖 Toolresult

Hooks

Current status in runtime

Key files

What a hook module is

Discovery and loading

Path resolution

Important legacy mismatch

Event surfaces

Session events

Agent/context events

Tool events (pre/post model)

Execution model and mutation semantics

1) Pre-execution: tool_call

1) Registration and actions (`ExtensionAPI`)

2) Handler context (`ExtensionContext`)

3) Command context (`ExtensionCommandContext`)

`resources_discover`

Interactive mode (`extension-ui-controller.ts`)

RPC mode (`rpc-mode.ts`)

1) Pre-execution: `tool_call`

3) Post-execution: `tool_result`

UI interactions (`HookContext.ui`)

What `createAgentSession()` discovers by default

Selection order when `model` is omitted

`createAgentSession()` return value

API surface passed to factories (`CustomToolAPI`)

`stdio` transport

`http` transport