opc-agents/README.md

opc-agents

Multi-target agent manager for opencode + Claude Code. Per-target parked sources (different formats), shared CLI surface. Companion to opc-skills.

Why

opencode injects every agent's frontmatter into the calling agent's tool registry. With 100+ agents the registry alone burns ~280K tokens of context before the user types a prompt. Park the ones you don't need this week.

opencode and Claude Code use different agent frontmatter formats (opencode: permission: { … }, claude: tools: Read, Glob, …), so opc-agents keeps a separate parked source per target.

Install

ln -s ~/Documents/opc-agents/bin/opc-agents ~/.local/bin/opc-agents

Ensure ~/.local/bin is on your PATH.

Layout it expects

~/Documents/personas/agents-opencode-archive/   # parked, opencode format
  <name>.md       (frontmatter: mode, permission, …)
  INDEX.json + INDEX.md (canonical index — also tracks claude side)

~/Documents/personas/agents-claude-archive/     # parked, claude format
  <name>.md       (frontmatter: tools: Read, Glob, …)

~/.config/opencode/agents/                      # active, opencode target
~/.claude/agents/                               # active, claude target

(~/Documents/opencode-agents-parked is symlinked to personas/agents-opencode-archive for backward compat.)

Override via env:

• OPC_AGENTS_PARKED — opencode parked source (default personas/agents-opencode-archive)
• OPC_AGENTS_CLAUDE_PARKED — claude parked source (default personas/agents-claude-archive)
• OPC_AGENTS_ACTIVE — opencode active dir (default ~/.config/opencode/agents)
• OPC_AGENTS_CLAUDE_ACTIVE — claude active dir (default ~/.claude/agents)
• OPC_AGENTS_TARGETS — comma-separated default targets (default opencode,claude)

Targets

enable, disable, and disable-all accept --target / -t (opencode, claude, both/all). Default is opencode,claude. An agent missing in a target's parked source is skipped with a clear message — there is no automatic format conversion.

Commands

Inspection

status	counts of active vs parked + primary/subagent breakdown
list {active|parked|all}	list agent names
categories / cats	prefix-based base-persona counts (PARKED)
variants / vars	suffix-based variant counts (PARKED) — eg. salva, iran

Single-agent operations

enable <name>	enable single agent (copy parked → active)
disable <name>	disable single agent (remove from active; keep parked)
disable-all [-y|--yes] [--keep-primary]	disable every active agent (asks for confirmation)

Bulk by axis

enable-category <prefix> / disable-category <prefix>	fzf multi-pick by base persona prefix (eg. frodo, marshal)
enable-variant <suffix> / disable-variant <suffix>	bulk by variant suffix (eg. salva, iran, russian-doctrine)
enable-domain <domain> / disable-domain <domain>	bulk by Domain: value in description (live scan)

Interactive / search

pick / disable-pick	fzf: pick category → multi-select
search [query] / disable-search	fzf fuzzy search across name + mode + domain + variant + description
reindex	rebuild INDEX.json / INDEX.md (extracts persona/variant/domain from frontmatter)

fzf is required for the interactive pickers; jq for the search variants; python3 for reindex.

Notes

• Each agent is a single <name>.md file with YAML frontmatter (typically description, mode, temperature, …).
• disable* commands never delete data — they remove the active copy and keep (or restore) the parked copy. Re-enable with opc-agents enable <name>.
• --keep-primary on disable-all skips agents with mode: primary (those are loaded as top-level personas in opencode).
• Common agent prefixes seen in personas: frodo-, marshal-, sentinel-, bastion-, neo-, oracle-, warden-, polyglot-, etc.

Differences from opc-skills

	opc-skills	opc-agents
Unit	directory containing SKILL.md	single <name>.md file
Frontmatter fields used	name, description	description, mode
Shared refs sync	yes (_platform-mapping.md)	n/a
disable-all flags	-y	-y, --keep-primary
Status breakdown	active/parked	+ primary/subagent counts