The Complete Guide to Agent CLIs: Design Logic, Tool Comparison, and Best Practices

🌏 中文版

Before 2025, AI coding assistants were mostly used for autocomplete (Copilot) or Q&A (ChatGPT). You typed, it responded, you copied and pasted, and you decided whether to use it or not.

After 2025, Agent CLIs changed this paradigm. You input a task, and the agent reads the codebase, runs tests, modifies code, and opens a PR -- all while you go grab a coffee.

This article covers the design logic of Agent CLIs, differences between major tools, and how to use them effectively. Each tool has its own dedicated deep-dive article; this serves as the overview map.

What Is an Agent CLI

An Agent CLI is an AI coding agent that runs in the terminal. The fundamental difference from traditional autocomplete tools is that it doesn't just answer your questions -- it has the ability to take action in your environment.

A typical capability set includes:

• Reading entire repos (not just your selected snippets)
• Executing shell commands (running tests, installing packages, git operations)
• Reading and writing to the filesystem
• Calling external APIs and MCP tools
• Maintaining context and plans across multiple steps

This transforms it from a "Q&A assistant" into an "agent capable of executing tasks."

Major Tools

Claude Code (Anthropic)

Built by Anthropic, powered by Claude Sonnet / Opus models. Positioned as the developer's primary daily agent, not a point-solution helper.

Core design: The CLAUDE.md system lets you place working guidelines in your repo or ~/.claude/; the Skills system packages common workflows into slash commands; Hooks inject automation logic at tool-call events; MCP integration connects external tools; the Sub-agent architecture supports parallel agent dispatch.

The most feature-complete option, suitable as a primary development tool. Billed by Anthropic API token usage.

-> Claude Code: Anthropic's Terminal AI Coding Agent -- Complete Overview

Codex CLI (OpenAI)

OpenAI's open-source Agent CLI (Apache-2.0, ~106.6k stars), built in Rust. Can be used with a ChatGPT subscription plan (Plus / Pro / Team / Enterprise) directly, or with your own API key.

Core design: The AGENTS.md system mirrors CLAUDE.md; three authorization modes (suggest / auto-edit / full-auto); sandbox isolation (Apple Sandbox on macOS, Docker on Linux); fully local execution with no state uploaded.

Ideal for developers who need strict control over the execution environment or want to customize agent behavior.

-> Codex CLI: OpenAI's Open-Source Terminal Coding Agent -- Complete Overview

Antigravity CLI (Google)

Google's terminal agent today. The Gemini CLI it replaced stopped serving individual accounts on 2026/06/18 — that "1,000 free requests a day" tier no longer exists, and Gemini CLI itself is down to two paths: enterprise licenses and paid API keys (the repo is still maintained under Apache-2.0, ~106.6k stars).

Antigravity CLI is rewritten in Go, shares a server-side harness with the Antigravity 2.0 desktop app, keeps Agent Skills, Hooks, and Subagents (Extensions are now plugins), and leads on async background workflows. The cost is that it is no longer open source.

-> Antigravity CLI: Google's Terminal AI Agent -- Complete Overview

OpenCode

An open-source AI coding agent (TypeScript, MIT, ~198.7k stars, repo at anomalyco/opencode) with a built-in TUI and now a desktop app. Its biggest feature is support for 75+ LLMs -- connecting to Anthropic, OpenAI, Ollama local models, and any OpenAI-compatible API.

Core design: LSP integration gives the agent IDE-level code understanding; a dual-agent mode (planning agent + execution agent division of labor); Vim-style editor; SQLite session management.

-> OpenCode: Open-Source AI Terminal Coding Agent -- Complete Overview

Aider (Paul Gauthier)

The most established terminal pair programming tool (~48.3k GitHub stars, repo at Aider-AI/aider), pure CLI, built in Python, Apache-2.0. Supports 100+ LLMs — the officially recommended models turn over every generation, so check the repo's leaderboard. Its standout feature is automatic git commits -- every AI modification automatically creates a commit, making review and rollback easy.

Core design: --architect mode (high-capability model designs the architecture, low-cost model implements it); --watch mode detects AI comments and triggers automatically; excellent SWE-bench scores.

Best suited for developers who want a lightweight, reliable terminal pair programmer without complex agent features.

