oc-agent

A zero-dependency npx CLI for installing and managing OpenCode agent .md files.

Installation • Commands • Publishing Agents

npx oc-agent add https://github.com/owner/repo --agent my-agent

Features

• One-command install — clone a git repo and install agents into the right directory
• Zero dependencies — pure Node.js, no compiled native modules
• Project or global scope — install agents per-project or system-wide
• Manifest tracking — every install is recorded for reliable update and remove
• CI-friendly — -y flag skips all prompts for automated workflows

Installation

No install needed — run directly with npx:

npx oc-agent <command>

Or install globally:

npm install -g oc-agent

Commands

add

Install an agent from a git repo.

npx oc-agent add <git-url> [--agent <name>] [-g] [-y]

The repo must have an /agents folder containing .md files. The --agent flag is required when the repo contains more than one agent.

[!TIP] Supports https://, git@, ssh://, and file:// URLs.

# Single-agent repo (--agent optional)
npx oc-agent add https://github.com/owner/repo

# Multi-agent repo (--agent required)
npx oc-agent add https://github.com/owner/repo --agent coder

# Install globally
npx oc-agent add https://github.com/owner/repo --agent coder -g

# Non-interactive (CI)
npx oc-agent add https://github.com/owner/repo --agent coder -g -y

list

Show all installed agents and their source repo.

npx oc-agent list
npx oc-agent list -g   # global agents

remove

Uninstall an agent by name.

npx oc-agent remove coder
npx oc-agent remove coder -g

update

Re-pull and reinstall agents from their source repo.

npx oc-agent update           # update all
npx oc-agent update coder     # update one
npx oc-agent update -g        # update all global

Scope

| Scope | Path | |---|---| | Project (default) | ./.opencode/agents/ | | Global (-g) | ~/.config/opencode/agents/ |

How it works

1. Clones the repo into a temp directory
2. Looks for .md files inside the /agents subfolder
3. Copies the chosen file to the install destination
4. Records the install in a manifest for future update and remove

Installed agents are tracked in oc-agent-manifest.json alongside your agents, so update and remove always know where a file came from.

Options

| Flag | Description | |---|---| | --agent <name> | Select agent to install (required if repo has multiple) | | -g, --global | Install to ~/.config/opencode/agents/ instead of ./.opencode/agents/ | | -y, --yes | Skip confirmation prompts (CI-friendly) | | -h, --help | Show help message | | -v, --version | Show version |

Publishing Agents

Structure your repo like this:

my-agents/
  agents/
    coder.md
    reviewer.md
    planner.md
  README.md

Each .md file becomes an installable agent. Users install individual agents with --agent <filename-without-extension>.

Requirements

• Node.js 18+
• git available in PATH