🧩 Plugins

Current local truth: .omp/plugins/package.json declares @oh-my-pi/omp-stats@^15.10.10 and @oh-my-pi/swarm-extension@^13.17.0; .omp/plugins/omp-plugins.lock.json pins both as enabled at 15.10.10 and 13.17.0.

🧠 Mental model

Plugin	Use it when you need	Core output	Default state path
`@oh-my-pi/omp-stats@15.10.10`	Local AI usage/cost/latency dashboard	Web dashboard or JSON stats	`~/.omp/stats.db`
`@oh-my-pi/swarm-extension@13.17.0`	Repeatable multi-agent workflows	`.swarm_<name>/` state, logs, artifacts	`<workspace>/.swarm_<name>/`

⚡ Install / verify

cd ~/.omp/plugins
bun install --frozen-lockfile
bun pm ls @oh-my-pi/omp-stats @oh-my-pi/swarm-extension

Expected local plugin lock:

{
  "@oh-my-pi/omp-stats": "15.10.10",
  "@oh-my-pi/swarm-extension": "13.17.0"
}

📊 `omp-stats` — local usage observability

What it does

Reads omp session JSONL logs from ~/.omp/agent/sessions/.
Aggregates requests, tokens, cost, cache rate, error rate, duration, TTFT, tokens/sec.
Stores rollups in SQLite at ~/.omp/stats.db.
Serves a local Chart.js dashboard on port 3847 by default.

Fast commands

# Start local dashboard
omp-stats
 
# Use a custom port
omp-stats --port 8080
 
# Sync logs and print a terminal summary
omp-stats --sync
 
# Sync logs and emit machine-readable JSON
omp-stats --json

✅ Use omp-stats as the source-verified CLI. Some older docs say omp stats; the installed package exposes the omp-stats binary.

Operator rules

🟢 Use for: personal/local cost reviews, model comparison, cache/error checks, quick JSON export.
🟡 Adapt for Ompcord: copy its parsing/cost ideas for per-thread Amy/Ompcord stats.
🔴 Do not directly reuse for Ompcord thread status: it reads global ~/.omp/agent/sessions/, not ~/.omp/amy-sessions/<threadId>/.
🔒 Never expose dashboard publicly: it is local usage telemetry, not an internet-facing service.

🐝 `swarm-extension` — YAML multi-agent orchestration

What it does

Runs a YAML-defined agent graph as sequential, parallel, or pipeline.
Builds a DAG from waits_for / reports_to.
Executes dependency waves: same-wave agents run in parallel; later waves wait.
Persists live state, logs, and artifacts under .swarm_<name>/.

Fast commands

# Best for long jobs: standalone runner, no TUI timeout
omp-swarm path/to/swarm.yaml
 
# Background long run
nohup omp-swarm path/to/swarm.yaml > swarm.log 2>&1 & disown

Inside an omp TUI session, after extension registration:

/swarm run path/to/swarm.yaml
/swarm status <name>
/swarm help

Production-grade YAML template

swarm:
  name: wiki-plugin-docs-upgrade
  workspace: ./work/wiki-plugin-docs-upgrade
  mode: parallel # explicit deps below create waves; independent agents fan out
  model: claude-sonnet-4-5
 
  agents:
    planner:
      role: docs-scope-architect
      task: |
        Goal: define the smallest safe documentation update for the omp npm plugins.
 
        Read:
        - content/knowledge/skills/omp-plugins.md
        - content/knowledge/agent-ecosystem.md
 
        Write:
        - plan/scope.md
        - signals/planner.done
 
        Acceptance:
        - Identify exact sections to change.
        - Preserve source-verified claims only.
        - Do not edit files.
        - If blocked, write BLOCKED:<reason> to signals/planner.done.
      reports_to:
        - stats_auditor
        - swarm_auditor
        - editor
 
    stats_auditor:
      role: omp-stats-source-verifier
      task: |
        Verify every omp-stats claim in the quick-start against installed package source.
 
        Read:
        - plan/scope.md
        - ~/.bun/install/cache/@oh-my-pi/omp-stats@15.10.10@@@1/package.json
        - ~/.bun/install/cache/@oh-my-pi/omp-stats@15.10.10@@@1/README.md
        - ~/.bun/install/cache/@oh-my-pi/omp-stats@15.10.10@@@1/src/index.ts
 
        Write:
        - reports/omp-stats.md
        - signals/stats_auditor.done
 
        Acceptance:
        - Mark each claim as KEEP, FIX, or REMOVE.
        - Include exact source file paths for every FIX/REMOVE.
        - Do not infer commands that are not exposed by package.json/bin or src/index.ts help.
      waits_for:
        - planner
      reports_to:
        - editor
 
    swarm_auditor:
      role: swarm-yaml-source-verifier
      task: |
        Verify every swarm-extension claim and YAML field against installed package source.
 
        Read:
        - plan/scope.md
        - ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension/package.json
        - ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension/README.md
        - ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension/src/swarm/schema.ts
        - ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension/src/cli.ts
        - ~/.omp/plugins/node_modules/@oh-my-pi/swarm-extension/src/extension.ts
 
        Write:
        - reports/swarm-extension.md
        - signals/swarm_auditor.done
 
        Acceptance:
        - Confirm snake_case YAML fields: extra_context, reports_to, waits_for, target_count.
        - Confirm valid modes and required fields.
        - Confirm CLI/TUI command names.
        - Include exact source file paths for every finding.
      waits_for:
        - planner
      reports_to:
        - editor
 
    editor:
      role: idiot-proof-technical-editor
      task: |
        Produce the final wiki-ready markdown patch plan.
 
        Read:
        - plan/scope.md
        - reports/omp-stats.md
        - reports/swarm-extension.md
        - content/knowledge/skills/omp-plugins.md
 
        Write:
        - output/wiki-patch.md
        - signals/editor.done
 
        Acceptance:
        - Keep the page ultra-condensed.
        - Preserve only source-verified commands and paths.
        - Include one production-grade swarm YAML example.
        - Include sharp edges and decision table.
        - Do not add unverified package behavior.
      waits_for:
        - stats_auditor
        - swarm_auditor
      reports_to:
        - qa
 
    qa:
      role: final-docs-quality-gate
      task: |
        Review output/wiki-patch.md for correctness, clarity, and copy/paste safety.
 
        Read:
        - output/wiki-patch.md
        - reports/omp-stats.md
        - reports/swarm-extension.md
 
        Write:
        - output/final-approved.md
        - signals/qa.done
 
        Acceptance:
        - Reject vague tasks, missing output paths, hidden assumptions, and unverified commands.
        - Ensure every agent task has Read, Write, and Acceptance blocks.
        - If approved, copy output/wiki-patch.md to output/final-approved.md.
        - If rejected, write REJECTED:<reason> to signals/qa.done.
      waits_for:
        - editor

