clauxton 0.11.2

Context that persists for Claude Code - Knowledge Base, Task Management, and Conflict Detection

Clauxton

Context that persists for Claude Code

✅ Production Ready: Clauxton v0.11.1 is stable and ready for production use. Complete with Repository Map (12-language support), TF-IDF search, task management, conflict detection, and comprehensive testing (1,367 tests, 85% coverage). 🚀 NEW v0.11.1 (2025-10-25): Daily Workflow Commands - morning briefing, daily/weekly summaries, trends analysis, pause/resume work tracking, unified search, and task add --start for instant focus! 🎯 v0.11.0 (2025-10-24): Repository Map - Multi-language symbol extraction (12 languages), 3 search modes (exact/fuzzy/semantic), 441 intelligence tests! ✨ v0.10.0 (2025-10-22): Bulk operations, undo functionality, human-in-the-loop confirmations, and 22 MCP tools!

Clauxton is a Claude Code plugin that provides persistent project context to solve AI-assisted development pain points.

Vision (Roadmap):

1. ✅ Session Context Loss → Persistent Knowledge Base with TF-IDF Search (Phase 0-1 - Complete)
2. ✅ Manual Dependency Tracking → Auto-inferred task dependencies (Phase 1 - Complete)
3. ✅ Post-hoc Conflict Detection → Pre-merge conflict prediction (Phase 2 - Complete)
4. ✅ Manual CLI Operations → Enhanced UX with Bulk Operations & Undo (Phase 3 - Complete in v0.10.0)

---

🎯 Quick Start

Install from PyPI (Recommended)

# Basic installation (fast, ~30 seconds)
pip install clauxton

# Or install with language parsers for Repository Map:
pip install clauxton[parsers-python]       # Python only
pip install clauxton[parsers-web]           # JavaScript/TypeScript/PHP
pip install clauxton[parsers-systems]       # Go/Rust/C++
pip install clauxton[parsers-enterprise]    # Java/C#/Kotlin
pip install clauxton[parsers-all]           # All 12 languages (~2 minutes)

# Verify installation
clauxton --version  # Should show: clauxton, version 0.11.1

Note: Language parsers are optional. Install only what you need for your project.

Basic Usage

⚡ Quick Start (Recommended)

# All-in-one setup - initialize, index, and configure MCP
cd your-project
clauxton quickstart

# Done! Your project is ready with:
# ✓ Knowledge Base initialized
# ✓ Codebase indexed (Repository Map)
# ✓ MCP server configured for Claude Code

# Optional: Skip certain steps
clauxton quickstart --skip-mcp     # Skip MCP setup (run later)
clauxton quickstart --skip-index   # Skip indexing (run later)

📋 Manual Setup (Step-by-Step)

# Step 1: Initialize in your project
cd your-project
clauxton init

# Step 2: Index your codebase (Repository Map)
clauxton repo index
# → Indexed 50 files, found 200 symbols (Python, TypeScript, JavaScript)

# Step 3: Setup MCP server for Claude Code
clauxton mcp setup              # Auto-configure MCP server
clauxton mcp status             # Check MCP configuration

# Step 4: Check overall project status
clauxton status                 # Repository Map, Tasks, KB, MCP - all in one

🔧 Daily Usage

# 🌅 Start your day (v0.11.1 NEW!)
clauxton morning
# → Shows yesterday's wins, suggests today's tasks, sets focus interactively

# ✅ Add and start a task immediately (v0.11.1 NEW!)
clauxton task add --name "Implement API" --start
# → Creates task and sets focus in one command

# ⏸️  Take a break (v0.11.1 NEW!)
clauxton pause "Meeting"
# → Records interruption with reason

clauxton pause --history
# → View all pause history and statistics

# 🔄 Resume work (v0.11.1 NEW!)
clauxton resume
# → Shows where you left off and suggests next actions

clauxton resume --yesterday
# → Also shows yesterday's activity for context

# 🔍 Unified search (v0.11.1 NEW!)
clauxton search "authentication"
# → Searches KB, Tasks, and Files all at once

clauxton search "API" --kb-only --limit 10
# → Search with filters and custom limits

# 📊 Daily summary (v0.11.1 NEW!)
clauxton daily
# → End-of-day review: completed tasks, time tracking, next actions

clauxton daily --date 2025-10-24
# → View specific date

clauxton daily --json
# → JSON output for integrations

# 📈 Weekly summary (v0.11.1 NEW!)
clauxton weekly
# → Week's accomplishments, velocity, trends

