@kimuson/super-agent

A unified CLI to invoke multiple AI coding agents (Claude Code, Codex) with priority-based provider fallback.

Why super-agent?

Modern AI-assisted development often involves multiple agent providers — Claude Code for autonomous task execution, Codex for precise implementation, and so on. In practice, most developers use subscription plans rather than pay-per-use pricing, which means rate limits are a constant reality.

super-agent solves three problems that arise in this multi-provider world:

1. Context separation: Define specialized agents (e.g., engineer, reviewer, architect) with their own system prompts. The orchestrator only needs to specify an agent name — the agent's dedicated instructions are loaded automatically, keeping each agent's context cleanly isolated.
2. Unified interface: Instead of learning each CLI separately, invoke any provider through a single agent-task command with pre-configured agent definitions.
3. Provider fallback: Define preferred providers in priority order per agent. When Claude Code hits a rate limit, automatically fall back to Codex — no manual switching required.

Quick Start

1. Setup

npx -y @kimuson/super-agent@latest setup

The interactive wizard creates ~/.super-agent/config.json and sets up your preferred providers.

2. List available agents

npx -y @kimuson/super-agent agent-list

Each agent is a pre-configured specialist. Specifying --agent-type loads an optimized system prompt and selects the best available provider automatically.

3. Run a task

# Foreground
npx -y @kimuson/super-agent agent-task --agent-type engineer "Implement user authentication"

# Background (returns session ID)
npx -y @kimuson/super-agent agent-task --agent-type engineer --background "Refactor the auth module"

# Retrieve background task output
npx -y @kimuson/super-agent agent-task-output <session-id>

4. Resume a session

npx -y @kimuson/super-agent agent-task-resume <session-id> "Now add tests for the changes"

Configuration

Config File

~/.super-agent/config.json (created by setup):

{
  "availableProviders": ["claude", "codex"],
  "defaultModel": { "provider": "claude", "model": "sonnet" },
  "agentDirs": ["~/.super-agent/agents"],
  "skillDirs": ["~/.claude/skills"],
  "sandboxOptions": { "enabled": true, "network": true }
}

Local overrides can be placed in config.local.json (same directory, gitignored).

Configuration priority: config.json < config.local.json < Environment variables (SA_*) < CLI args.

Agent Definition

Agent files follow the Claude Code agent format — if you already have agents defined for Claude Code, they work as-is with super-agent.

Place Markdown files in an agents directory (~/.super-agent/agents/<name>.md):

---
name: engineer
description: Implement code with strict type safety and TDD approach
models:
  - provider: claude
  - provider: codex
skills:
  - typescript
---

Your system prompt here...

The models field is a super-agent extension to the Claude Code format. It defines a list of { provider, model } pairs in priority order — the first available provider is used, and the rest serve as fallbacks.

| Field | Description | | ------------- | ------------------------------------------------------------- | | name | Agent identifier (used with --agent-type) | | description | Shown in agent-list output | | models | List of { provider, model? } in priority order for fallback | | skills | Skill names to auto-load (Claude Code compatible) | | Body | System prompt injected into the agent session |

A built-in general agent is always available as the default.

Skills

super-agent supports the Claude Code skills frontmatter field. Skills referenced in an agent definition are automatically loaded from the configured skillDirs.

If you already have skills defined for Claude Code or Codex, add their directories to skillDirs in your config (or configure via setup):

{
  "skillDirs": ["~/.claude/skills", "~/.codex/skills"]
}

Rate Limits and Provider Fallback

When an agent task fails due to rate limits, use provider-cooldown to temporarily disable the provider and retry:

# "claude is rate limited until 3:00 PM"
npx -y @kimuson/super-agent provider-cooldown claude --disabled-until "15:00"
npx -y @kimuson/super-agent agent-task --agent-type engineer "Fix the bug in auth.ts"

CLI Reference

Commands:
  setup                              Interactive configuration wizard
  agent-list                         List available agents
  agent-task <prompt>                Execute a task
  agent-task-resume <id> <prompt>    Resume a session
  agent-task-output <id>             Get background task output
  provider-cooldown <provider>       Temporarily disable a provider
  server                             Local server management
  show-context                       Display loaded configuration

Global Options:
  --sa-dir <path>                    SuperAgents directory (default: ~/.super-agent)
  --available-providers <providers>  Available providers (comma-separated)
  --default-model <model>            Default model (provider:model or provider)
  --agents-dir <paths>               Agent directories (comma-separated)
  --skills-dir <paths>               Skill directories (comma-separated)

Environment Variables:
  SA_DIR                 SuperAgents directory
  SA_AVAILABLE_PROVIDERS Available providers
  SA_DEFAULT_MODEL       Default model
  SA_AGENT_DIRS          Agent directories
  SA_SKILL_DIRS          Skill directories

Supported Providers

| Provider | ID | Status | | ------------ | -------- | --------- | | Claude Code | claude | Supported | | OpenAI Codex | codex | Supported |

Troubleshooting

If unexpected errors occur, the background local server may be running an outdated version. Restart it:

npx -y @kimuson/super-agent server stop

Development

See docs/dev.md for development guide.

License

MIT