blueclaw 2.2.0

Terminal AI agent with built-in execution tracing and observability

Understand, debug, and control AI agent behavior.
Structured tracing, context management, and reproducible runs — all from the terminal.

Quickstart · Features · Models · Configuration · Roadmap · Contributing · License

---

• Structured traces — every run writes a structured JSON trace, queryable from the terminal with no external service
• Regression testing — define expected behavior in YAML; run as CI with TAP or JUnit output and Wilson CI scoring
• Context management — observation masking keeps token cost low across long sessions without losing quality
• Trace replay & diff — step through any recorded run interactively, or compare steps, tokens, and cost between two runs
• HTTP API + stateful conversations — blueclaw serve exposes the agent over HTTP with bearer auth, SSE streaming, a concurrency cap, and per-conversation_id history persisted via FileSessionManager
• Built-in playground — GET /playground ships a single-page chat UI with blueclaw serve for manual stateful + streaming testing

Quickstart

pip install blueclaw
blueclaw init
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
blueclaw

Features

Tracing & Observability — docs/tracing.md

Every run produces a structured JSON trace. Ten CLI commands let you inspect, compare, and replay runs without a hosted dashboard.

$ blueclaw trace graph 20260315-054426

search for Python 3.13 new features
├── web_search (1ms) ✓  query: Python 3.13 new features
├── web_search (1ms) ✓  query: Python 3.13 new features list 2024
└── http_request (366ms) ✓  url: https://docs.python.org/3.13/whatsnew/3.13.html

trace list · trace show · trace graph · trace timeline · trace diff · trace explain · trace replay · trace stats · trace ui · trace purge

Regression Testing — docs/testing.md

Define expected behavior in YAML, run as a CI test suite with TAP or JUnit output. Multi-run Wilson CI scoring handles non-determinism.

blueclaw test spec.yaml
blueclaw test spec.yaml --format junit -o results.xml

11 deterministic assertions: tools called, output content, file existence, cost, step count, duration, tool order.

Context Management

Tool outputs from older turns are automatically masked to keep token cost low across long sessions without losing model reasoning quality. A hybrid summarization mode is available for very long conversations.

HTTP API — docs/api.md

Expose the agent over HTTP for programmatic access or tool integration.

blueclaw serve                          # http://127.0.0.1:8420
curl -X POST http://127.0.0.1:8420/message \
  -d '{"message": "what is in the workspace?"}' | jq .

# Stream tokens as they're generated:
curl -N -X POST http://127.0.0.1:8420/message/stream \
  -d '{"message": "what is in the workspace?"}'

Bearer token auth (BLUECLAW_API_KEY), 1 MB body cap, 300 s timeout, CORS for localhost. A shared asyncio.Semaphore (default 4, configurable via --max-concurrent) caps simultaneous agent runs. Every API request writes a trace visible in blueclaw trace ui.

Model Support — docs/models.md

blueclaw                                    # Anthropic (default)
blueclaw --model ollama/llama3.1:8b         # Ollama (local)
blueclaw --model openai/gpt-4.1-mini       # OpenAI
blueclaw --model litellm/gemini/gemini-2.0-flash  # Gemini via LiteLLM

Set API keys in .env:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Configuration

blueclaw.yaml in your project root:

model:
  provider: anthropic
  model_id: claude-sonnet-4-6

workspace:
  path: ~/blueclaw/workspace/
  trace_retention_days: 30

tools:
  - web
  - shell
  - pdf
  - mcp:http://localhost:8080/sse        # SSE MCP server (use mcp:<command> for stdio)

allowlist_domains:
  - github.com
  - docs.python.org

Architecture

Module	Purpose
cli.py	Typer entrypoints, welcome banner, trace tooling
session.py	Config, model factory, agent, chat loop, background context updater
server.py	HTTP API gateway (blueclaw serve) — /message, /message/stream, /playground, /health, /api/traces; bearer auth, CORS, per-conversation locks
workspace.py	Sandbox enforcement, context/history/trace I/O
observer.py	Structured tool tracing + output truncation
context.py	Observation masking and hybrid summarization for context management
lessons.py	Extracts behavioral hints from past traces and injects into system prompt
models.py	Pydantic models, trace schema, cost calculation, error classification
testing.py	Test spec loading, runner, assertions, formatters, stub replay
tools/	Web, shell, MCP wiring (factory pattern)
approval.py	Shell command + domain allowlist hooks

Built on Strands Agents SDK.

Roadmap

See docs/roadmap.md for the full roadmap with milestone details.

Contributing

pip install -e ".[dev]"
pytest
flake8 blueclaw/ tests/
black --check blueclaw/ tests/

Bug reports and pull requests are welcome. See docs/contributing.md for the full guide.

Links

• AI Agent Observability Without a Dashboard — The story behind blueclaw's design: why we built structured tracing into the terminal instead of a hosted service
• I Cut My AI Agent's Token Costs 21% Without Changing the Model — Benchmarks behind blueclaw's ObservationMaskingManager: why replacing stale tool outputs with placeholders beats LLM summarization on cost and speed
• How I Debug AI Agents Like Code (Not Guesswork) — A walkthrough of blueclaw's 10 trace CLI commands: trace list → show → timeline → diff turns "re-run and guess" debugging into actual inspection in under a minute

License

MIT