# opc-agents

Small shell utility for toggling opencode **agents** between a curated "active" set and a full "parked" catalog. Keeps `~/.config/opencode/agents/` small and intentional while preserving the full agent library offline.

Companion to [`opc-skills`](https://gitea.taygun.net.tr/salvacybersec/opc-skills) — same UX, file-based unit (each agent is a single `<name>.md` file rather than a folder).

## Why

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

## Install

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

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

## Layout it expects

```
~/Documents/opencode-agents-parked/   # full catalog — untracked data dir
  <name>.md
  INDEX.json
  INDEX.md
~/.config/opencode/agents/            # only currently-enabled agents
  <name>.md
```

Override via env:
- `OPC_AGENTS_PARKED` — parked catalog root (default `~/Documents/opencode-agents-parked`)
- `OPC_AGENTS_ACTIVE` — active agents root  (default `~/.config/opencode/agents`)

## 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 |