v1.22.52see what's new →

Install

Install once, point the CLI at the agents you already pay for, and run anything from one prompt.

Quickstart: zero to a running agent

Four commands take you from nothing to a first agent run. Copy the block, then read the annotated steps below it.

# 1. install the CLI — single binary at ~/.agents/bin/agents
curl -fsSL agi-cli.sh | sh

# 2. bootstrap the machine — clones ~/.agents/.system and imports installed CLIs
agents setup

# 3. install a harness — sign-in happens on its first run
agents add claude@latest

# 4. first run, read-only so nothing touches disk (opens Claude's native login)
agents run claude "summarize the last 10 commits" --mode plan

Step 2 is not optional. agents setup is the one-time bootstrap that clones the shared system layer into ~/.agents/.system/ and imports any agent CLIs already on the machine. Skip it and later agents commands run against a half-set-up home. Full walkthrough of what it does and where every file lands is on first run.

Step 3 installs that agent's CLI; the first agents run for it opens the provider's native sign-in, so you do it once per agent you want to drive. Step 4's --mode plan keeps the run read-only, so you watch the agent reason with no writes and no shell side-effects. A successful first run prints the resolved version, streams the plan, and exits clean:

> agents run claude "summarize the last 10 commits" --mode plan
[email protected] · mode=plan · profile=claude
  reading git log (last 10 commits)...
  1. feat(auth): rotate refresh tokens on reuse
  ... 9 more ...
done · 0 files changed · session saved (agents sessions to replay)

1. Install

curl -fsSL agi-cli.sh | sh

The installer drops a single binary at ~/.agents/bin/agents and symlinks ag alongside it. Both work everywhere.

2. Add a model profile (hosted models)

Native harnesses like claude, codex, and grok install with agents add above and sign in on first run. A profile is the other path: a saved (provider, model, key) triple that runs a hosted model (Kimi, DeepSeek, Qwen) through the Claude Code runtime. Match a built-in preset by name, or point Anthropic-direct at your own API key. The key lives in macOS Keychain — never on disk.

agents profiles presets           # list built-in presets (OpenRouter + direct providers)
agents profiles add kimi          # Kimi K2.5 via OpenRouter (preset)
agents profiles add deepseek      # DeepSeek Chat V3 via OpenRouter (preset)
agents profiles add anthropic     # Claude via your own Anthropic API key
agents profiles list

3. Run an agent

agents run claude "refactor the queue worker"
agents run kimi   "draft a release note for v1.20"
agents run codex  "fix the failing test in src/payments/"

Same flags work everywhere. --rotate picks the least-used account, --quiet suppresses the preamble, --stream emits stream-json for piping.

4. Pin per project

Drop an agents.yaml at the repo root. Every agents call inside the tree honors it — like .nvmrc, but for AI.

# agents.yaml
agents:
  claude: "2.1.113"
  codex:  "0.116.0"

5. Make the config travel

Your skills, commands, hooks, rules, and MCP servers live in ~/.agents/. Push it to a git host once and pull on every machine.

agents repo init
agents repo push                # mirrors ~/.agents to your remote
agents repo pull                # on the next machine

Per-project rules go in ./.agents/ and get merged in at spawn time. See config layers for how the four levels — system, you, team, project — combine.

To reach those other machines directly — run agents on them, sync sessions, push secrets — register your fleet and target any of it with one flag. agents devices sync ingests your tailnet; agents secrets push carries credential bundles across. Go multi-machine →

Next