-> Aider: The Oldest Terminal AI Pair Programmer, and Where Its Maintenance Stands

Pi (Mario Zechner)

A minimalist open-source coding harness, built in TypeScript, running on the Bun runtime. The core consists of just 4 tools (read, write, edit, bash) and a 300-word system prompt -- the design philosophy is "reject complexity."

Core design: Extensible through Extensions, Skills, and Prompt Templates; Ollama has built-in ollama launch pi for one-click startup; deep integration with OpenClaw.

-> Pi Coding Agent: A Minimalist Open-Source Terminal Coding Harness

Kiro CLI (AWS)

An official AWS product (formerly Amazon Q Developer CLI), available as both an IDE (Code OSS fork) and a standalone CLI.

Core design: Spec-driven development -- uses EARS notation to convert natural language requirements into structured requirements + acceptance criteria, then generates architecture designs and task lists, with the agent executing step by step; Agent Hooks auto-trigger on events like file saves; supports multimodal input; native MCP; defaults to Auto mode (dynamically mixing frontier and specialized models, cheaper in credits than pinning a single frontier model), with premium models selectable on paid plans.

Best for teams heavily invested in the AWS ecosystem or those who prefer spec-first development workflows. Official site: kiro.dev

Cursor CLI (Anysphere)

A standalone CLI from the Cursor AI IDE, one-line install: curl https://cursor.com/install -fsS | bash. Positioned as "deliver code in any environment" -- no need to open the IDE, just run the agent directly in the terminal.

Core design: Supports all Cursor models (Claude Opus 4.6, GPT-5.2, Gemini 3 Pro, Grok, etc.); Shell Mode lets the agent execute shell commands directly and display output; Headless mode for CI pipelines and script automation; GitHub Actions integration can trigger nightly docs updates, security audits, and other workflows; MCP integration.

Can be used independently without the Cursor IDE, suitable for CI/CD automation or developers who want to use Cursor subscription models in the terminal. Official site: cursor.com/cli

GitHub Copilot CLI (GitHub / Microsoft)

GitHub's official terminal agent, bundled with GitHub Copilot subscription plans (Free / Pro / Team / Enterprise), no additional cost. Provides a chat interface in the terminal that can autonomously read/write files, execute commands, and complete bug fixes, feature development, documentation updates, and test completion.

Core design: Autopilot mode (--allow-all) lets the agent operate fully autonomously without step-by-step confirmation; by default, only accesses files in the current directory -- cross-directory access requires explicit authorization; supports custom instructions (.github/copilot-instructions.md) for project-specific guidelines; deep integration with the GitHub ecosystem (PR review, issue triage, GitHub Actions).

Ideal for developers who already have a GitHub Copilot subscription and work within the GitHub ecosystem -- no additional API setup required. It went generally available on 2026-02-25 and is included in every plan, Free included.

-> GitHub Copilot CLI: An Agent That Runs on GitHub the Platform

Amp (Amp Frontier Corporation)

Originally a Sourcegraph product, spun out as Amp Frontier Corporation in December 2025, with the npm package renamed from @sourcegraph/amp to @ampcode/cli. It dropped editor extensions in early 2026 to focus on the CLI — one item on a long list of deliberate removals.

Its current focus is orbs (remote machines that keep working after you close your laptop), and monthly subscriptions only arrived on 2026-07-18 (Megawatt $20 / Gigawatt $200); before that it was pay-as-you-go only.

Suited for developers willing to move with the frontier and tolerate features being removed.

-> Amp: The Coding Agent That Defines Itself by What It Deletes

Tool Comparison Overview

Core Design Pattern: Context Engineering

How well an Agent CLI works is 30% model capability and 70% the context you provide.

Context files (CLAUDE.md / AGENTS.md / GEMINI.md) -- tell the agent about this project's conventions, prohibitions, workflows, and anything that can't be inferred from the code itself.

A good context file:

# Project Context
This project is ... using ... tech stack, deployed on ...

# Commit Convention
Use conventional commits format for every commit: feat / fix / docs / refactor

# Do Not
- Do not use `git add .`, add files to commit individually
- Do not delete files without asking first
- Do not commit before tests pass

# Workflow
1. Read the relevant tests before modifying code
2. Run `npm test` after making changes
3. Handle bug fixes using TDD approach