YAML field cheat sheet

Field	Required	Meaning
`swarm.name`	✅	State dir becomes `.swarm_<name>/`
`swarm.workspace`	✅	Shared filesystem for agents and artifacts
`swarm.mode`	❌	`sequential` default; also `parallel`, `pipeline`
`swarm.target_count`	❌	Iterations for `pipeline` mode
`swarm.model`	❌	Default model for all agents
`agents.<id>.role`	✅	Specialist identity/system role
`agents.<id>.task`	✅	Complete instructions; include exact paths + outputs
`reports_to`	❌	Downstream agents depend on this one
`waits_for`	❌	This agent waits for named upstream agents
`agents.<id>.model`	❌	Per-agent model override

🧩 Best-practice recipes

✅ Use `omp-stats` for local telemetry

omp-stats --json > usage.snapshot.json

Then inspect:

highest-cost model
error-rate spikes
poor cache rate
slow TTFT
expensive folders/projects

✅ Use `swarm-extension` for repeatable work, not vibes

Good swarm tasks always specify:

📥 exact input files/URLs
📤 exact output files
🚫 non-goals
✅ acceptance criteria
🧯 failure behavior, e.g. “write SKIP:<reason> instead of guessing”

✅ Use file handoffs between swarm agents

reports/security.md      # detailed specialist report
signals/security.done    # one-line completion flag
output/final-plan.md     # final synthesized deliverable

Do not rely on agent memory across iterations. Each agent starts fresh.

🚨 Sharp edges

omp-stats is global-session telemetry; it is not scoped to one Discord thread.
swarm-extension agents communicate through workspace files, not magic hidden memory.
pipeline mode repeats the whole graph; make output filenames unique or tracking-aware.
Cycles in waits_for / reports_to are rejected before execution.
Background swarms need real log files; redirect stdout/stderr intentionally.
Keep dashboards local unless explicitly protected behind auth.

🏁 Decision table

Goal	Use
“How much did my local omp usage cost?”	`omp-stats --sync` or `omp-stats --json`
“Show a local chart dashboard.”	`omp-stats --port 3847`
“Run 3 reviewers then 1 synthesizer.”	`swarm-extension` fan-in DAG
“Run one pipeline 50 times and accumulate output.”	`swarm-extension` `mode: pipeline` + `target_count`
“Show Amy/Ompcord per-thread usage.”	Adapt `omp-stats` parser; do not use its global DB directly
“Let Discord users kick off controlled swarms.”	Wrap `omp-swarm` behind Ompcord allow-lists + explicit approval

📌 Source-verified files

.omp/plugins/package.json
.omp/plugins/omp-plugins.lock.json
.bun/install/cache/@oh-my-pi/omp-stats@15.10.10@@@1/README.md
.bun/install/cache/@oh-my-pi/omp-stats@15.10.10@@@1/src/index.ts
.omp/plugins/node_modules/@oh-my-pi/swarm-extension/README.md
.omp/plugins/node_modules/@oh-my-pi/swarm-extension/src/cli.ts
.omp/plugins/node_modules/@oh-my-pi/swarm-extension/src/extension.ts

OMP Plugins

🧩 Plugins

🧠 Mental model

⚡ Install / verify

📊 `omp-stats` — local usage observability

What it does

Fast commands

Operator rules

🐝 `swarm-extension` — YAML multi-agent orchestration

What it does

Fast commands

Production-grade YAML template

YAML field cheat sheet

🧩 Best-practice recipes

✅ Use `omp-stats` for local telemetry

✅ Use `swarm-extension` for repeatable work, not vibes

✅ Use file handoffs between swarm agents

🚨 Sharp edges

🏁 Decision table

📌 Source-verified files

Ask Docs

OMP Plugins

🧩 Plugins

🧠 Mental model

⚡ Install / verify

📊 omp-stats — local usage observability

What it does

Fast commands

Operator rules

🐝 swarm-extension — YAML multi-agent orchestration

What it does

Fast commands

Production-grade YAML template

YAML field cheat sheet

🧩 Best-practice recipes

✅ Use omp-stats for local telemetry

✅ Use swarm-extension for repeatable work, not vibes

✅ Use file handoffs between swarm agents

🚨 Sharp edges

🏁 Decision table

📌 Source-verified files

📊 `omp-stats` — local usage observability

🐝 `swarm-extension` — YAML multi-agent orchestration

✅ Use `omp-stats` for local telemetry

✅ Use `swarm-extension` for repeatable work, not vibes