Skip to content

caw

One interface for every coding agent.

caw (Coding Agent Wrapper) is a Python library and CLI that wraps multiple coding-agent CLIs — Claude Code, Codex, and opencode — behind a single Agent / Session API. Swap providers without changing your code, attach MCP tool servers, capture structured trajectories, and manage credentials for Docker containers.

caw aims at the common cases with a small, ergonomic API — if you need fine-grained control over agent behavior, reach for the underlying agent SDKs; caw isn't trying to replace them.

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}")

Get started Quickstart API reference

Why caw

  • One API, three backends. Pin a provider, or give caw a fallback order and let it pick whatever is installed and healthy at runtime. See Providers and Auto-provider mode.
  • Portable model selection. Use ModelTier so "strongest" and "fast" resolve per provider — no hard-coded model strings.
  • Multi-turn sessions that resume across processes. Grab a resume_handle and continue the conversation later, even in a different process or without a data_dir.
  • Tools your way. Attach MCP servers, define tools declaratively with ToolKit, or register subagents the parent can call.
  • Structured trajectories. Every interaction yields a Trajectory with turns, content blocks, token usage, and cost — persisted to JSONL and viewable in the trajectory viewer.
  • Health checks & credentials. Probe provider health and bind-mount OAuth credentials into Docker containers without touching host files.

Install

pip install coding-agent-wrapper

Requires Python 3.10+. See Installation for the CLI prerequisites and dev setup.

For agents

These docs are also published as machine-readable llms.txt (index) and llms-full.txt (flattened) — handy when caw's own users are agents.