clauxton weekly --week -1
# → Last week's summary

# 📉 Productivity trends (v0.11.1 NEW!)
clauxton trends
# → 30-day productivity analysis with insights

clauxton trends --days 7
# → Last week's trends

# Add knowledge to your Knowledge Base
clauxton kb add
# Enter: Title, Category, Content, Tags

# Search with TF-IDF relevance ranking
clauxton kb search "FastAPI authentication"
# Results are ranked by relevance - most relevant first!

# Get next recommended task (AI-powered)
clauxton task next

# Search symbols across codebase
clauxton repo search "authenticate" --mode exact
# → authenticate_user (function) at auth.py:10-20
#   AuthService.verify (method) at auth.ts:45-60

clauxton repo search "user login" --mode semantic
# → Find symbols by meaning (requires scikit-learn)

# Undo last operation (v0.10.0 feature)
clauxton undo                   # Undo with confirmation
clauxton undo --history         # View operation history

# Configure confirmation mode (v0.10.0 feature)
clauxton config set confirmation_mode auto    # Balanced (default)
clauxton config set confirmation_mode always  # Maximum safety
clauxton config set confirmation_mode never   # Maximum speed
clauxton config list            # View all configuration

Install from Source (Development)

git clone https://github.com/nakishiyaman/clauxton.git
cd clauxton
pip install -e .

MCP Integration with Claude Code

Set up Clauxton as MCP tools in Claude Code (22+ tools available):

# 🆕 v0.11.0: Automatic setup with single command
clauxton mcp setup
# → Detects your platform and Python environment
# → Generates .claude-plugin/mcp-servers.json automatically
# → Ready in seconds!

# Check configuration status
clauxton mcp status

# Alternative: Manual setup (Linux/macOS)
./setup-mcp.sh

# Or see detailed guide
docs/MCP_INTEGRATION_GUIDE.md

With v0.10.0 (Released 2025-10-22), Claude Code uses Clauxton with enhanced features:

You: "Build a Todo app with FastAPI"

Claude Code: (Automatically creates 10 tasks via MCP, no manual commands needed)
             "Created 10 tasks. Starting with TASK-001: FastAPI setup"

You: "Sounds good!"

Claude Code: (Begins implementation)

No more manual CLI commands - just natural conversation! See CLAUDE.md for details.

---

✨ Features

• 🧠 Persistent Knowledge Base - Store architecture decisions, patterns, constraints across sessions
• 📋 Task Management - AI-powered task tracking with automatic dependency inference
• ⚠️ Conflict Detection - Predict file conflicts before they occur, get safe execution order
• 🔍 TF-IDF Search - Relevance-based search with intelligent ranking (powered by scikit-learn)
• 🗺️ Repository Map - ⭐ NEW v0.11.0: Automatic codebase indexing with symbol search (exact/fuzzy/semantic)
• 🔒 Privacy First - Local-only by default, no cloud dependencies
• 🤖 MCP Integration - Seamless integration with Claude Code via Model Context Protocol (22 tools)

✅ Core Features (v0.10.0)

🔍 TF-IDF Relevance Search

• ✅ Intelligent Ranking: TF-IDF algorithm ranks results by relevance (powered by scikit-learn)
• ✅ Automatic Fallback: Gracefully falls back to keyword search if scikit-learn unavailable
• ✅ Fast Performance: Validated with 200+ knowledge base entries
• ✅ Query Understanding: Understands multi-word queries and technical terms
• ✅ See: Search Algorithm Documentation

📚 Knowledge Base Management

• ✅ Persistent Context: Store architecture decisions, patterns, constraints, conventions
• ✅ Category System: 5 categories (architecture, constraint, decision, pattern, convention)
• ✅ YAML Storage: Human-readable, Git-friendly format
• ✅ CRUD Operations: Add, get, update, delete, list entries
• ✅ Version Management: Automatic versioning on updates
• ✅ Atomic Writes: Safe file operations with automatic backups
• ✅ Secure Permissions: 700/600 permissions for privacy

✅ Task Management System

• ✅ Full CRUD: Add, get, update, delete, list tasks
• ✅ Smart Dependencies: Auto-inferred from file overlap + manual dependencies
• ✅ DAG Validation: Cycle detection prevents circular dependencies
• ✅ Priority Management: 4 levels (Critical > High > Medium > Low)
• ✅ AI Recommendations: task next suggests optimal next task
• ✅ Progress Tracking: Track status (pending, in_progress, completed, blocked)
• ✅ Time Estimates: Optional hour estimates for planning

