The Problem

Developers building AI‑driven coding assistants need a reusable set of “agent” components (prompt templates, background tasks, storage back‑ends) that can be swapped between model providers (Codex, OpenCode, Claude, etc.). Maintaining those pieces across several heterogeneous codebases quickly becomes a coordination nightmare, especially when each piece has its own build, test, and deployment pipeline.

What This Does

oh‑my‑openagent is a portfolio of seven self‑contained projects that together form a modular “coding‑agent” ecosystem:

  • packages/agents-md-core – core markdown‑based agent runtime (src/index.ts). Supplies the generic prompt handling, skill registration, and command dispatch logic.
  • packages/ast-grep-mcp – a command‑line front‑end (src/cli.ts) that drives the AST‑grep‑based “multi‑code‑path” (MCP) tool, exposing a run() entry in src/index.ts.
  • packages/boulder-state – a lightweight state store (src/storage/index.ts) with a public API (src/index.ts) used by other agents to persist session data.
  • packages/claude-code-compat-core – compatibility shims for Claude‑based back‑ends (not listed as an entry point but part of the same mono‑repo).
  • .agents & .opencode – markdown‑driven skill definitions (e.g., codex-qa, opencode-qa) and associated shell/JS scripts that the core runtime loads at startup.
  • script/ & bin/ – helper utilities for repository maintenance (e.g., publishing, dead‑code removal).

Across the portfolio the same TypeScript tooling, npm scripts, and Docker build environment are reused, giving each project a familiar developer experience while allowing them to be versioned and released independently.

How It Is Wired

Execution always begins at one of the four declared entry points:

  1. packages/agents-md-core/src/index.ts – exports createAgent() and registers skills from the .agents folder. The module reads agents/skills/*.md files, parses their SKILL.md metadata, and wires the associated scripts (e.g., agents/skills/codex-qa/scripts/*).
  2. packages/ast-grep-mcp/src/cli.ts – parses CLI flags, imports the default export from packages/ast-grep-mcp/src/index.ts, and calls its run() function. run() internally loads the core agent (agents-md-core) to obtain prompt templates, then spawns the AST‑grep process and streams results back to the terminal.
  3. packages/boulder-state/src/index.ts – provides BoulderState class with get(), set(), and delete() methods. The implementation delegates to src/storage/index.ts, which currently uses a file‑system JSON store. All other packages import BoulderState via the package entry point, making it the single source of persistence.
  4. packages/ast-grep-mcp/src/index.ts – re‑exports run() for the CLI and also exposes a programmatic API used by other agents (e.g., codex-qa scripts) to perform code‑pattern searches.

The core runtime (agents-md-core) is the hub: every skill script ultimately calls agent.execute(command, payload), which lives in src/index.ts. That function looks up the command name in the skill registry (populated from .agents/skills/*/SKILL.md) and invokes the corresponding script file via a child process. Side‑effects (state writes, network calls) are funneled through BoulderState or through explicit HTTP clients coded in the individual scripts.

No circular dependencies are present in the static call graph; the only directed edges are:

CLI → ast-grep-mcp/index → agents-md-core/index → skill scripts → (optional) boulder-state

Thus, a change to a skill script touches only its own folder and the core runtime, limiting blast radius.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/oh-my-openagent
cd oh-my-openagent

# Install all npm workspaces
npm ci   # respects the root package-lock.json

# Build TypeScript packages (workspace aware)
npm run build   # defined in root package.json, runs tsc for each package
  • Configuration – the repository ships an .env.example describing required variables (e.g., API keys for model providers). Copy it to .env before running agents that contact external services.
  • Running a skill – invoke the core agent with a skill name, for example:
node -r ts-node/register packages/agents-md-core/src/index.ts codex-qa --input "Explain this function"
  • Running the AST‑grep CLI – use the dedicated entry point:
node packages/ast-grep-mcp/src/cli.js --pattern "TODO"

If a required script or environment variable is missing, the CLI will emit a clear error and exit with code 1.

Real‑World Use

A CI pipeline for a large monorepo can add oh‑my‑openagent as a development dependency. During a PR check, a workflow runs:

npm ci && npm run build && node packages/agents-md-core/src/index.ts codex-qa --input "$(git diff --cached)"

The agent reads the diff, uses the codex-qa skill to generate a review comment via the configured model, and posts the result back to GitHub via a small helper script in agents/skills/github-triage/scripts/gh_fetch.py.

Code Health & Issues

  • High – Pin third‑party GitHub Actions to a commit SHA – .github/workflows/* uses tags (oven-sh/setup-bun@v2, etc.). Replace each with a 40‑char SHA to prevent supply‑chain drift.
  • High – Remove continue-on-error from correctness steps – line 269 in .github/workflows/ci.yml masks test failures. Delete or move the step to a non‑required job.
  • High – Push to default branch directly – .github/workflows/ci.yml performs a git push. Switch to a bot branch and open a PR.
  • Medium – Enable Dependabot or Renovate – 60 manifests lack an update bot. Add .github/dependabot.yml.
  • Medium – Pin container base image by digest – .devcontainer/Dockerfile uses a mutable tag. Use @sha256:<digest>.
  • Medium – Add dependency‑vulnerability scan – No scan step in CI. Add dependency-review-action or osv-scanner.
  • Medium – Move large binaries to Git LFS – omo-logo.png (8.4 MiB) and other assets exceed 5 MiB. Track them with LFS or external storage.
  • Medium – Set persist-credentials: false on checkout – .github/workflows/ci.yml keeps the token after checkout. Add the flag and supply an explicit token only when needed.
  • Medium – Review postinstall script – package.json contains a postinstall that fetches binaries. Disable scripts in CI (npm ci --ignore-scripts) or move work to an explicit build step.
  • Low – Define timeout-minutes on workflow jobs – .github/workflows/publish.yml lacks timeouts; add reasonable limits.

The repo includes tests, a CI pipeline, Docker support, a license, and a lockfile, indicating solid baseline hygiene.

The Bottom Line

oh‑my‑openagent provides a well‑structured, multi‑package toolkit for building and running AI‑assisted coding agents, with clear separation between core runtime, CLI front‑ends, and state storage. The codebase is healthy overall but requires tightening of CI security (action pinning, credential handling) and dependency management before it can be trusted in production environments. It is best suited for teams that need a plug‑and‑play agent framework and are comfortable managing a mono‑repo of several interrelated packages.