agents

# agents

**The package manager and runtime for AI coding agents.**

Install versions. Install skills. Run any agent through one interface. Build pipelines across Claude, Codex, Gemini, Cursor, OpenCode, and more.

```bash
npm install -g @swarmify/agents-cli
```

Also available as `ag` -- all commands work with both `agents` and `ag`.

---

## Run any agent. Same interface.

```bash
agents exec claude "Find all auth vulnerabilities in src/"
agents exec codex "Fix the issues Claude found"
agents exec gemini "Write tests for the fixed code"
```

Each agent resolves to the project-pinned version, with the right skills, MCP servers, and permissions already synced. No setup between steps -- just run.

`agents exec` also passes through environment overrides to the spawned CLI, so Claude can target any Anthropic-compatible endpoint:

```bash
agents exec claude "Reply with exactly: agents-qwen route ok" \
  --mode full \
  --model qwen3.6:35b \
  --env ANTHROPIC_BASE_URL=https://ollama.427yosemite.com \
  --env ANTHROPIC_AUTH_TOKEN="$(security find-generic-password -a "$USER" -s yosemite-ollama-auth-token -w)" \
  --env ANTHROPIC_MODEL=qwen3.6:35b \
  --env ANTHROPIC_SMALL_FAST_MODEL=qwen3.6:35b
```

This makes agent pipelines possible. Chain agents by strength, swap one for another, script them in CI -- the interface stays the same:

```bash
# Friday night code review
agents exec claude "Review all PRs merged this week, summarize risks" \
  | agents exec codex "Write regression tests for the top 3 risks"

# Same pipeline, different project -- different agent versions, same commands
cd ../other-project
agents exec claude "Review all PRs merged this week, summarize risks"
# ^ resolves to claude@2.0.0 here instead of claude@2.1.89
```

Supports plan (read-only) and edit modes, effort levels that map to the right model per agent, and JSON output for scripting.

---

## Non-interactive usage

Other coding agents usually run in non-TTY shells. `agents` now supports that mode directly:

```bash
agents add codex@latest --yes
agents use claude@2.1.79 --yes
agents commands add --names review-pr,debug --agents codex@0.113.0
agents skills add --names agents-cli --agents claude@default
agents install ./team-agent-pack --agents codex@0.113.0
agents mcp add postgres --agents claude@2.1.79 -- npx -y @modelcontextprotocol/server-postgres
agents mcp register postgres
agents sessions view <session-id>
agents routines view <job-name>
```

Rules for automation:

- Pass explicit names or IDs instead of relying on pickers.
- Use `--yes` when a command would otherwise ask for default sync or confirmation choices.
- Use `--names` with `commands`, `skills`, `hooks`, `rules`, and `permissions` to install from central storage without a checkbox prompt.
- Use `agent@version` or `agent@default` with `--agents` when you need an exact managed version.
- Long `view` commands print directly in non-interactive shells instead of opening `less`.

If a command still needs a human-only picker, it now exits with a plain-text hint that shows the matching non-interactive form.

---

## Search sessions fast

Interactive terminals now get a live-search picker for sessions:

```bash
agents sessions view
agents sessions --agent codex
agents sessions --project agents-cli
agents sessions view --agent gemini "session discovery"
```

What you can type into the picker:

- Session ID or short ID
- Prompt text / topic text
- Project name
- Account email
- Agent name or version

The shared `Agent` column also shows the resolved agent version when it is known, so filtered lists read like `claude@2.1.110`, `codex@0.113.0`, `gemini@0.29.5`, and `opencode@1.2.6`.

Use `agents sessions view <id>` in non-interactive shells when you already know the session you want.

---

## Pin agent versions per project

```bash
agents add claude@2.0.0             # Install specific version
agents use claude@2.0.0 -p          # Pin to this project
```

Like `.nvmrc` for Node -- different projects use different agent versions. A shim system reads `.agents-version` and routes to the right binary automatically. No other tool does this for AI agents.

When you switch versions, configs are backed up and resources are re-synced. Each version gets its own isolated home directory with the right skills, commands, and permissions already in place.

---

## Install skills, MCP servers, and commands once -- every agent gets them

### Skills

Skills are reusable knowledge packs -- rules, patterns, and expertise that make your agents better at specific tasks. Install once, available everywhere.

```bash
agents skills add gh:yourname/python-expert     # Install from GitHub
agents skills add ./my-skills                    # Install from local path
agents skills list                               # See what's installed
agents skills view python-expert                 # View skill details and rules
```

A skill is a directory with a `SKILL.md` and optional rule files:

```
python-expert/
  SKILL.md       

... (truncated)