Principles: Specific instructions beat vague principles ("follow clean code" is useless); prohibitions must be explicit (the agent doesn't know what you consider obvious constraints); use layered management (global settings for common habits, repo root for project-specific conventions).

Tool Usage and Authorization Modes

Read-only tools (typically safe to auto-allow): reading files, searching the codebase, git log / diff

Write tools (confirmation recommended): editing/creating/deleting files, git commit / push

Execution tools (highest risk): executing shell commands, calling external APIs

Setting the authorization mode to "fully automatic" and then complaining that the agent did something you didn't want is the most common mistake.

Practical Principles for Effective Use

Break tasks down instead of giving everything at once:

Bad:  "Convert this entire codebase from REST API to GraphQL"
Good: "First list all external REST endpoints, don't modify any code"
   -> After confirmation: "Convert /users GET and POST to GraphQL, leave everything else alone"

Have the agent plan before executing:

> claude "I want to refactor the auth module, first tell me your plan, don't touch any files"

Package repeatable workflows: If you type the same instructions for every commit, that's a signal to package it. Claude Code's Skills, Pi's Prompt Templates, and Kiro's Custom Agents all serve this purpose.

Verification is your responsibility: The agent won't tell you it made a mistake. Having the agent run tests to confirm they pass, checking git diff before critical operations -- these steps are non-negotiable.

Overall Assessment

Selection logic:
Claude Code        -> Most feature-complete, ideal for primary daily use
Codex CLI          -> Open-source and controllable, ideal for sandbox isolation needs
Antigravity CLI    -> Google ecosystem, async background tasks (Gemini CLI's individual tier is gone)
OpenCode           -> LLM-agnostic, ideal for multi-model mixing or local deployment
Aider              -> Auto git commit, ideal for lightweight pair programming
Pi                 -> Minimalist, ideal for understanding internals or custom harnesses
Kiro CLI           -> Spec-first, ideal for AWS ecosystem or spec-driven teams
Cursor CLI         -> IDE extension, ideal for Cursor users needing terminal/CI coverage
GitHub Copilot CLI -> Already have Copilot subscription, ideal for GitHub ecosystem workers
Amp                -> Orbs for long unattended runs; for those tracking the frontier

The core trade-off: investing the upfront cost of context engineering in exchange for an efficiency multiplier on every subsequent task. For developers working in the same repo long-term, this investment pays back quickly.

References

• Claude Code Official Documentation
• OpenAI Codex CLI GitHub
• Gemini CLI GitHub
• OpenCode GitHub
• Aider GitHub
• Pi Coding Agent GitHub
• Antigravity CLI announcement
• Kiro Official Website
• GitHub Copilot CLI Official Documentation
• Amp
• Cursor CLI Official Website
• AGENTS.md Standard Draft
• Model Context Protocol (MCP) Specification
• Anthropic: Building Effective Agents

Changelog

• 2026-08-19: Added links to the three new dedicated posts (Aider, GitHub Copilot CLI, Amp), making good on this post's claim that each tool has its own article; corrected Amp's ownership (spun out of Sourcegraph as Amp Frontier Corporation in 2025-12, npm package renamed @ampcode/cli) and its current focus (orbs, subscriptions only since 2026-07); noted Aider's slowed maintenance and Copilot CLI's 2026-02-25 GA
• 2026-08-18: Full pass over every tool's current state. (1) Gemini CLI's individual tier ended 2026/6/18; that section is now Antigravity CLI, with the selection list and comparison table updated to match. (2) Corrected OpenCode's language and repo (Go → TypeScript, opencode-ai/opencode → anomalyco/opencode). (3) Fixed three broken or wrong repo links: Aider (paul-gauthier → Aider-AI), Pi (badlogic/lemmy → earendil-works/pi), and OpenCode. (4) Updated star counts: Codex 71k → ~106.6k, Gemini CLI ~99.8k → ~106.6k, Aider 42.7k → ~48.3k, plus OpenCode ~198.7k and Pi ~93k. (5) Removed hardcoded model IDs (Kiro's Sonnet 4.5, Cursor's Opus 4.6 / GPT-5.2 / Gemini 3 Pro, Aider's Claude 3.7 / o1) in favor of tiers or current mechanisms. (6) Added Pi's "deliberately omitted" design stance