Quickstart (60 seconds)
-
1. Install
pip install clouvel
-
2. Add to Claude Code
clouvel setup
# This single command:
- Adds can_code auto-call rule to ~/.claude/CLAUDE.md
- Runs: claude mcp add clouvel
-
3. Start coding
# Claude Code automatically calls can_code before writing code
No PRD → BLOCK (coding blocked)
PRD exists → PASS (start coding)
Pro users: After purchase, run
activate_license
in Claude Code to unlock 10 additional Pro tools.
Architecture
Clouvel is an MCP (Model Context Protocol) server. It provides tools to Claude Code for error memory, spec gating, and blind spot detection.
// System Architecture
How it works
MCP Server Start
When Claude Code starts, Clouvel MCP server launches via stdio.
Tool call
Before coding, Claude calls can_code to check specs.
Document check
Checks local filesystem for PRD.md and required docs.
Result
Returns BLOCK (no docs), WARN (partial), or PASS (ready to code).
System Requirements
Runtime
- ✓ Python 3.10+
- ✓ Claude Code CLI (latest)
- ✓ pip / pipx
OS Support
- ✓ Windows 10/11
- ✓ macOS 12+
- ✓ Linux (Ubuntu 20.04+)
Dependencies
# clouvel
mcp>=1.0.0
pydantic>=2.0.0
Installation
# pip
pip install clouvel
# pipx (isolated)
pipx install clouvel
Free users get 10 tools immediately. Pro users run
activate_license
to unlock 10 more.
Integration
1 Claude Code
# Register
claude mcp add clouvel
# Verify
/mcp
# ~/.claude.json result
{
"mcpServers": {
"clouvel": {
"type": "stdio",
"command": "clouvel",
"args": []
}
}
}
2 Claude Desktop
// claude_desktop_config.json
{
"mcpServers": {
"clouvel": {
"command": "clouvel",
"args": [],
"env": {
"PROJECT_PATH": "/path/to/project"
}
}
}
}
3 VS Code / Cursor
// .vscode/mcp.json or Cursor settings
{
"servers": {
"clouvel": {
"command": "clouvel",
"type": "stdio"
}
}
}
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
| CLOUVEL_DEV_MODE | false | Dev mode (skip license validation) |
| CLOUVEL_LICENSE_PATH | ~/.clouvel-license | License file path |
API Reference: Free Tools (10)
Always available. No license required.
can_code
Spec gate (BLOCK / WARN / PASS)
Checks if required docs exist before allowing coding. Must be called before writing code.
# Parameters
path: str - docs folder path
# Returns
BLOCK - No PRD, coding blocked
WARN - PRD exists but missing recommended docs
PASS - All docs ready, start coding
Example output
Status: BLOCK
No PRD found in docs/
Checked: docs/PRD.md, docs/prd.md, docs/requirements.md
Action: Create a PRD first.
Run: start(path="/your/project", init=true)
start
Project onboarding + PRD generation
Auto-detects project type and generates PRD template. Includes --template, --guide, --init options.
# Parameters
path: str - project root path
template: str (optional) - web-app, api, cli, generic
layout: str (optional) - lite, standard, detailed
guide: bool (optional) - show PRD writing guide
init: bool (optional) - initialize docs folder
save_prd
Save PRD content
Saves PRD written through conversation with Claude.
# Parameters
path: str - project path
content: str - PRD content (markdown)
error_check
Pre-emptive error warning
Checks past error patterns before code modification. Warns if similar mistakes were made before.
# Parameters
path: str - project root
context: str - current work context
file_path: str (optional) - file being modified
error_record
Record errors with 5 Whys analysis
Records errors with structured root cause analysis. Generates prevention rules.
# Parameters
path: str - project root
error_text: str - error message
root_cause: str (optional) - root cause
five_whys: list (optional) - 5 Whys analysis
context_save
Context checkpoint
Saves working state before context compression. One call captures everything for recovery.
# Parameters
path: str - project root
reason: str (optional) - why saving
active_files: list (optional) - files being worked on
context_load
Context restore
Loads context from checkpoint after compression or new session.
# Parameters
path: str - project root
checkpoint: str (optional) - "latest" or specific filename
quick_perspectives
Quick blind spot check
3-4 managers ask key questions in 10 seconds. Surfaces blind spots before you code.
# Parameters
context: str - what you're about to build
max_managers: int (optional) - max 4
gate
lint → test → build automation
Sequential quality gate. Stops at first failure.
# Parameters
path: str - project root
steps: list (optional) - ["lint", "test", "build"]
fix: bool (optional) - auto-fix lint errors
license_status
License management
Check license status, activate license, or start free trial.
# Parameters
license_key: str (optional) - for activation
action: str (optional) - "trial" to start 7-day trial
API Reference: Pro Tools (10)
Requires Pro license ($7.99/mo or $49/yr). 7-day free trial available.
What Pro delivers
error_learn
Learn from error patterns
Analyzes error history, generates NEVER/ALWAYS rules, auto-updates CLAUDE.md.
# Parameters
path: str - project root
auto_update_claude_md: bool (optional)
Example output
# Error Learning Analysis
Pattern Analysis:
import_error 3x Learning needed
null_check 2x Observing
CLAUDE.md Updated:
+ NEVER: import from deleted module
+ ALWAYS: validate query result before .data access
Learned: 2 rules · Analyzed: 5 errors
memory_status
Regression memory stats
Shows active memories, hit counts, save rates, and top error patterns.
memory_search
Search regression memories
Full-text search on root causes, prevention rules, and task descriptions.
# Parameters
path: str - project root
query: str - search keyword
memory_global_search
Cross-project memory
Search patterns learned across all your projects. Mistakes from project A prevent repeats in project B.
drift_check
Context drift detection
Detects if current work deviates from original goals. Compares recent actions against plan.
record_decision
Record decisions to knowledge base
Persists decisions across sessions. Supports locking to prevent changes.
# Parameters
category: str - architecture, pricing, security, etc.
decision: str - the decision made
reasoning: str (optional) - why
locked: bool (optional) - prevent changes
search_knowledge
Search knowledge base
Find past decisions, code locations, and context. FTS5 full-text search.
plan
Execution plan generation
Generates detailed execution plan with phases, action items, dependencies, and verification points.
# Parameters
path: str - project root
task: str - task to perform
goals: list (optional) - goals to achieve
meeting
C-Level meeting simulation
8 AI managers (PM, CTO, QA, CSO, CDO, CMO, CFO, Error) ask tough questions. They don't give answers — they surface blind spots.
# Parameters
context: str - meeting topic/situation
topic: str (optional) - auth, api, payment, ui, etc.
managers: list (optional) - specific managers
Example output
# C-Level Meeting: Auth System
Topic: auth · Managers: PM, CTO, CSO, QA
PM: "What happens when the token expires mid-session?"
CTO: "Are we hashing passwords with bcrypt or argon2?"
CSO: "Rate limiting on login? Brute force is day-one risk."
QA: "Edge case: user logs in on two devices simultaneously?"
4 managers · 8 blind spots surfaced
ship
One-click verify + evidence
Runs lint → typecheck → test → build sequentially. Generates evidence file on success.
# Parameters
path: str - project root
feature: str (optional) - feature to verify
steps: list (optional) - ["lint", "typecheck", "test", "build"]
auto_fix: bool (optional) - fix lint errors
Example: generated evidence file
# .claude/evidence/auth-refactor_20260215_143012.md
## Ship Evidence
Project: my-app Feature: auth-refactor
Generated: 2026-02-15T14:30:12 Status: PASS
| Step | Command | Status | Time |
|------|---------|--------|------|
| Lint | ruff check . | PASS | 340ms |
| Typecheck | mypy src/ | PASS | 2.1s |
| Test | pytest | PASS (48 passed) | 4.7s |
| Build | npm run build | PASS | 8.2s |
Conclusion: Ready to ship.
Security Model
- 1. Local execution - All document checks and gates run locally
- 2. License only - Only license validation contacts the server
- 3. No code uploaded - Your code and docs never leave your machine
Data Privacy
- ✓ Local execution: All checks run on your machine. No code or docs sent to any server.
- ✓ License only: Server communication is limited to license key validation.
- ✓ Offline after activation: Pro license activation needs internet once. Everything works offline after that.
Network Communication
| Endpoint | Purpose | Data Sent |
|---|---|---|
| /api/validate | License validation | license_key, machine_id |
What is machine_id?
- • SHA-256 hash of your hardware fingerprint (CPU, hostname, OS). Not reversible.
- • Used only to bind your license to one device (prevents sharing).
- • No personal data is included — no IP, no username, no file paths.
- • Device change? machine_id resets automatically within 24–48 hours. Contact GitHub Issues for immediate reset.
Licensing
Free vs Pro
| Free | Pro | |
|---|---|---|
| Price | $0 forever | $7.99/mo or $49/yr |
| Tools | 10 | 10 + 10 = 20 |
| Error Memory | Record + Check | + Learn + Search + Cross-project |
| Manager Review | Quick Perspectives | + Full Meeting (8 managers) |
| Trial | - | 7 days free, no card required |
Activation Flow
1. Purchase at polar.sh/clouvel
↓
2. In Claude Code: activate_license YOUR_KEY
↓
3. Server validates via Polar.sh API
↓
4. License cached locally (~/.clouvel-license)
↓
5. 10 Pro tools unlocked. Works offline.
Free Trial
Try all 20 tools free for 7 days. No credit card required.
# In Claude Code
license_status action="trial"
Troubleshooting
Common issues and how to fix them.
•
clouvel: command not found
The clouvel command is not in your PATH after pip install.
# Windows - use Python module syntax
py -m clouvel install
# Mac/Linux - use python3
python3 -m clouvel install
# Or install with pipx (adds to PATH automatically)
pipx install clouvel
•
claude mcp add clouvel fails
Claude Code cannot find the Clouvel executable.
# 1. Check where clouvel is installed
pip show clouvel
# 2. Use full path in claude mcp add
claude mcp add clouvel -- py -m clouvel
# 3. Verify it's registered
claude mcp list
• Python version error
Clouvel requires Python 3.10 or higher.
# Check your Python version
python --version
# If below 3.10, upgrade Python first
# Download from python.org or use your package manager
• Pro license activation fails
License validation server is unreachable or key is invalid.
# 1. Check internet connection
# 2. Verify your license key (check Polar.sh email)
# 3. Try again
activate_license YOUR_KEY
# Still failing? Open a GitHub Issue with your key
• Windows path issues
Backslashes in Windows paths can cause issues with some tools.
# Use forward slashes in path arguments
can_code path="D:/myproject/docs"
# Or use raw strings
can_code path="D:\\myproject\\docs"
•
can_code always returns BLOCK
No PRD found in the expected location.
# 1. Create a docs folder with a PRD
start path="/your/project" init=true
# 2. Or save a PRD from conversation
save_prd path="/your/project" content="# My PRD\n..."
# 3. Make sure path points to project root, not docs/
Still stuck? Open an issue at GitHub Issues or use the contact form. We typically respond within 24–48 hours.
Changelog
- - Reboot: 10 Free + 10 Pro clean architecture
- - Simplified pricing: $7.99/mo or $49/yr (Early Adopter Pricing)
- - Tier gating: Defense-in-depth (list_tools + call_tool)
- - Ghost data: Pro teasers for free users on error tools
- - CTA unification: Single trial CTA across all messages
- - Tool consolidation: 52 tools → 12 standard tools
- - Deprecation warnings for old tools
- - Knowledge Base: record_decision, search_knowledge
- - Error Learning: regression memory, pattern detection
- - Quick Perspectives: 10-second blind spot check
- - 8 C-Level manager meeting simulation
- - Ship: one-click verify + evidence
- - Project onboarding (start tool)
- - Initial release
- - can_code spec gate (BLOCK / WARN / PASS)
- - PRD-based coding gate