Quick Start

Get up and running with cagent in under 5 minutes. Pick whichever path suits you best.

Option A: Run the Default Agent

The fastest way to try cagent — no config file needed:

# Launch the default agent with the interactive TUI
$ cagent run

This starts a general-purpose assistant with sensible defaults. Just start chatting.

Option B: Run a Pre-Built Agent from the Registry

Try a ready-made agent from the agent catalog — no YAML needed:

# Run a pirate-themed assistant
$ cagent run agentcatalog/pirate

# Run a coding agent
$ cagent run agentcatalog/coder

Option C: Generate a Config Interactively

Use the cagent new command to scaffold a config file through prompts:

# Interactive wizard
$ cagent new

# Or specify options directly
$ cagent new --model openai/gpt-4o

# Override context size and iteration limits
$ cagent new --model dmr/ai/gemma3-qat:12B --max-tokens 32000 --max-iterations 15

This generates an agent.yaml in the current directory. Then run it:

cagent run agent.yaml

Option D: Write Your Own Config

Create an agent.yaml by hand for full control. Here’s a minimal example:

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: A helpful coding assistant
    instruction: |
      You are an expert software developer. Help users write
      clean, efficient code. Explain your reasoning.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think

This gives your agent:

• Claude Sonnet 4 as the underlying model
• Filesystem access to read and write files
• Shell access to run commands
• Think tool for step-by-step reasoning

# Launch the interactive terminal UI
$ cagent run agent.yaml

Try It Out

Once your agent is running, try asking it to:

• “List the files in the current directory”
• “Create a Python script that fetches weather data”
• “Explain what the code in main.go does”

Non-Interactive Mode

Use cagent run --exec for one-shot tasks:

# Ask a single question
$ cagent run --exec agent.yaml "Create a Dockerfile for a Node.js app"

# Pipe input
$ cat error.log | cagent run --exec agent.yaml "What's wrong in this log?"

Add More Power

Give your agent persistent memory and web search:

agents:
  root:
    model: anthropic/claude-sonnet-4-0
    description: Research assistant with memory
    instruction: |
      You are a research assistant. Search the web for information,
      remember important findings, and provide thorough analysis.
    toolsets:
      - type: think
      - type: memory
        path: ./research.db
      - type: mcp
        ref: docker:duckduckgo

What’s Next?