Working with Claude

Cairn orchestrates agents by calling the Claude Code CLI directly. This means you bring your own Claude access (subscription or API) and Cairn never needs your credentials directly.

Direct CLI Integration

Under the hood, Cairn spawns claude processes with specific flags:

claude --output-format stream-json \
       --mcp-config /path/to/config.json \
       --model sonnet \
       --resume <session-id> \
       -- "Your task here"

This direct integration has significant advantages:

Max Compatible. Use Claude with a Pro/Max subscription or API credits. Since it's calling the official CLI on your behalf, Cairn is compliant with Anthropic's Terms of Service.

Session continuity via native sessions. When you continue a conversation or resume a job, Cairn uses Claude's --resume flag with the original session ID. The conversation history lives in Claude's native session system, not reconstructed from event logs. This means:

• Prompt caching works automatically across turns
• No token overhead from replaying history
• Sessions can be resumed even after Cairn restarts

Automatic best practices. Because Cairn calls claude directly, you automatically get any optimizations Anthropic ships—backend improvements, new model capabilities, efficiency gains. No waiting for Cairn to "support" new features.

MCP Server Configuration

Cairn injects its own MCP server (cairn-mcp) to provide tools like write, edit, create_pr, and task. But your existing MCP servers work too.

Install MCP servers to Claude, not Cairn. Any MCP servers you've configured with claude mcp add are available to agents running in Cairn. There's no separate configuration—Cairn respects your existing Claude setup.

When Cairn starts an agent, it passes --mcp-config pointing to a merged configuration that includes both Cairn's tools and your globally-installed servers.

Interoperable Agents and Skills

Cairn uses the same markdown format as Claude Code for defining agents and skills, so .md files work in both contexts:

Agents

Agents define a persona with specific tools and behaviors:

---
name: Code Reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
disallowedTools: Bash
skills: code-review-guidelines
---

You are a thorough code reviewer. When reviewing changes:
- Check for potential bugs and edge cases
- Verify error handling is appropriate
- Look for performance concerns
- Suggest improvements without being pedantic

The frontmatter fields:

• name — Display name for the agent
• description — Short summary (shown in agent picker)
• tools — Comma-separated list of allowed tools
• model — Optional model override (sonnet, opus, haiku)
• permissionMode — How Claude handles permissions (plan, acceptEdits)
• disallowedTools — Optional comma-separated list of tools to block for this agent
• skills — Optional comma-separated list of skill IDs to inject into the agent's prompt

Skills

Skills are reusable instruction sets that agents can retrieve on demand:

---
name: React Testing Patterns
description: Best practices for testing React components with Vitest
allowedTools: Read, Grep, Bash
---

When writing tests for React components:

1. **Use `@testing-library/react`** for component tests
2. **Test behavior, not implementation** — query by role/label, not class names
3. **Keep tests focused** — one concept per test
...

Skills differ from agents: they don't define a complete persona, just injectable expertise. An agent retrieves a skill's content with the skill tool when it needs that knowledge.