initial: opc-agents standalone tool

2026-04-30 21:52:24 +03:00
commit ba0b744656
3 changed files with 505 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,69 @@
+# 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
+
+| | |
+|---|---|
+| `status`                                       | counts of active vs parked + mode breakdown |
+| `list {active\|parked\|all}`                    | list agent names |
+| `categories` / `cats`                          | prefix-based category counts (PARKED) |
+| `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) |
+| `enable-category <prefix>`                     | fzf multi-pick within a prefix, then enable |
+| `disable-category <prefix>`                    | fzf multi-pick of ACTIVE agents with prefix, then disable |
+| `pick`                                         | fzf: choose category → multi-select → enable |
+| `disable-pick`                                 | fzf: choose ACTIVE category → multi-select → disable |
+| `search [query]`                               | fzf fuzzy search across name+description (enable) |
+| `disable-search [query]`                       | fzf fuzzy search ACTIVE agents only (disable) |
+| `reindex`                                      | rebuild `INDEX.json` / `INDEX.md` |
+
+`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 |