🚀 v0.10.0 Features (Transparent Integration)

Bulk Operations:

• ✅ YAML Bulk Import: Create multiple tasks from YAML file - 30x faster than manual
• ✅ KB Export: Export Knowledge Base to Markdown documentation
• ✅ Progress Display: Real-time progress bars for bulk operations (100+ items)

Safety & Recovery:

• ✅ Undo/Rollback: Reverse accidental operations with full history tracking
• ✅ Error Recovery: Transactional import with rollback/skip/abort strategies
• ✅ YAML Safety: Security checks to prevent code injection attacks
• ✅ Backup Enhancement: Automatic backups before every write operation (last 10 kept)
• ✅ Enhanced Validation: Pre-Pydantic validation with clear error messages

User Experience:

• ✅ Confirmation Prompts: Threshold-based warnings for bulk operations
• ✅ Configurable Confirmation Mode: Set HITL level (always/auto/never)
• ✅ Operation Logging: Structured logging with daily log files (30-day retention)
• ✅ Better Error Messages: Actionable errors with context + suggestion + commands
• ✅ Performance Optimization: 10x faster bulk operations

Total: 13 new features in v0.10.0

🗺️ Repository Map (v0.11.0 - Released 2025-10-24)

Automatic Codebase Intelligence:

• ✅ File Indexing: Recursive scanning with .gitignore support (1000+ files in <2s)
• ✅ Symbol Extraction: Functions, classes, methods, interfaces, types with signatures
• ✅ Multi-Language Support (12 languages):
  • Python ✅ Complete (functions, classes, methods, docstrings, type hints)
  • JavaScript ✅ Complete (ES6+, classes, arrow functions, async/await)
  • TypeScript ✅ Complete (interfaces, type aliases, generics, type annotations)
  • Go ✅ Complete (functions, methods, structs, interfaces, type aliases, generics)
  • Rust ✅ Complete (functions, methods, structs, enums, traits, type aliases, generics)
  • C++ ✅ Complete (functions, classes, structs, namespaces, templates)
  • Java ✅ Complete (classes, interfaces, methods, enums, annotations, constructors)
  • C# ✅ Complete (classes, interfaces, structs, methods, properties, records, extensions)
  • PHP ✅ Complete (classes, functions, methods, traits, enums, promoted properties, attributes)
  • Ruby ✅ Complete (classes, modules, methods, module mixins, singleton methods, attr_*)
  • Swift ✅ Complete (classes, structs, protocols, extensions, enums, init methods, properties)
  • Kotlin ✅ Complete (classes, data/sealed classes, interfaces, objects, companion objects, suspend functions)
• ✅ 3 Search Modes:
  • Exact: Fast substring matching with priority scoring
  • Fuzzy: Typo-tolerant using Levenshtein distance
  • Semantic: TF-IDF meaning-based search (requires scikit-learn)
• ✅ CLI Commands: repo index, repo search, repo status
• ✅ MCP Integration: index_repository(), search_symbols() tools
• ✅ Performance: 1000+ files/1-2s indexing, <0.01s search
• ✅ Storage: JSON format in .clauxton/map/ (~10-50KB per project)

Example Usage:

# Index your codebase (Python, JavaScript, TypeScript)
clauxton repo index
# → Indexed 50 files, found 200 symbols in 0.15s
#   - 15 Python files (50 functions, 20 classes)
#   - 20 TypeScript files (80 functions, 15 interfaces, 10 type aliases)
#   - 15 JavaScript files (40 functions, 10 classes)

# Search for functions
clauxton repo search "authenticate" --mode exact
# → authenticate_user (function) at auth.py:10-20
#   getAuthToken (function) at auth.ts:30-35
#   AuthService.verify (method) at auth-service.ts:45-60

# Search for TypeScript interfaces
clauxton repo search "User" --mode exact
# → User (interface) at types.ts:5-10
#   UserService (class) at user-service.ts:15-50
#   getUserById (function) at api.ts:100-110

# Semantic search by meaning
clauxton repo search "user login" --mode semantic
# → authenticate_user, verify_credentials, check_session...
#   AuthService, LoginRequest, validateToken...

Programming API:

from pathlib import Path
from clauxton.intelligence.symbol_extractor import (
    PythonSymbolExtractor,
    JavaScriptSymbolExtractor,
    TypeScriptSymbolExtractor,
    GoSymbolExtractor,
)

