Quickstart: Zero to First Agent in 5 Minutes

Cowboy is an AI agent harness that lets you run autonomous AI agents directly in your terminal. This guide will get you from zero to your first agent session in under 5 minutes.

🚀 Quick Start (2 Minutes)

Step 1: Start Your First Agent Session

# Basic session with Claude Opus
cowboy --model anthropic:claude-opus-4-6

# Or specify a task directly
cowboy --model anthropic:claude-opus-4-6 --task "Analyze this directory structure"

Step 2: Interact with Your Agent

Once the session starts, you'll see a prompt like this:

🤖 Agent: I'm ready to help. What would you like me to do?

Just type naturally - the agent will understand and use the right tools:

👤 You: What files are in the current directory?

The agent will automatically use the ls tool and show you the results.

🛠️ Available Tools

Cowboy provides these built-in tools for interacting with your system:

File Operations

  • read - Read file contents or fetch URLs
  • write - Create or overwrite files
  • find - Find files by name pattern
  • ls - List directory contents

Search & Analysis

  • search - Search file contents recursively with grep
  • web-search - Search the web for real-time information

System Operations

  • bash - Execute shell commands (with security controls)
  • reload_plugin - Reload the Zellij plugin after updates

💡 Practical Examples

File Management

"Read the README.md file"
"Search for TODO comments in the codebase"
"Create a new configuration file at ./config.json"
"List all Python files in the project"

Development Tasks

"Run tests in the current project"
"Check for linting issues in the src/ directory"
"Generate documentation for the API"
"Find all files containing 'import React'"

System Analysis

"Check disk usage and report any issues"
"List running processes"
"Check network connectivity"
"Analyze the directory structure"

🎯 Common Interactions

Reading Files

👤 You: Read the package.json file

🤖 Agent: I'll read the package.json file for you.
[Tool: read] Executing: read path=package.json
[Tool: read] Output:
{
  "name": "my-project",
  "version": "1.0.0",
  ...
}

Searching Codebase

👤 You: Search for all function definitions in Rust files

🤖 Agent: I'll search for function definitions in .rs files.
[Tool: search] Executing: search pattern="fn " path=. flags="-w"
[Tool: search] Output:
src/main.rs:42:fn main() {
src/lib.rs:10:fn helper_function() {
...
}

File Operations

👤 You: Create a new file with a simple hello world program

🤖 Agent: I'll create a new Python file with a hello world program.
[Tool: write] Executing: write path=hello.py content="print('Hello, World!')"
[Tool: write] Output: File written successfully

🔧 Session Management

Save and Resume Sessions

# Save current session state
cowboy --save-session my-project-session

# Resume a previous session
cowboy --load-session my-project-session --model anthropic:claude-opus-4-6

Stop Running Sessions

# Stop the current session
cowboy --stop

# Stop a specific session
cowboy --session my-session --stop

⚙️ Configuration Basics

API Keys

Set these environment variables for full functionality:

export ANTHROPIC_API_KEY="sk-ant-..."
export EXA_API_KEY="..."  # For web search

Model Options

# Anthropic Claude models
cowboy --model anthropic:claude-opus-4-6
cowboy --model anthropic:claude-sonnet-4-0

# OpenAI models
cowboy --model openai:gpt-4.1

# OpenRouter models
cowboy --model openrouter:anthropic/claude-3-opus

🛡️ Security Features

Cowboy includes built-in security controls:

  • Tool Approval: Sensitive operations require confirmation
  • Execution Limits: Timeouts prevent runaway processes
  • Audit Logging: All actions are logged for review
  • Sandboxed Execution: Tools run in controlled environments

🎓 Next Steps

Once you've completed your first session, explore these advanced features:

  1. Configuration - Customize tools, security, and memory settings
  2. Sub-Agents - Run multiple agents in parallel
  3. Memory System - Enable persistent knowledge storage
  4. Security Model - Understand the security architecture

🚨 Troubleshooting

"No API keys found"

Set your API keys as environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."

"Zellij not found"

Install Zellij first:

nix profile install nixpkgs#zellij

Session won't start

Check if another session is running:

cowboy --stop
cowboy --model anthropic:claude-opus-4-6

Ready to go deeper? Continue to the Configuration guide to customize Cowboy for your workflow.