Quickstart

This assumes Cowboy is installed (see Installation) and you have an API key for at least one provider.

Set a key

export ANTHROPIC_API_KEY="sk-ant-..."
export EXA_API_KEY="..."          # optional, enables web search

Start a session

cowboy --model anthropic:claude-sonnet-4-20250514

This opens a Zellij session running the agent. Type your request in plain language; the agent decides which tools to call and shows each call and its result inline.

To run a single task non-interactively and exit when done:

cowboy -q "Summarize the README and list any broken links"

To stop a running session:

cowboy --stop

Choosing a model

Pass provider:model. The default provider is anthropic.

cowboy --model anthropic:claude-sonnet-4-20250514   # default
cowboy --model anthropic:claude-opus-4-5-20251101
cowboy --model openai:gpt-4.1
cowboy --model openrouter:moonshotai/kimi-k2.5
cowboy --model ollama:llama3.1:8b                   # local
cowboy --model codex:gpt-5.6-luna                  # full NixOS mode

Codex uses a ChatGPT subscription. It is available in the full NixOS deployment, where the credential proxy supplies the subscription token; portable Lite mode requires a provider with a directly configured API key.

A cheaper model can be used for background summarization and context compaction:

cowboy --model anthropic:claude-opus-4-5-20251101 \
       --summary-model anthropic:claude-sonnet-4-20250514 \
       --compact-model anthropic:claude-sonnet-4-20250514

See Configuration for all flags and config keys.

Tools the agent can use

The agent has these tools by default:

Tool	Purpose
`read`	Read file contents
`write`	Create or overwrite a file
`search`	Recursive content search (ripgrep)
`find`	Find files by name pattern
`ls`	List directory contents
`bash`	Run a shell command
`web-search`	Search the web (requires `EXA_API_KEY`)
`view_image`	Inspect an image or screenshot (when vision support is configured)

It also has built-in tools for hashline editing, memory, and spawning sub-agents.

Example requests

Read README.md and tell me what this project does.
Search for TODO comments under src/ and group them by file.
Find every Python file that imports requests, then add a comment at the top of each.
What changed in the last three commits?

Next steps

Configuration — flags, config files, and NixOS options
Sub-Agents — delegate work to parallel agents
Memory System — persistent notes across sessions
Security Model — how tools are bounded in full mode

Keyboard shortcuts