# Extract TypeScript symbols
ts_extractor = TypeScriptSymbolExtractor()
symbols = ts_extractor.extract(Path("src/types.ts"))

for symbol in symbols:
    print(f"{symbol['name']} ({symbol['type']}) at line {symbol['line_start']}")
    # Output:
    # User (interface) at line 5
    # AuthRequest (type_alias) at line 10
    # AuthService (class) at line 15

# Extract Go symbols
go_extractor = GoSymbolExtractor()
go_symbols = go_extractor.extract(Path("pkg/user.go"))

for symbol in go_symbols:
    if symbol['type'] == 'method':
        print(f"{symbol['name']} (method on {symbol['receiver']})")
    else:
        print(f"{symbol['name']} ({symbol['type']})")
    # Output:
    # User (struct)
    # GetName (method on *User)
    # SetName (method on *User)

Total: Week 1 complete (81 tests, 92%/90% coverage)

🔌 MCP Server Integration (22 Tools)

Knowledge Base Tools (7):

• ✅ kb_search - TF-IDF relevance-ranked search
• ✅ kb_add - Add new knowledge entry
• ✅ kb_list - List all entries (filterable by category)
• ✅ kb_get - Get entry by ID
• ✅ kb_update - Update existing entry
• ✅ kb_delete - Delete entry
• ✅ kb_export_docs - NEW v0.10.0: Export KB to Markdown docs

Task Management Tools (7):

• ✅ task_add - Create task with auto-dependency inference
• ✅ task_import_yaml - NEW v0.10.0: Bulk import tasks from YAML
• ✅ task_list - List tasks (filterable by status/priority)
• ✅ task_get - Get task details
• ✅ task_update - Update task fields
• ✅ task_next - Get AI-recommended next task
• ✅ task_delete - Delete task

Conflict Detection Tools (3):

• ✅ detect_conflicts - Detect file conflicts for a task
• ✅ recommend_safe_order - Get optimal task execution order
• ✅ check_file_conflicts - Check if files are being edited

Operation Management Tools (2) - NEW v0.10.0:

• ✅ undo_last_operation - Reverse accidental operations
• ✅ get_recent_operations - View operation history

Logging Tools (1) - NEW v0.10.0:

• ✅ get_recent_logs - View recent operation logs

Repository Map Tools (2) - ⭐ NEW v0.11.0:

• ✅ index_repository - Index codebase with symbol extraction
• ✅ search_symbols - Search symbols with exact/fuzzy/semantic modes

📊 Quality Metrics

