agent-supagents

supagents

Compile a single AI supagent into multiple AI subagents.

Supagents is a small Python CLI that compiles a single markdown file into target-specific subagent files for Claude Code, Gemini CLI, GitHub Copilot, Cursor, OpenCode, and Kilo Code. You write the agent's persona once and ship it to every agent CLI you use.

Why

Every agent CLI has its own subagent format. The persona is the same ("You are a code-investigation expert..."), but each one wants a different YAML frontmatter shape and a different output directory. Hand-syncing every file every time you tweak a prompt is miserable.

Supagents takes the opposite approach from format-conversion tools: it makes you write each target's frontmatter verbatim in named blocks, and then it does the boring parts — splitting the body, copying shared keys, writing files atomically, and cleaning up stale outputs.

   one source                                 many outputs
   ─────────                                  ────────────
                                              ~/.claude/agents/code_investigator.md
                                              ~/.gemini/agents/code_investigator.md
~/.agents/supagents/code_investigator.md  →   ~/.copilot/agents/code_investigator.agent.md
                                              ~/.cursor/agents/code_investigator.md
                                              ~/.config/opencode/agents/code_investigator.md
                                              ~/.config/kilo/agents/code_investigator.md

The diagram shows the full fan-out. Declare any subset of target blocks in your source and supagents emits just those — the example below picks three.

Install

uv tool install supagents
# or:
pipx install supagents
# or, from this repo:
uv tool install --from /path/to/supagents supagents

Requires Python 3.12+.

Install as a plugin or extension

The same repo doubles as a Claude Code plugin, a Gemini CLI extension, and a GitHub Copilot plugin — install it through your agent CLI and it pulls in the bundled use-agent-supagents Agent Skill. Your agent learns the source format and CLI semantics up front, so you don't have to paste docs into prompts.

Tool	Manifest in the repo	What it installs
Claude Code	.claude-plugin/plugin.json (+ marketplace.json)	Plugin + bundled marketplace.
Gemini CLI	gemini-extension.json	Gemini CLI extension.
GitHub Copilot	plugin.json	Copilot plugin manifest.

These manifests register the Skill — they don't install the supagents CLI binary. Install the CLI separately (above) so supagents build lives on $PATH.

Quick start

Scaffold a new source with supagents init <name> (writes a template with all default target blocks), or drop one yourself at ~/.agents/supagents/code_investigator.md. The example below declares three blocks to keep things short — add CURSOR:, OPENCODE:, or KILO: blocks to emit those targets too:

---
name: code_investigator
description: Use to explore unfamiliar codebases — trace symbols, map data flow across modules, and explain how a feature is implemented.

CLAUDE:
  model: sonnet
  tools: Read, Grep, Glob, Bash

GEMINI:
  kind: local
  tools: ["*"]
  mcp_servers:
    context7:
      command: npx
      args: ["-y", "@upstash/context7-mcp@latest"]

COPILOT:
  target: vscode
  model: ["gpt-5", "gpt-4.1"]
  APPEND_BODY: |

    ## Copilot-specific
    Reference tools inline with `#tool:<name>`.
---

# Code Investigator Agent

You are the specialized code investigation agent. Help the user explore unfamiliar codebases: trace symbols, map data flow across modules, and explain how features are implemented.

Then build:

supagents build

You'll get one file per declared target — three in this example: