Q&A

❓ ClawCode — Frequently Asked Questions

Everything you wanted to know about ClawCode, answered.

---

Table of Contents

• Getting Started
• Core Concepts
• LLM Providers & Models
• Development Workflow
• Collaboration & Teams
• Themes & UI Customization
• Learning & Evolution
• Privacy & Security
• Integrations & Extensibility
• Troubleshooting
• Comparison & Alternatives

---

Getting Started

Q: What is ClawCode?

ClawCode is an open-source, terminal-native AI coding assistant platform. Think of it as your AI-powered engineering cockpit — it combines an intelligent agent runtime, 20+ development tools, multi-agent team orchestration, and a self-improving learning system, all running inside your terminal.

Unlike simple chat-based AI tools, ClawCode can read, write, edit, search, and execute code in your project, plan complex features with structured workflows, coordinate teams of AI specialists, and learn from every session to get better over time.

---

Q: How do I install ClawCode?

# Clone the repository
git clone https://github.com/your-org/clawcode.git
cd clawcode

# Install with pip (Python 3.12+)
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Once installed, launch the interactive TUI:

clawcode

Or run a one-shot non-interactive query:

clawcode -p "Explain the authentication module"

---

Q: What are the system requirements?

Requirement	Detail
Python	3.12 or later
Operating System	Windows, macOS, or Linux
Terminal	Any modern terminal (Windows Terminal, iTerm2, Alacritty, etc.)
LLM API Key	At least one provider API key (Anthropic, OpenAI, or Google)

---

Q: How do I configure my first API key?

Create a .clawcode.json file in your project root or home directory:

{
  "providers": {
    "anthropic": {
      "api_key": "sk-ant-your-key-here"
    }
  }
}

Alternatively, set the environment variable:

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

That's it — launch clawcode and start coding.

---

Q: Can I try ClawCode for free?

Yes! You can use the GitHub Copilot provider which works with your existing Copilot subscription (no additional API key needed). Or use any provider that offers free tiers (Google Gemini, for example).

{
  "providers": {
    "copilot": {
      "disabled": false
    }
  }
}

---

Core Concepts

Q: How does ClawCode actually work?

ClawCode runs a ReAct (Reasoning + Acting) agent loop:

1. You type a request
2. The agent reasons about what to do
3. It selects and invokes tools (read files, search code, edit, run commands)
4. It observes the results
5. It repeats until the task is done

