OmAgents

English | 简体中文 | 日本語 | 한국어

An OpenCode and Codex CLI plugin that bundles agent skills, MCP servers, parallel execution, and superpowers into a single install.

---

Skip This README

Paste this into your agent:

Read this and install omagents: https://raw.githubusercontent.com/omagents/omagents/main/README.md

---

Installation

TL;DR

For Humans

Prerequisites:

• OpenCode installed and running
• Python 3.11+ installed and on PATH (required for deep-research, markitdown-converter, playwright-web-scraping, and loop engine)

1. Open your OpenCode config:

open -e ~/.config/opencode/opencode.json

2. Add @omagents/omagents to the plugin array:

{
  "plugin": [
    "@omagents/omagents"
  ]
}

3. Restart OpenCode.

Or, use the CLI setup command:

npx @omagents/omagents opencode

That’s it. At session start OmAgents will automatically:

• Install superpowers (bundled, no separate install needed)
• Register all skills (OmAgents + Superpowers)
• Register all MCP servers (agentmemory, codegraph, context7, websearch, github/grep_app)
• Enable parallel execution (background agents with /ps and cancel_task)
• Set up Python venv at ~/.venvs/omagents (installs jinja2 for report templates)
• Check Python prerequisite (warns with install instructions if Python is missing)

For LLM Agents

If you’re an AI agent helping a user install OmAgents, follow these steps:

# 1. Read the user's current OpenCode config
cat ~/.config/opencode/opencode.json

# 2. Add "@omagents/omagents" to the plugin array
#    Use jq if available, otherwise edit manually

# 3. Verify the config is valid JSON after editing

# 4. Tell the user to restart OpenCode

The plugin handles everything else automatically - no manual MCP configuration, no skill installation, no venv setup.

Optional: API Keys

Some remote MCP servers accept optional API keys for higher rate limits:

# ~/.zshrc or ~/.bashrc
export EXA_API_KEY="your-exa-key"
export CONTEXT7_API_KEY="your-context7-key"
export GITHUB_TOKEN="your-github-token"

Setting GITHUB_TOKEN enables the full GitHub Copilot MCP (issues, PRs, repos, code search). Without it, OmAgents falls back to Vercel’s mcp.grep.app for public code search only.

Combine with Other Plugins

OmAgents’ hook merging mechanism ensures no conflicts with additional plugins:

{
  "plugin": [
    "@omagents/omagents",
    "@devcxl/opencode-spec"
  ]
}

Codex CLI

Prerequisite: Python 3.11+ installed and on PATH.

npx @omagents/omagents codex

This installs the OmAgents plugin into ~/.codex/plugins/cache/omagents/omagents/local/ and enables it in ~/.codex/config.toml. At session start, the plugin auto-discovers bundled skills, MCP servers, and sets up the Python venv via SessionStart hooks.

The OpenCode-only parallel execution engine is not available; use Codex’s native subagent tools for parallel dispatch.

---

Highlights

---

Loop Engineering

OmAgents pioneers loop engineering for AI agent skills. Instead of one-shot prompts that say “scan everything and fix it,” loop-based skills use a durable task queue that processes items one at a time with verification.

How It Works

Phase 1: Build Task Queue          Phase 2: Execute Loop           Phase 3: Report
┌─────────────────────┐    ┌──────────────────────────┐    ┌─────────────────┐
│ Scan codebase       │    │ loop_engine.py next      │    │ loop_engine.py  │
│ Build task list     │───>│   -> get next task       │───>│   summary       │
│ loop_engine.py init │    │   -> execute + verify    │    │ Show results    │
└─────────────────────┘    │   -> complete or fail    │    └─────────────────┘
                           │   -> repeat until null   │
                           └──────────────────────────┘

State persists in .omagents/loops//tasks.json – if the agent’s context is cleared mid-task, it can resume exactly where it left off.

Retry logic: Failed tasks retry up to 3 times before being marked blocked.

Compaction safe: The experimental.session.compacting hook injects loop engine state into the compaction prompt, so the agent knows to resume after context clearing.

Skills Using Loop Engineering

