Skip to content

Quickstart

This page gets you from install to a running agent in about a minute. If you haven't yet, install caw and make sure at least one provider CLI (e.g. claude) is authenticated — caw doctor will tell you.

60-second example

from caw import Agent

agent = Agent()  # defaults to claude_code
traj = agent.completion("Explain what this repository does")

print(traj.result)
print(f"{traj.usage.total_tokens} tokens, ${traj.usage.cost_usd:.4f}")

Agent.completion() runs a single message and returns the complete Trajectory — traj.result is the final text, and traj.usage carries the token counts and cost.

Multi-turn session

When you need follow-up turns that share context, open a session:

from caw import Agent

agent = Agent(provider="claude_code", model="opus", reasoning="high")
agent.set_system_prompt("You are a security reviewer.")

with agent.start_session() as session:
    print(session.send("Review src/auth.py for vulnerabilities").result)
    print(session.send("Now check src/api.py").result)
# session.end() runs on context-manager exit and returns the full Trajectory

This is the runnable examples/basic.py:

"""Basic usage: single turn, tool use, and multi-turn sessions."""

import os

os.environ["CAW_LOG"] = "full"

from caw import Agent


def main():
    agent = Agent(data_dir="caw_data")

    print("=== Single turn ===")
    with agent.start_session() as session:
        session.send("What is 2 + 2? Answer in one sentence.")
        print()

    print("=== Tool use turn ===")
    with agent.start_session() as session:
        session.send("List files in the current directory.")
        print()

    print("=== Multi-turn ===")
    with agent.start_session() as session:
        session.send("Remember the number 42.")
        session.send("What number did I just tell you?")

        traj = session.trajectory
        print(f"\nTurns: {traj.num_turns}")
        print(f"Total tool calls: {traj.total_tool_calls}")
        print(f"Total tokens: {traj.usage.total_tokens}")


if __name__ == "__main__":
    main()

Swap providers without changing code

The same code runs against any backend. Pin one explicitly:

agent = Agent(provider="codex")

…or give caw a fallback order and let it use whatever is installed and healthy at runtime:

agent = Agent(provider=["claude", "codex", "opencode"])
traj = agent.completion("Reply with a one-line hello.")
print(f"[{traj.agent}] {traj.result}")  # whichever provider handled it

See Auto-provider mode for the full fallback semantics.

Where to go next