The agent has access to 20+ tools — file operations, shell execution, code search, browser automation, and more. Each tool call is permission-gated (you control what's allowed).

---

Q: What tools does the agent have?

Category	Tools
File operations	View, Write, Edit, Patch
Shell	Bash (with timeout), ExecuteCode (sandboxed Python)
Search	Glob (file patterns), Grep (content regex) — Rust-powered for speed
Advanced	WebFetch, Diagnostics (LSP), TodoWrite/Read
Browser	Navigate, Click, Type, Screenshot, Vision analysis, Web search
Desktop	Screenshot, Mouse, Keyboard
Agents	Agent/Task (spawn subagents with isolated tool sets)
Integration	MCP (external tool servers), Git operations

---

Q: Is it safe to let an AI agent modify my code?

ClawCode provides multiple safety mechanisms:

Safety Feature	How It Works
Permission dialogs	Destructive operations require your approval
Plan mode	Read-only research mode — agent can look but not touch
Spec mode	Three-phase: analyze (read-only) → implement → verify (test-only)
/rewind	One-command undo — restore all files to their git HEAD state
Git integration	All changes are trackable via git diff
File tracking	Real-time panel showing exactly which files were read or modified

---

LLM Providers & Models

Q: Which LLM providers does ClawCode support?

ClawCode supports an exceptionally wide range of providers:

Provider	Models	Special Notes
Anthropic	Claude 3.5 Sonnet/Haiku/Opus, Claude 3.7 Sonnet	Extended thinking, prompt caching
OpenAI	GPT-4o, o1/o3/o4, GPT-4.1	Plus 20+ OpenAI-compatible APIs
Google Gemini	1.5 Pro, 2.0 Flash, 2.5 Pro/Flash	Up to 2M token context window
Groq	Llama, Mixtral, Qwen, DeepSeek	Ultra-fast inference
Azure OpenAI	All OpenAI models	Enterprise compliance
OpenRouter	100+ models from any vendor	Unified API
xAI	Grok-2, Grok-2-mini	Up to 131K context
AWS Bedrock	Claude, Titan, Llama, Mistral	AWS-native
GitHub Copilot	GPT-4o, Claude, Gemini, O-series	Works with Copilot subscription

---

Q: Can I use Chinese LLMs?

Absolutely! ClawCode has first-class support for Chinese LLM providers through OpenAI-compatible endpoints:

Provider	Models	Configuration
DeepSeek	deepseek-chat, deepseek-reasoner	Auto-detected from model name
Qwen (Alibaba)	qwen-, qwq-, qvq-*	Auto-detected
GLM (Zhipu)	glm-*	Auto-detected
Moonshot/Kimi	moonshot-*	Auto-detected
MiniMax	minimax-, abab-	Auto-detected
VolcEngine/Doubao	doubao-, ep-	Auto-detected
Baichuan	baichuan-*	Auto-detected
StepFun	step-*	Auto-detected

Just set the API key and base URL in your config:

{
  "providers": {
    "openai": {
      "api_key": "your-deepseek-key",
      "base_url": "https://api.deepseek.com/v1",
      "models": ["deepseek-chat", "deepseek-reasoner"]
    }
  },
  "agents": {
    "coder": {
      "model": "deepseek-chat",
      "provider_key": "openai"
    }
  }
}

---

Q: How do I switch models mid-session?

Press Ctrl + O in the TUI to open the model picker. It lists all models from your configuration and a bundled catalog of 121+ models. Select one and the switch is instant — no restart needed.

---

Q: How much does it cost to use ClawCode?

Costs depend entirely on your LLM provider. ClawCode tracks usage at every level:

What's Tracked	Where to See It
Per-message tokens (input + output)	/usage command
Per-session accumulation	Session panel (Ctrl + A)
Per-turn live tokens	HUD status bar
Estimated cost in USD	/usage command

Tip: Use smaller models (Haiku, GPT-4o-mini) for title generation and summarization to save costs:

{
  "agents": {
    "title": { "model": "claude-3-5-haiku-20241022", "max_tokens": 100 },
    "summarizer": { "model": "claude-3-5-haiku-20241022", "max_tokens": 4096 }
  }
}

---

Q: What happens when I run out of context window?

ClawCode handles this automatically. When your conversation reaches ~70% of the model's context window:

1. The agent flushes important facts to persistent memory first
2. A dedicated summarizer agent compresses older messages into a compact summary
3. The most recent messages are kept intact
4. The conversation continues seamlessly

You can also trigger this manually with /compact.

---

Development Workflow

Q: How do I start a coding session?

# Interactive TUI mode
clawcode

# Then just type what you want:
> "Fix the authentication bug in src/auth.py"
> "Add unit tests for the payment module"
> "Refactor the database connection pool"

Or use non-interactive mode for scripting:

clawcode -p "Add error handling to all API endpoints" -f json

---

Q: What is Plan mode and when should I use it?

Plan mode (/plan) restricts the agent to read-only operations — it can search, read, and analyze your code but cannot modify anything.

Use it when:

• You want the agent to understand a codebase before making changes
• You need a plan or architecture review without risking modifications
• You're exploring unfamiliar code

/plan Analyze the microservices architecture and suggest improvements

The agent will research your codebase, produce a structured plan, and save it to .claw/plans/ — but won't touch a single file.

---

Q: What is Spec mode?

Spec mode (/spec) is a structured three-phase workflow:

Phase	Access	What Happens
Pending	Read-only	Agent analyzes the codebase and produces a specification
Executing	Full access	Agent implements the specification
Verifying	Test-only	Agent runs tests and validates the work

This produces a complete artifact bundle:

File	Purpose
spec.md	Detailed specification
tasks.md	Task breakdown with dependencies
checklist.md	Acceptance criteria with auto-verify commands
meta.json	Machine-readable structured data

---

Q: What is Claw mode?

Claw mode (/claw) is a lightweight autonomous agent with full tool access and an iteration budget. It's perfect for well-defined tasks where you want the agent to work independently:

/claw Refactor the user service to use dependency injection

The agent will iterate, search, edit, and test until the budget is exhausted or the task is complete. Unlike Plan mode, it can modify files. Unlike Spec mode, it doesn't produce formal artifacts — it just gets the job done.

---

Q: Can I undo the agent's changes?

Yes! Use the /rewind command to restore all modified files to their git HEAD state:

/rewind

This is safe because:

• It only touches tracked files (never deletes new untracked files)
• It uses git restore under the hood
• Changes are stashed first (recoverable if needed)

---

Q: Can I use ClawCode in my CI/CD pipeline?

Yes! The non-interactive mode (-p flag) is designed for automation:

# Generate a security review report
clawcode -p "Review the codebase for security vulnerabilities" -f json | jq .response

# Check code quality
clawcode -p "Run linting and report issues" -q

# Generate documentation
clawcode -p "Generate API documentation from the route definitions"

Output formats: text (default) or json ({"response": "..."}).

---

Collaboration & Teams

Q: Can ClawCode work with multiple AI agents at once?

Yes! This is one of ClawCode's most powerful features. Three built-in team commands:

Command	Team Size	Focus
/clawteam	14 engineering roles	Full engineering lifecycle
/designteam	6 design roles	Product design workflows
/research team	8 research roles	Academic/technical investigation

Example:

/clawteam Build an order management system with audit logging

This dispatches multiple AI specialists — architect, backend engineer, QA, etc. — to collaborate on your task. Each role has its own tool permissions and expertise.

---

Q: What engineering roles are available in ClawTeam?

Role	Specialty	Can Modify Code?
Product Manager	Strategy, scope, acceptance	No
Business Analyst	Requirements, stakeholder alignment	No
System Architect	Architecture, trade-offs	No
UI/UX Designer	User flows, interaction design	No
Dev Manager	Execution planning	No
Team Lead	Cross-role coordination	No
Backend Engineer	Backend implementation	Yes
Frontend Engineer	Frontend implementation	Yes
Mobile Engineer	Mobile development	Yes
DevOps	CI/CD, infrastructure	Yes
QA Engineer	Testing, quality validation	Yes
SRE	Reliability, observability	Yes
Project Manager	Scheduling, governance	No
Scrum Master	Agile process	No

---

Q: What is Saddle?

Saddle is ClawCode's standalone collaboration framework that turns a one-line requirement into a complete project roadmap through a three-stage pipeline:

spec → design → develop

Stage	What Happens	Output
Spec	Clarify scope and split work	spec.md, tasks.md, checklist.md
Design	DesignTeam creates design	Full design documentation
Develop	ClawTeam implements	Engineering execution

Run it with:

saddle run "Build an order system with audit logging" --mode fast

Saddle also includes Saddle Studio — a browser-based visual editor for configuring collaboration modes.

---

Q: What is "deep loop" and when should I use it?

Deep loop is an iterative convergence mechanism for team commands. When enabled, the team runs multiple iterations until quality thresholds are met.

/clawteam --deep_loop --max_iters 10 Refactor the payment module

Each iteration:

1. Inspects the previous outcome
2. Deepens the design and architecture
3. Expands implementation scope
4. Evaluates convergence (delta score, critical risks)

The loop stops when gap_delta falls below the threshold for consecutive rounds.

When to use deep loop:

• Complex refactoring requiring multiple passes
• Tasks where quality is more important than speed
• Situations where initial attempts may miss edge cases

---

Q: Can I define custom agent roles?

Yes! Create a Markdown file with YAML frontmatter in .claw/agents/:

---
name: my-security-reviewer
description: Security-focused code reviewer
tools: [Read, Glob, Grep, Bash]
---

You are a security-focused code reviewer. Analyze the codebase for:
- Authentication vulnerabilities
- Input validation gaps
- SQL injection risks
- XSS attack surfaces
Provide specific file paths and line numbers for each finding.

Your custom agents override built-in ones with the same name. The merge order is:

Built-in agents → ~/.claude/agents/ → .claw/agents/ (highest priority)

---

Themes & UI Customization

Q: Can I customize the look of ClawCode?

Absolutely! ClawCode offers 8 themes and 6 display modes:

Themes (color palettes):

Theme	Vibe
Yellow (default)	Warm amber on dark charcoal
Catppuccin	Pastel macaron tones
Dracula	Vibrant purple/cyan
Gruvbox	Retro warm tones
Monokai	Classic editor palette
One Dark	Atom-inspired balance
Tokyo Night	Japanese serene aesthetics
Light	Bright mode for well-lit environments

Display modes (layouts):

Mode	Layout
OpenCode (default)	No sidebar, right panel, bottom HUD
ClawCode	Neutral blue-gray tones
Claude	Full-width, Anthropic orange accent
Classic	Left sidebar + top status bar
Minimal	Messages + input only
Zen	Centered narrow column, maximum focus

Switch with Ctrl + T (theme) or Ctrl + D (display mode).

---

Q: What are the 54 brand design catalogs?

ClawCode includes design language references from 54 world-class brands (Apple, Stripe, Vercel, Figma, Notion, etc.). When you ask ClawCode to generate UI code, it can automatically match the best brand style using an AI-driven TF-IDF engine.

This means you can say:

"Build a dashboard with a Stripe-like design language"

And ClawCode will reference Stripe's actual design tokens, typography, and component patterns.

---

Learning & Evolution

Q: Does ClawCode learn from my usage?

Yes — this is one of its most unique features. ClawCode implements a three-layer learning system:

Layer	What It Learns
Instinct	Atomic preferences: coding style, formatting rules, tool choices
ECAP	Problem-solving workflows: structured traces of how problems were solved
TECAP	Team collaboration patterns: how multi-agent teams coordinate

The more you use ClawCode, the smarter it gets — without any manual configuration.

---

Q: How does the learning system work?

Every session → observations recorded
    ↓
Autonomous cycle analyzes patterns
    ↓
Recurring patterns → instincts (confidence: 0.5)
    ↓
Successful workflows → ECAP capsules (structured traces)
    ↓
Team collaborations → TECAP capsules (coordination patterns)
    ↓
Future sessions automatically apply relevant experience
    ↓
Feedback reinforces or fades knowledge

Key behaviors:

• Confidence scoring: Each piece of knowledge has a 0–1 confidence score
• Decay: Unused knowledge fades at 3% per day
• Reinforcement: Successful applications increase confidence (+0.04)
• Penalty: Failures decrease confidence more (-0.048, 1.2× penalty)
• Quality gates: Only validated knowledge gets promoted

---

Q: What is the autonomous learning cycle?

The autonomous cycle is a 7-stage pipeline that runs periodically:

Stage	Purpose
Observe	Consume raw observations from session logs
Analyze	Cluster observations, identify patterns
Evolve	Promote patterns to instincts and skills
Import	Make evolved artifacts available to agents
Report	Generate quality reports and metrics
Tuning	Apply feedback-based parameter adjustments
Export	Export reports and capsules for review

# Run manually (dry run by default)
clawcode-autonomous-cycle --cwd /path/to/project

# Full run (with writes)
clawcode-autonomous-cycle --no-dry-run

---

Q: Will ClawCode forget what it learned?

Knowledge decays gradually if not reinforced:

• Confidence decreases by 3% per day for unused instincts
• But it never drops below a 20% floor
• A single successful application restores and boosts confidence

You can also manually reinforce knowledge:

/experience-feedback ecap-xxxx --result success --score 0.9

---

Q: Can I share learned experience between projects?

Yes! Export and import capsules:

# Export from project A
/experience-export ecap-xxxx --format json

# Import into project B
/experience-import ./ecap.json

Team experiences (TECAPs) can also be shared:

/team-experience-export tecap-xxxx --v1-compatible
/team-experience-import ./tecap.json

---

Privacy & Security

Q: Is my code sent to AI providers?

Yes — when the agent processes your requests, relevant code snippets are sent to your configured LLM provider's API. This is how all AI coding assistants work. You control which provider to use and can choose self-hosted models if data privacy is a concern.

---

Q: Does ClawCode store my API keys securely?

API keys are stored in .clawcode.json config files. Best practices:

• Never commit .clawcode.json to version control (add to .gitignore)
• Use environment variables instead of config files when possible
• The learning system redacts sensitive data (API keys, tokens, file paths) from experience capsules

---

Q: What about prompt injection attacks?

ClawCode's memory system actively scans for injection attempts before storing any user-provided content:

Threat Pattern	Risk Level
"ignore previous instructions"	Prompt injection
"you are now..."	Role hijack
"disregard your instructions"	Rule override
curl ... $SECRET	Credential exfiltration

Detected threats are rejected before storage.

---

Q: What data does the learning system collect?

Collected	Not Collected
Tool call sequences	Your API keys
Success/failure outcomes	File contents (in capsules)
Problem types and patterns	Personal information
Performance metrics	Credentials

All learning data is stored locally in .clawcode/learning/ — nothing is sent to external servers.

---

Integrations & Extensibility

Q: Does ClawCode support MCP (Model Context Protocol)?

Yes! ClawCode implements a full MCP client:

Feature	Description
Stdio transport	Connect to local MCP server subprocesses
SSE transport	Connect to remote HTTP-based MCP servers
Dynamic management	Add/remove servers at runtime
Tool discovery	Auto-discover tools from connected servers

MCP tools become available to all agents during team orchestration — your custom MCP servers (database clients, API gateways, internal tools) become part of the team's toolkit.

---

Q: Can I use ClawCode with my existing tools?

Integration	How It Works
LSP	30+ language servers for real-time diagnostics and symbol info
Git/GitHub	PR review, diff generation, /rewind undo
Browser	Full browser automation for testing and scraping
Docker	Containerized code execution
SSH	Remote server execution
Plugins	Claude Code-compatible plugin system

---

Q: Does ClawCode work with my favorite editor?

ClawCode is terminal-native — it runs in any terminal emulator, so it works alongside any editor. You can also use the non-interactive mode for editor integration:

# Vim/Neovim integration example
:!clawcode -p "Fix the function under the cursor" -c %:p:h

---

Q: Can I write plugins for ClawCode?

Yes! ClawCode has a Claude Code-compatible plugin system supporting:

Plugin Feature	Description
Skills	Reusable prompt templates and workflows
Hooks	Lifecycle events (SessionStart, UserPromptSubmit, Stop)
MCP Servers	Inject external tool servers
LSP Servers	Inject language server integrations
Slash Commands	Custom namespaced commands

Plugins can be installed from: local directories, GitHub repos, git URLs, npm, or pip.

---

Troubleshooting

Q: ClawCode won't start — what should I check?

1. Python version: Ensure Python 3.12+

   python --version

2. API key: Verify your .clawcode.json has a valid provider API key

3. Config file location: ClawCode looks for config in:

   • ./.clawcode.json (current directory)
   • ~/.clawcode.json (home directory)

4. Dependencies: Reinstall if needed:

   pip install -e ".[dev]"

---

Q: The agent seems slow — how can I speed it up?

Optimization	How
Use a faster model	Switch to Haiku or GPT-4o-mini for simple tasks (Ctrl + O)
Use a faster provider	Groq offers ultra-fast inference
Reduce context	Use /compact to compress conversation history
Use compact prompt profile	In Saddle: prompt_profile: compact
Use fast mode	In Saddle: --mode fast (12-iteration cap, compact prompts)

---

Q: The agent made a mistake — how do I fix it?

1. Undo immediately: /rewind restores files to git HEAD
2. Give feedback: Help the learning system improve

   /experience-feedback ecap-xxxx --result failure --score 0.3
   

3. Be more specific: Add constraints to your request
4. Use Plan mode first: Let the agent research before acting (/plan)
5. Use Spec mode: Get a structured plan before implementation (/spec)

---

Q: How do I reset everything and start fresh?

# Remove all learning data
rm -rf .clawcode/learning/

# Remove all runtime state
rm -rf .clawcode/

# Remove config
rm .clawcode.json

This gives you a completely clean slate. The agent will start learning from scratch.

---

Comparison & Alternatives

Q: How is ClawCode different from Claude Code?

Feature	ClawCode	Claude Code
Architecture	Open-source, extensible platform	Proprietary, closed
Provider support	9+ providers, 100+ models	Anthropic only
Team orchestration	14 engineering + 6 design + 8 research roles	Single agent
Learning system	Three-layer (Instinct → ECAP → TECAP)	None
UI customization	8 themes × 6 display modes	Limited
Brand design	54 brand catalogs with AI matching	None
Plugin system	Claude Code-compatible plugins	Built-in only
Pipeline framework	Saddle (spec → design → develop)	None

ClawCode is Claude Code-compatible — it can read .claude/ directories and use Claude Code plugins.

---

Q: How is ClawCode different from Cursor?

Feature	ClawCode	Cursor
Interface	Terminal-native (TUI)	Desktop GUI editor
Agent types	28+ specialized roles	General-purpose
Multi-agent	Built-in team orchestration	Limited
Self-improvement	Autonomous learning cycle	None
Extensibility	Plugin system, MCP, custom agents	Extensions
Cost	Bring your own API key	Subscription-based

ClawCode is for developers who prefer the terminal and want deeper AI collaboration than GUI tools offer.

---

Q: Who is ClawCode for?

You Might Love ClawCode If...	ClawCode May Not Be For You If...
You live in the terminal	You prefer GUI-based tools
You work on complex, multi-file projects	You only need quick code snippets
You want AI that learns your style	You don't want any data stored
You need multi-model flexibility	You're happy with a single provider
You build teams of AI specialists	You only need single-agent chat
You value open-source and extensibility	You want a managed, zero-config solution

---

Q: Where can I learn more?

Resource	Location
Project README	Root README.md
Aesthetic Design Guide	docs/wiki/Aesthetic-Design.en.md
Collaboration Guide	docs/wiki/Collaboration.en.md
Development Guide	docs/wiki/Development.en.md
Evolution Guide	docs/wiki/Evolution.en.md
Architecture Decisions	docs/adr/
Saddle Documentation	saddle/README.en.md
ECAP User Guide	docs/ECAP_v2_USER_GUIDE.md
TECAP Upgrade Guide	docs/TECAP_v2_UPGRADE.md

---

ClawCode — Creative Engineering Cockpit for Serious AI Builders

Questions not answered here? Open an issue or start a discussion on GitHub.