Run Your First Task

The primary way to run agent tasks is through the command line. The TUI dashboard provides a visual interface for the same operations.

Quick Start with CLI

Start an agent directly from the command line:


ah agent start --agent claude --prompt "Add a README file to this project"

This launches Claude Code agent in your current directory with the specified prompt.


ah agent start --agent claude --claude-model sonnet --prompt "Refactor the main function"

For scripting or CI/CD, use non-interactive mode:


ah agent start --agent claude --non-interactive --prompt "Generate unit tests"

The agent executes a single turn and exits.

For interactive task management, launch the TUI:

ah

Or explicitly:


ah tui

TUI dashboard overview

The TUI opens a dashboard where you can:

Agent	Flag	Description
Claude Code	`--agent claude`	Anthropic’s Claude Code agent
OpenAI Codex	`--agent codex`	OpenAI’s Codex CLI
GitHub Copilot	`--agent copilot`	Requires `--experimental-features copilot`
Google Gemini	`--agent gemini`	Requires `--experimental-features gemini`


ah agent start --agent gemini --experimental-features gemini --prompt "Your task"

Flag	Description
`--output-format text`	Full TUI with animated output (default)
`--output-format basic-text`	Simple stdout, no animations
`--output-format json`	JSON output at completion
`--output-format stream-json`	Streaming JSON events


ah agent start --agent claude --output-format json --prompt "List all files"

Run agents in a sandboxed environment for extra security:


ah agent start --agent claude --sandbox --prompt "Install dependencies and run tests"

Record the agent session for later replay:


ah agent record --out-file session.ahr -- ah agent start --agent claude --prompt "Fix the bug"

Replay the session:


ah agent replay session.ahr