Skip to content

Manage Subagents

Aikito keeps each canonical subagent definition in subagents/<name>.md. Its JSON-valued frontmatter contains the description, target Agents, and platform options. The Markdown body contains instructions. Aikito renders these definitions into formats supported by each Agent.

Preview

Review the canonical definition and preview the rendering plan:

aikito sync subagents --dry-run
aikito show subagents

The plan identifies creates, updates, unsupported capabilities, or unmanaged target conflicts.

Apply and Verify

aikito sync subagents
aikito show subagents
aikito show subagent verifier
aikito edit subagent verifier

Managed files are updated from the canonical definition. An existing file without an Aikito marker is treated as unmanaged and will not be overwritten by default. To overwrite a specific unmanaged target after review, specify its target key:

aikito sync subagents --force <agent>/<subagent>

Passing --force with a specific <agent>/<subagent> authorizes overwriting only that target, preventing accidental overwrite of other conflicting files.

Shared agent configuration files (such as DeepSeek Harness cordis.patch.yml) merge multiple subagent definitions in memory and perform a single write, preserving other unmanaged sections and custom tool definitions.

Example aikito show subagents output from a configured workspace:

┌───────────┬───────┬─────────────┬─────────────────┬──────────┬────────────────────┬──────────────────┐
│ Subagent  │ Codex │ Claude Code │ Antigravity CLI │ OpenCode │ GitHub Copilot CLI │ DeepSeek Harness │
├───────────┼───────┼─────────────┼─────────────────┼──────────┼────────────────────┼──────────────────┤
│ verifier  │ ✓     │ ✓           │ ✓               │ ✓        │ ✓                  │ ✓                │
└───────────┴───────┴─────────────┴─────────────────┴──────────┴────────────────────┴──────────────────┘

✓ means the rendered definition is synchronized; – means that Agent does not participate in subagent synchronization.

  • Antigravity CLI: Definitions are rendered to ~/.gemini/config/agents/<name>/agent.md, supporting model and tools.
  • OpenCode: Definitions are rendered to ~/.config/opencode/agents/<name>.md with mode: subagent; set the native model ID through the opencode frontmatter object’s model field.
  • Pi: Participates only when its optional extension entry point exists at ~/.pi/agent/extensions/subagent/index.ts. Definitions are rendered to ~/.pi/agent/agents/<name>.md. Pi-specific configuration supports model and tools; without the extension, Pi remains skipped and Aikito writes nothing.

Add or Import Subagents

Create a new canonical subagent skeleton:

aikito add subagent reviewer --description "Performs automated code reviews"

Import from an existing markdown prompt or Copilot agent file:

aikito add subagent --from ./prompts/reviewer.md --sync
aikito add subagent --from .github/agents/reviewer.agent.md --force
  • --from <path>: Points to a local markdown prompt file (e.g. .md, .agent.md) or directory containing instructions. Name and description are inferred from frontmatter or file stem when omitted.
  • --sync: Immediately renders and synchronizes the subagent into configured agent runtimes.
  • --force: Atomically replaces an existing subagent definition in subagents/<name>.md including its frontmatter.

To unregister and remove a subagent from the workspace, run aikito rm subagent <name>. Add --sync to immediately prune the rendered subagent definition from all configured Agent runtimes:

aikito rm subagent reviewer --sync

If a definition was removed without --sync, aikito status may report a managed orphan. Run aikito sync subagents --prune to clean up orphaned definitions across agents. Pruning strictly deletes only definitions containing an Aikito ownership marker; pre-existing unmanaged definitions are never deleted.

See Architecture for Agent capability boundaries and Safety model before forcing any target.