• ✅ 1228 Tests - Comprehensive test coverage (758 → 1228, +470 tests in v0.11.0):
  • Core modules: 87-96% coverage (knowledge_base, task_manager, conflict_detector, etc.)
  • Intelligence modules: 91-92% coverage (repository_map, symbol_extractor, parser) - NEW v0.11.0
    • 441 intelligence tests covering 12 languages (Python, JS, TS, Go, Rust, C++, Java, C#, PHP, Ruby, Swift, Kotlin)
  • MCP server: 35% coverage (22 tools, all tested individually)
  • CLI modules: 84-100% coverage (main, tasks, conflicts, config, repository)
  • Utils modules: 15-29% coverage (targeted for future improvement)
• ✅ 91% Coverage - High code quality maintained across all modules
• ✅ Type Safe - Full Pydantic validation with strict mode
• ✅ Production Ready - Stable v0.11.0 release with 12-language Repository Map

⚠️ Conflict Detection

⚠️ Pre-merge Conflict Detection

• ✅ File Overlap Detection: Detects file conflicts between tasks
• ✅ Risk Scoring: Calculates risk (LOW <40%, MEDIUM 40-70%, HIGH >70%)
• ✅ Safe Execution Order: Recommends optimal task execution order
• ✅ File Availability Check: Check if files are currently being edited
• ✅ CLI Commands: conflict detect, conflict order, conflict check
• ✅ MCP Tools: Full integration for Claude Code

🔮 Future Enhancements

v0.11.0 Complete (Released 2025-10-24) ✅:

• ✅ Repository Map: 12-language symbol extraction
• ✅ 3 Search Modes: Exact, Fuzzy, Semantic
• ✅ 441 intelligence tests across all languages
• ✅ Performance: 1000+ files in 1-2s
• ✅ MCP Integration: 2 new tools (22 total)

v0.12.0 Roadmap (Planned):

• 📋 Line-Level Conflict Detection: Detect conflicts at code line level
• 📋 Drift Detection: Track scope expansion in tasks
• 📋 Enhanced Event Logging: Complete audit trail with events.jsonl
• 📋 Lifecycle Hooks: Pre-commit and post-edit hooks
• 📋 Web Dashboard: Browser-based UI for task/KB management

---

📦 Installation

PyPI Installation (Recommended)

# Install latest stable version (includes all features)
pip install clauxton

# Verify installation
clauxton --version  # Should show: clauxton, version 0.11.0

# Install specific version (example)
pip install clauxton==0.10.1

What's Included:

• ✅ Knowledge Base management (CRUD + TF-IDF search + Markdown export)
• ✅ Task Management system with auto-dependencies + YAML bulk import
• ✅ Conflict Detection (pre-merge conflict prediction)
• ✅ Undo/Rollback functionality with operation history
• ✅ Configurable confirmation modes (always/auto/never)
• ✅ Operation logging with 30-day retention
• ✅ Automatic backups (last 10 retained)
• ✅ MCP Server (22 tools for Claude Code)
• ✅ All dependencies (scikit-learn, numpy, pydantic, click, pyyaml, gitpython, mcp)

Development Installation

# Clone repository
git clone https://github.com/nakishiyaman/clauxton.git
cd clauxton

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate     # On Windows

# Install in editable mode
pip install -e .

# Run tests
pytest

Requirements

• Python: 3.11 or higher
• Dependencies (auto-installed with pip):
  • pydantic>=2.0 - Data validation
  • click>=8.1 - CLI framework
  • pyyaml>=6.0 - YAML parsing
  • gitpython>=3.1 - Git integration
  • mcp>=1.0 - MCP server
  • scikit-learn>=1.3 - TF-IDF search
  • numpy>=1.24 - Required by scikit-learn

Note on Search: Clauxton uses TF-IDF algorithm for intelligent relevance ranking. If scikit-learn is unavailable, it automatically falls back to keyword matching. See Search Algorithm for details.

---

🚀 Usage

Daily Workflow Commands (NEW v0.11.1)

# Quick project overview - See everything at a glance
clauxton overview
clauxton overview --limit 5  # Show 5 entries per category

# Resume work - Get back into context after a break
clauxton resume

# Project statistics - Understand project health
clauxton stats

Quick Add Shortcuts (NEW v0.11.1)

Faster than interactive commands - no prompts, just add!

# Quick Knowledge Base entries (10x faster)
clauxton add-architecture "Microservices" "Using Docker containers for each service"
clauxton add-decision "Use PostgreSQL" "Chosen for JSONB support" --tags database,backend
clauxton add-constraint "Max 1000 items" "API returns maximum 1000 items per request"
clauxton add-pattern "Repository Pattern" "All DB access through repositories"
clauxton add-convention "snake_case" "Use snake_case for Python variables"

# Quick task creation
clauxton quick-task "Setup backend"
clauxton quick-task "Fix authentication bug" --high
clauxton quick-task "Security patch CVE-2024-001" --critical

Knowledge Base Commands

# Initialize Clauxton in your project
clauxton init

# Add knowledge entry (interactive)
clauxton kb add

# Search Knowledge Base (TF-IDF relevance ranking)
clauxton kb search "architecture"          # Results ranked by relevance
clauxton kb search "API" --category architecture
clauxton kb search "FastAPI" --limit 5     # Limit to top 5 results

# List all entries
clauxton kb list
clauxton kb list --category decision

# Get entry by ID
clauxton kb get KB-20251019-001

# Update entry
clauxton kb update KB-20251019-001 --title "New Title"
clauxton kb update KB-20251019-001 --content "New content" --category decision

# Delete entry
clauxton kb delete KB-20251019-001
clauxton kb delete KB-20251019-001 --yes  # Skip confirmation

# Export Knowledge Base to Markdown docs (v0.10.0)
clauxton kb export --output-dir ./docs/kb

# Export as compact summary - Perfect for team onboarding! (NEW v0.11.1)
clauxton kb export --output-dir ./docs/kb --summary

Task Management Commands

# Add a new task
clauxton task add --name "Setup database" --priority high

# Add task with dependencies
clauxton task add \
  --name "Add API endpoint" \
  --depends-on TASK-001 \
  --files "src/api/users.py" \
  --estimate 3.5

# List all tasks
clauxton task list
clauxton task list --status pending
clauxton task list --priority high

# Get task details
clauxton task get TASK-001

# Update task
clauxton task update TASK-001 --status in_progress
clauxton task update TASK-001 --priority critical

# Get next recommended task (AI-powered)
clauxton task next

# Delete task
clauxton task delete TASK-001

# Bulk import tasks from YAML (NEW v0.10.0)
clauxton task import tasks.yml
clauxton task import tasks.yml --dry-run  # Validate without creating

YAML Bulk Import Example (tasks.yml):

tasks:
  - name: "Setup FastAPI project"
    priority: high
    files_to_edit:
      - main.py
      - requirements.txt
    estimated_hours: 2.5

  - name: "Create database models"
    priority: high
    depends_on:
      - TASK-001
    files_to_edit:
      - models/user.py
      - models/post.py
    estimated_hours: 3.0

  - name: "Write API tests"
    priority: medium
    depends_on:
      - TASK-002
    estimated_hours: 4.0

See YAML Task Format Guide for complete specification.

MCP Server Integration

The Clauxton MCP Server provides full Knowledge Base and Task Management for Claude Code:

// .claude-plugin/mcp-servers.json
{
  "mcpServers": {
    "clauxton": {
      "command": "python",
      "args": ["-m", "clauxton.mcp.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Knowledge Base Tools:

• kb_search(query, category?, limit?) - Search with TF-IDF relevance ranking
• kb_add(title, category, content, tags?) - Add new entry
• kb_list(category?) - List all entries
• kb_get(entry_id) - Get entry by ID
• kb_update(entry_id, title?, content?, category?, tags?) - Update entry
• kb_delete(entry_id) - Delete entry

Note: Search results are automatically ranked by relevance using TF-IDF algorithm. Most relevant entries appear first.

Task Management Tools:

• task_add(name, description?, priority?, depends_on?, files?, kb_refs?, estimate?) - Add task
• task_import_yaml(yaml_content, dry_run?, skip_validation?) - NEW v0.10.0: Bulk import tasks from YAML
• task_list(status?, priority?) - List tasks with filters
• task_get(task_id) - Get task details
• task_update(task_id, status?, priority?, name?, description?) - Update task
• task_next() - Get AI-recommended next task
• task_delete(task_id) - Delete task

See MCP Server Guide for complete documentation.

Conflict Detection Commands

# Check conflicts before starting a task
clauxton conflict detect TASK-001

# Get safe execution order for multiple tasks
clauxton conflict order TASK-001 TASK-002 TASK-003

# Check if specific files are being edited
clauxton conflict check src/api/users.py src/models/user.py

See Conflict Detection Guide for complete documentation.

Undo/History Commands (NEW v0.10.0)

# Undo last operation (with confirmation)
clauxton undo

# View operation history
clauxton undo --history
clauxton undo --history --limit 20  # Show last 20 operations

# Force undo without confirmation
clauxton undo --yes

See Error Handling Guide for recovery strategies.

Configuration Commands (NEW v0.10.0)

# Set confirmation mode
clauxton config set confirmation_mode always   # Strict (confirm every operation)
clauxton config set confirmation_mode auto     # Balanced (threshold-based, default)
clauxton config set confirmation_mode never    # Fast (no confirmations)

# Get configuration value
clauxton config get confirmation_mode

# List all configuration
clauxton config list

See Configuration Guide for all available settings.

Knowledge Base YAML Structure

After running clauxton kb add, your entries are stored in .clauxton/knowledge-base.yml:

version: '1.0'
project_name: my-project

entries:
  - id: KB-20251019-001
    title: Use FastAPI framework
    category: architecture
    content: |
      All backend APIs use FastAPI framework.

      Reasons:
      - Async/await support
      - Automatic OpenAPI docs
      - Excellent performance
    tags:
      - backend
      - api
      - fastapi
    created_at: '2025-10-19T10:30:00'
    updated_at: '2025-10-19T10:30:00'
    version: 1

Categories:

• architecture: System design decisions
• constraint: Technical/business constraints
• decision: Important project decisions with rationale
• pattern: Coding patterns and best practices
• convention: Team conventions and code style

See YAML Format Reference for complete schema documentation.

---

🏗️ Architecture

Current Architecture (v0.10.0)

clauxton/
├── core/                      # Core business logic
│   ├── models.py              # Pydantic data models ✅
│   ├── knowledge_base.py      # KB CRUD operations ✅
│   ├── task_manager.py        # Task lifecycle + DAG validation ✅
│   ├── search.py              # TF-IDF search implementation ✅
│   ├── conflict_detector.py   # Conflict detection ✅
│   ├── operation_history.py   # Undo/history tracking ✅
│   └── confirmation_manager.py # HITL confirmations ✅
├── utils/                     # Utility modules
│   ├── yaml_utils.py          # Safe YAML I/O ✅
│   ├── file_utils.py          # Secure file operations ✅
│   ├── backup_manager.py      # Backup management ✅
│   └── logger.py              # Operation logging ✅
├── cli/                       # CLI interface
│   ├── main.py                # Main CLI + KB commands ✅
│   ├── tasks.py               # Task management commands ✅
│   ├── conflicts.py           # Conflict detection commands ✅
│   └── config.py              # Configuration commands ✅
└── mcp/                       # MCP Server integration
    └── server.py              # 17 MCP tools ✅

Storage:

• .clauxton/knowledge-base.yml - Knowledge Base entries
• .clauxton/tasks.yml - Task definitions
• .clauxton/operation-history.jsonl - Operation history (undo)
• .clauxton/logs/ - Daily operation logs
• .clauxton/backups/ - Automatic backups (last 10)

See docs/architecture.md for complete design.

---

📚 Documentation

User Guides

• Quick Start Guide - Get started in 5 minutes (CLI)
• Developer Workflow Guide - Complete development workflow with examples and diagrams ✨ v0.10.0
• Installation Guide - Shell alias setup, virtual environment isolation explained
• MCP Integration Guide - Step-by-step Claude Code integration (22 tools)
• Tutorial: Your First Knowledge Base - 30-minute beginner guide
• Use Cases & Examples - Real-world scenarios and implementations
• MCP Server Quick Start - Get started with Claude Code
• Task Management Guide - Complete task management documentation
• YAML Task Format Guide - YAML bulk import specification ✨ v0.10.0
• Search Algorithm - TF-IDF search explanation
• YAML Format Reference - Complete Knowledge Base YAML specification
• MCP Server Guide - Complete MCP Server documentation
• Conflict Detection Guide - Complete conflict detection documentation
• Configuration Guide - Configuration management ✨ v0.10.0
• Logging Guide - Operation logging system ✨ v0.10.0
• Backup Guide - Backup management ✨ v0.10.0

Developer Guides

• Architecture Overview - System design and data flow
• Development Guide - Setup and contribution guide
• Technical Design - Implementation details (⚠️ Currently in Japanese, English version coming in v0.10.1)
• Error Handling Guide - Error handling patterns ✨ v0.10.0
• Performance Guide - Performance optimization ✨ v0.10.0
• Troubleshooting Guide - Common issues and solutions ✨ v0.10.0
• Contributing - Contribution guidelines

---

🧪 Testing

Clauxton has comprehensive test coverage (85%, 1,367 tests) with optimized execution time.

Quick Tests (Default - Recommended)

pytest  # ~2 minutes, 1,348 tests

Automatically excludes performance tests for fast feedback during development.

Performance Tests

pytest -m "performance"  # ~70 minutes, 19 tests

Run before releases or when optimizing performance. Also runs automatically every Sunday via CI.

All Tests

pytest -m ""  # ~80 minutes, 1,367 tests

Complete test suite including all performance tests.

Coverage Report

pytest --cov=clauxton --cov-report=html
open htmlcov/index.html  # View detailed coverage report

Test Statistics

• Total Tests: 1,367
• Default Tests: 1,348 (excludes 19 performance tests)
• Coverage: 85%
• CI Execution Time: ~5-8 minutes
• Performance Tests: Weekly (Sundays 02:00 UTC) + Manual trigger

CI/CD

• Push/PR: Runs default tests automatically (~8 minutes)
• Weekly Schedule: Performance tests every Sunday at 02:00 UTC
• Manual Trigger: Run performance tests via GitHub Actions "Run workflow" button

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

---

📄 License

MIT License - see LICENSE for details.

---

📊 Project Status

Phase	Status	Completion	Release
Phase 0: Foundation	✅ Complete	100%	v0.1.0
Phase 1: Core Engine	✅ Complete	100%	v0.8.0
Phase 2: Conflict Detection	✅ Complete	100%	v0.9.0-beta
Phase 3: Enhanced UX	✅ Complete	100%	v0.10.0 (Released 2025-10-22)
Phase 4: Repository Map	✅ Complete	100%	v0.11.0 (Released 2025-10-24)
Polish & Documentation	📋 Planned	0%	v0.12.0 (target)
v1.0 Public Launch	📋 Planned	0%	v1.0.0 (target)

Phase 1 Complete (v0.8.0 - Released 2025-10-19) ✅:

• ✅ Knowledge Base CRUD (6 MCP tools + CLI)
• ✅ TF-IDF Relevance Search (scikit-learn powered)
• ✅ Task Management (6 MCP tools + CLI)
• ✅ Auto Dependency Inference (file overlap detection)
• ✅ DAG Validation (cycle detection)
• ✅ Full Documentation (20 guides)
• ✅ 267 tests, 94% coverage

Phase 2 Complete (v0.9.0-beta - Released 2025-10-20) ✅:

• 🆕 Conflict Detection (file-based conflict prediction)
• 🆕 Risk Scoring (LOW/MEDIUM/HIGH)
• 🆕 Safe Execution Order (topological sort + conflict-aware)
• 🆕 3 CLI Commands (detect, order, check)
• 🆕 3 MCP Tools (15 tools total)
• 🆕 390 tests (+123), 94% coverage maintained
• 🆕 Comprehensive migration guide
• 🆕 Production ready release

Phase 3 Complete (v0.10.0 - Released 2025-10-22) ✅:

• 🆕 Bulk Task Import/Export (YAML format, 30x faster)
• 🆕 Undo Functionality (reverse operations, view history)
• 🆕 Human-in-the-Loop Confirmations (3 modes: always/auto/never)
• 🆕 KB Documentation Export (Markdown generation)
• 🆕 Enhanced Validation (YAML safety, dependency validation)
• 🆕 2 new MCP Tools (17 tools total: undo_last_operation, get_recent_operations)
• 🆕 758 tests (+368), 91% coverage achieved
• 🆕 13 comprehensive documentation files
• 🆕 Production ready, stable release

Phase 4 Complete (v0.11.0 - Released 2025-10-24) ✅:

• 🗺️ Repository Map - Automatic codebase intelligence
• 🆕 12-Language Support: Python, JavaScript, TypeScript, Go, Rust, C++, Java, C#, PHP, Ruby, Swift, Kotlin
• 🆕 Multi-Language Symbol Extraction: Functions, classes, methods, interfaces, types with full metadata
• 🆕 3 Search Modes: Exact (fast substring), Fuzzy (typo-tolerant), Semantic (TF-IDF meaning-based)
• 🆕 CLI Commands: repo index, repo search, repo status
• 🆕 2 new MCP Tools (22 tools total: index_repository, search_symbols)
• 🆕 Performance: 1000+ files in 1-2s indexing, <0.01s search
• 🆕 441 intelligence tests (12 languages, 91% coverage)
• 🆕 1,228 total tests (+470 from v0.10.0)
• 🆕 Production ready with comprehensive error handling

See CHANGELOG.md for detailed version history.

---

🔒 Security

Clauxton takes security seriously and follows industry best practices:

Security Measures

• Static Analysis: Automated security scanning with Bandit in CI/CD
• Safe YAML Loading: Uses yaml.safe_load() to prevent code execution
• Secure File Permissions:
  • .clauxton/ directory: 700 (owner only)
  • Data files: 600 (owner read/write only)
• Input Validation: All inputs validated with Pydantic models
• No Command Injection: No shell=True without sanitization
• Path Traversal Protection: All file operations validated against project root

Security Scanning Results

Latest scan (Session 8, 2025-10-21):

• Lines Scanned: 5,609
• Issues Found: 0
• Severity: MEDIUM or higher checked
• Status: ✅ PASSED

Reporting Security Issues

DO NOT create public issues for security vulnerabilities.

Instead, please:

1. Email security concerns to the maintainers
2. Include: description, reproduction steps, potential impact, suggested fix
3. We will respond within 48 hours

See SECURITY.md for detailed security guidelines.

---

🔗 Links

• PyPI: https://pypi.org/project/clauxton/
• GitHub: https://github.com/nakishiyaman/clauxton
• GitHub Releases: https://github.com/nakishiyaman/clauxton/releases
• Issues: https://github.com/nakishiyaman/clauxton/issues
• Discussions: https://github.com/nakishiyaman/clauxton/discussions

---

🙏 Acknowledgments

This project was inspired by the need for persistent context in AI-assisted development. Special thanks to the Claude Code team for building an extensible platform.

Note: Clauxton is an independent project and is not officially affiliated with Anthropic or Claude Code.

---

Built with ❤️ for Claude Code users