Loop Engine API

loop_engine.py init  ''   # Initialize task queue
loop_engine.py next                    # Get next pending task
loop_engine.py complete   [result] # Mark task complete
loop_engine.py fail   [error]      # Mark task failed (retries 3x)
loop_engine.py status                  # Print stats
loop_engine.py summary                 # Full task list with icons
loop_engine.py reset                   # Clear queue
loop_engine.py add  ''      # Add task to existing queue

---

What’s Included

Skills

MCP Servers

Parallel Execution

• Background task dispatch via OpenCode’s native task(background: true)
• Job Board tracking with automatic result injection
• Persistence: Job Board survives restart (saved to job-board.json)
• Session isolation: Each session only sees its own jobs (no cross-session leak)
• Compaction safe: Loop engine and Job Board state preserved across context compaction
• /ps command to check running tasks
• cancel_task tool to cancel background tasks
• parallel_status tool for programmatic status checks

---

Architecture

OmAgents is designed as a layered system:

┌─────────────────────────────────────────────────┐
│  User Choice Layer (not bundled, install separately)  │
│  OpenSpec · gstack · custom workflows · none     │
├─────────────────────────────────────────────────┤
│  Process Skills Layer (bundled: superpowers)      │
│  Brainstorming · TDD · Debugging · Plans ·       │
│  Code Review · Git Worktrees · Verification      │
├─────────────────────────────────────────────────┤
│  Infrastructure Layer (bundled: OmAgents)         │
│  MCP servers · Parallel execution ·              │
│  Deep research · Python tooling · venv            │
├─────────────────────────────────────────────────┤
│  OpenCode runtime                                │
└─────────────────────────────────────────────────┘

OmAgents is the infrastructure layer. It provides the tools and capabilities agents need: MCP servers for external data, parallel execution for background tasks, research workflows, and Python environment management.

Superpowers is the process skills layer. It provides reusable development workflows: brainstorming before implementation, test-driven development, systematic debugging, plan writing and execution, code review, and git worktree management.

The user choice layer is not bundled. Development methodology is a choice - spec-driven development (OpenSpec), team-based engineering workflow (gstack), or no methodology at all. OmAgents stays neutral so users can pick what fits their project.

---

Uninstallation

1. Remove the plugin from your OpenCode config:

# Using jq
jq '.plugin = [.plugin[] | select(. != "@omagents/omagents")]' \
    ~/.config/opencode/opencode.json > /tmp/oc.json && \
    mv /tmp/oc.json ~/.config/opencode/opencode.json

2. Remove the Python venv (optional):

rm -rf ~/.venvs/omagents

3. Restart OpenCode.

---

Development

Project structure:

omagents/
├── index.js                  # Unified entry (OpenCode plugin export + Codex CLI installer)
├── .opencode/plugins/
│   ├── index.js              # OpenCode plugin (merges superpowers + omagents hooks)
│   └── parallel.js           # Parallel execution engine
├── .codex/plugins/
│   └── install.js            # Codex installer (run via npx @omagents/omagents)
├── hooks/
│   └── setup-venv.sh         # Shared venv setup hook (OpenCode + Codex)
├── skills/                   # Bundled skills (18 OmAgents + 14 Superpowers)
│   ├── _shared/scripts/      # Shared scripts (loop_engine.py)
│   ├── deep-research/        # Research workflow with gap detection
│   └── ...                   # 16 more skills
├── mcp-servers/
│   └── base.json             # MCP server definitions (single source of truth)
├── tests/                    # Node.js built-in test runner
├── AGENTS.md                 # AI agent context file
├── package.json              # Includes superpowers as dependency
└── README.md

Testing

# Run all tests
npm test

# Check formatting
npm run format:check

# Format code
npm run format

Publishing

OmAgents uses OIDC Trusted Publishing - no npm token required.

# Bump version
npm version patch   # 0.1.0 -> 0.1.1

# Push tag (triggers GitHub Actions auto-publish)
git push && git push --tags

Configure Trusted Publisher at npmjs.com -> Settings -> Trusted Publisher.

---

License

MIT - see LICENSE.