Oh My Pi

⚙️ System Fundamentals

2 min read

Workspace structures, lifecycle protocols, execution loops, and ecosystem map.

~: /home/loca packages: ~/.omp/plugins/node_modules/@oh-my-pi/ truth: src/ ignored: dist/

📂 Workspace Layout

~ (/home/loca) execution workspace.

~/
├── AGENTS.md             # Guidelines & safety ladders
├── skills/               # Static procedural runbooks (skill://<name>)
├── docs/                 # Architecture guides
└── .omp/                 # Verified runtime state
    ├── agent/            # DBs (agent, history, models), config.yml, sessions/
    ├── logs/             # Execution logs
    ├── plugins/          # Registry: package.json, bun.lock, node_modules/
    ├── extensions/       # Custom extensions
    ├── cache/            # Model caches
    └── mcp.json          # Model Context Protocol config

🗺️ Ecosystem Map

flowchart LR
  subgraph Packaging
    P[Plugin Package] -->|package.json| EP[Entrypoints]
    P -->|manifest| PF[Tools/Hooks/Commands/Features/Settings]
  end
  subgraph Runtime
    EP -->|ExtensionFactory| E[Extension]
    E -->|pi.on| EV[Events]
    E -->|pi.registerTool| RT[Registered Tools]
  end
  subgraph Agent Loop
    A[Agent Profile] -->|Calls| T[Tools]
    S[Skill.md] -.->|skill://| A
  end

🧩 Concept Matrix & Core Entities

  • Plugin: Packaging unit distributed via npm at ~/.omp/plugins/node_modules/<pkg>/. Declares capabilities (tools, hooks, extensions, commands) in package.json.
  • Extension: Runtime session factory/environment at ~/.omp/extensions/<ext>/ (in JS/TS). Runs state-isolated, exports ExtensionFactory(pi), subscribes to pi.on(...), and registers features/tools.
  • Agent: Executor persona/profile defined via MD/YAML (prompt, tools, model, thinkingLevel, output, blocking, spawns).
  • Tool: Callable LLM capability exposing schema/label/description. Executes via AgentTool or ToolDefinition (Built-in/Plugin/Extension).
  • Skill: Non-executable procedural knowledge at ~/skills/<name>/SKILL.md (skill://<name>). Injected dynamically into prompt.

🔄 Request Flow

flowchart TD
    Start([Request]) --> Bind[1. Bind Agent & Session]
    Bind --> Config[2. Load Plugins & Extensions]
    Config --> Prompt[3. Inject Prompt & Skills]
    Prompt --> LLM{Inference Loop}
    LLM <-->|Tools| ToolExec[Execute Tool]
    LLM --> End([Deliver Result])

⚙️ Protocols

  • Interactive: CLI/TUI human-in-the-loop interface.
  • Batch: YAML-defined non-interactive orchestrator (omp-swarm).
  • MCP: Model Context Protocol client/server integration.
  • SessionEvents: Event emitter API (pi.on()) for execution phases.
  • IRC: Async message-passing (send, wait, inbox) for subagent concurrency.

🛠️ Manifests & Developer Checklist

Checklist:

  • Bundle Functionality: Create Plugin with package.json manifest.
  • Hook Events: Export Extension factory consuming ExtensionAPI.
  • Create LLM Action: Build Tool (AgentTool / ToolDefinition).
  • Teach Procedure: Write Skill at skills/<name>/SKILL.md with a precise trigger.
  • Delegate Work: Use task tool to spawn Agents.

Plugin (package.json):

{
  "name": "@oh-my-pi/sample",
  "omp": {
    "extensions": ["./dist/ext.js"],
    "tools": [{ "name": "tool", "schema": {} }]
  }
}

Extension (ext.ts):

export const ExtensionFactory = (pi: ExtensionAPI) => {
  pi.on("session:init", (session) => console.log(session.id))
  pi.registerTool("dynamic", { execute: async (args) => args })
}

Graph View

Backlinks