npm package: @kimuson/super-agent
Description: Unified orchestration layer for AI agent SDKs with intelligent fallback and sub-agent patterns
Latest version: 0.0.1

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

```bash
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

```bash
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

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

```bash
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`):

```json
{
  "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`):

```markdown
---
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`):

```json
{
  "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:

```bash
# "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:

```bash
npx -y @kimuson/super-agent server stop
```

## Development

See [docs/dev.md](./docs/dev.md) for development guide.

## License

MIT