# Clauxton
**Context that persists for Claude Code**
[](https://github.com/nakishiyaman/clauxton/actions)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/PyCQA/bandit)
[](https://pypi.org/project/clauxton/)
[](https://pypi.org/project/clauxton/)
[](https://github.com/nakishiyaman/clauxton)
[](https://github.com/nakishiyaman/clauxton)
[](https://codecov.io/gh/nakishiyaman/clauxton)
> ✅ **Production Ready**: Clauxton v0.11.2 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,370 tests, 85% coverage).
> ⚡ **v0.11.2** (2025-10-25): Test Optimization - 97% faster test execution (52min → 1m46s), CI improvements for all language parsers!
> 🚀 **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)
```bash
# 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.2
```
**Note**: Language parsers are optional. Install only what you need for your project.
### Basic Usage
#### ⚡ Quick Start (Recommended)
```bash
# 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)
```bash
# 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
```bash
# 🌅 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)
```bash
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):
```bash
# 🆕 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)
- 🌅 **Daily Workflow Commands** - ⭐ **NEW v0.11.1**: `morning` briefing, `daily`/`weekly` summaries, `trends` analysis, `pause`/`resume` tracking, unified `search`
- 🔒 **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](docs/search-algorithm.md)
#### 📚 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**:
```bash
# 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**:
```python
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)
```bash
# 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
```bash
# 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](docs/search-algorithm.md) for details.
---
## 🚀 Usage
### Daily Workflow Commands (NEW v0.11.1)
```bash
# 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!
```bash
# 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
```bash
# 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
```bash
# 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`):
```yaml
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](docs/YAML_TASK_FORMAT.md) for complete specification.
### MCP Server Integration
The Clauxton MCP Server provides full Knowledge Base and Task Management for Claude Code:
```json
// .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](docs/mcp-server.md) for complete documentation.
### Conflict Detection Commands
```bash
# 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](docs/conflict-detection.md) for complete documentation.
### Undo/History Commands (NEW v0.10.0)
```bash
# 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](docs/ERROR_HANDLING_GUIDE.md) for recovery strategies.
### Configuration Commands (NEW v0.10.0)
```bash
# 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](docs/configuration-guide.md) for all available settings.
### Knowledge Base YAML Structure
After running `clauxton kb add`, your entries are stored in `.clauxton/knowledge-base.yml`:
```yaml
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](docs/yaml-format.md) 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](docs/architecture.md) for complete design.
---
## 📚 Documentation
### User Guides
- [Quick Start Guide](docs/quick-start.md) - Get started in 5 minutes (CLI)
- **[Developer Workflow Guide](docs/DEVELOPER_WORKFLOW_GUIDE.md)** - Complete development workflow with examples and diagrams ✨ v0.10.0
- **[Installation Guide](docs/INSTALLATION_GUIDE.md)** - Shell alias setup, virtual environment isolation explained
- **[MCP Integration Guide](docs/MCP_INTEGRATION_GUIDE.md)** - Step-by-step Claude Code integration (22 tools)
- [Tutorial: Your First Knowledge Base](docs/tutorial-first-kb.md) - 30-minute beginner guide
- [Use Cases & Examples](docs/use-cases.md) - Real-world scenarios and implementations
- [MCP Server Quick Start](docs/mcp-server-quickstart.md) - Get started with Claude Code
- [Task Management Guide](docs/task-management-guide.md) - Complete task management documentation
- [YAML Task Format Guide](docs/YAML_TASK_FORMAT.md) - YAML bulk import specification ✨ v0.10.0
- [Search Algorithm](docs/search-algorithm.md) - TF-IDF search explanation
- [YAML Format Reference](docs/yaml-format.md) - Complete Knowledge Base YAML specification
- [MCP Server Guide](docs/mcp-server.md) - Complete MCP Server documentation
- [Conflict Detection Guide](docs/conflict-detection.md) - Complete conflict detection documentation
- [Configuration Guide](docs/configuration-guide.md) - Configuration management ✨ v0.10.0
- [Logging Guide](docs/logging-guide.md) - Operation logging system ✨ v0.10.0
- [Backup Guide](docs/backup-guide.md) - Backup management ✨ v0.10.0
### Developer Guides
- [Architecture Overview](docs/architecture.md) - System design and data flow
- [Development Guide](docs/development.md) - Setup and contribution guide
- [Technical Design](docs/technical-design.md) - Implementation details (⚠️ Currently in Japanese, English version coming in v0.10.1)
- [Error Handling Guide](docs/ERROR_HANDLING_GUIDE.md) - Error handling patterns ✨ v0.10.0
- [Performance Guide](docs/performance-guide.md) - Performance optimization ✨ v0.10.0
- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions ✨ v0.10.0
- [Contributing](CONTRIBUTING.md) - Contribution guidelines
---
## 🧪 Testing
Clauxton has comprehensive test coverage (85%, 1,367 tests) with optimized execution time.
### Quick Tests (Default - Recommended)
```bash
pytest # ~2 minutes, 1,348 tests
```
Automatically excludes performance tests for fast feedback during development.
### Performance Tests
```bash
pytest -m "performance" # ~70 minutes, 19 tests
```
Run before releases or when optimizing performance. Also runs automatically every Sunday via CI.
### All Tests
```bash
pytest -m "" # ~80 minutes, 1,367 tests
```
Complete test suite including all performance tests.
### Coverage Report
```bash
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](CONTRIBUTING.md) for guidelines.
---
## 📄 License
MIT License - see [LICENSE](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](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](https://github.com/PyCQA/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](SECURITY.md) for detailed security guidelines.
---
## 🔗 Links
- **PyPI**: [https://pypi.org/project/clauxton/](https://pypi.org/project/clauxton/)
- **GitHub**: [https://github.com/nakishiyaman/clauxton](https://github.com/nakishiyaman/clauxton)
- **GitHub Releases**: [https://github.com/nakishiyaman/clauxton/releases](https://github.com/nakishiyaman/clauxton/releases)
- **Issues**: [https://github.com/nakishiyaman/clauxton/issues](https://github.com/nakishiyaman/clauxton/issues)
- **Discussions**: [https://github.com/nakishiyaman/clauxton/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**
Raw data
{
"_id": null,
"home_page": null,
"name": "clauxton",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ai-assistant, claude, claude-code, context, knowledge-base, mcp, plugin, task-management",
"author": null,
"author_email": "Nakishiyama <noreply@example.com>",
"download_url": "https://files.pythonhosted.org/packages/0c/89/11287bd80a6f59efad3ca03889443d799d9f6da024c464faac59c67a4e83/clauxton-0.12.0.tar.gz",
"platform": null,
"description": "# Clauxton\n\n**Context that persists for Claude Code**\n\n[](https://github.com/nakishiyaman/clauxton/actions)\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://github.com/PyCQA/bandit)\n[](https://pypi.org/project/clauxton/)\n[](https://pypi.org/project/clauxton/)\n[](https://github.com/nakishiyaman/clauxton)\n[](https://github.com/nakishiyaman/clauxton)\n[](https://codecov.io/gh/nakishiyaman/clauxton)\n\n> \u2705 **Production Ready**: Clauxton v0.11.2 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,370 tests, 85% coverage).\n> \u26a1 **v0.11.2** (2025-10-25): Test Optimization - 97% faster test execution (52min \u2192 1m46s), CI improvements for all language parsers!\n> \ud83d\ude80 **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!\n> \ud83c\udfaf **v0.11.0** (2025-10-24): Repository Map - Multi-language symbol extraction (12 languages), 3 search modes (exact/fuzzy/semantic), 441 intelligence tests!\n> \u2728 **v0.10.0** (2025-10-22): Bulk operations, undo functionality, human-in-the-loop confirmations, and 22 MCP tools!\n\nClauxton is a Claude Code plugin that provides **persistent project context** to solve AI-assisted development pain points.\n\n**Vision** (Roadmap):\n1. \u2705 **Session Context Loss** \u2192 Persistent Knowledge Base with TF-IDF Search (Phase 0-1 - **Complete**)\n2. \u2705 **Manual Dependency Tracking** \u2192 Auto-inferred task dependencies (Phase 1 - **Complete**)\n3. \u2705 **Post-hoc Conflict Detection** \u2192 Pre-merge conflict prediction (Phase 2 - **Complete**)\n4. \u2705 **Manual CLI Operations** \u2192 Enhanced UX with Bulk Operations & Undo (Phase 3 - **Complete in v0.10.0**)\n\n---\n\n## \ud83c\udfaf Quick Start\n\n### Install from PyPI (Recommended)\n\n```bash\n# Basic installation (fast, ~30 seconds)\npip install clauxton\n\n# Or install with language parsers for Repository Map:\npip install clauxton[parsers-python] # Python only\npip install clauxton[parsers-web] # JavaScript/TypeScript/PHP\npip install clauxton[parsers-systems] # Go/Rust/C++\npip install clauxton[parsers-enterprise] # Java/C#/Kotlin\npip install clauxton[parsers-all] # All 12 languages (~2 minutes)\n\n# Verify installation\nclauxton --version # Should show: clauxton, version 0.11.2\n```\n\n**Note**: Language parsers are optional. Install only what you need for your project.\n\n### Basic Usage\n\n#### \u26a1 Quick Start (Recommended)\n\n```bash\n# All-in-one setup - initialize, index, and configure MCP\ncd your-project\nclauxton quickstart\n\n# Done! Your project is ready with:\n# \u2713 Knowledge Base initialized\n# \u2713 Codebase indexed (Repository Map)\n# \u2713 MCP server configured for Claude Code\n\n# Optional: Skip certain steps\nclauxton quickstart --skip-mcp # Skip MCP setup (run later)\nclauxton quickstart --skip-index # Skip indexing (run later)\n```\n\n#### \ud83d\udccb Manual Setup (Step-by-Step)\n\n```bash\n# Step 1: Initialize in your project\ncd your-project\nclauxton init\n\n# Step 2: Index your codebase (Repository Map)\nclauxton repo index\n# \u2192 Indexed 50 files, found 200 symbols (Python, TypeScript, JavaScript)\n\n# Step 3: Setup MCP server for Claude Code\nclauxton mcp setup # Auto-configure MCP server\nclauxton mcp status # Check MCP configuration\n\n# Step 4: Check overall project status\nclauxton status # Repository Map, Tasks, KB, MCP - all in one\n```\n\n#### \ud83d\udd27 Daily Usage\n\n```bash\n# \ud83c\udf05 Start your day (v0.11.1 NEW!)\nclauxton morning\n# \u2192 Shows yesterday's wins, suggests today's tasks, sets focus interactively\n\n# \u2705 Add and start a task immediately (v0.11.1 NEW!)\nclauxton task add --name \"Implement API\" --start\n# \u2192 Creates task and sets focus in one command\n\n# \u23f8\ufe0f Take a break (v0.11.1 NEW!)\nclauxton pause \"Meeting\"\n# \u2192 Records interruption with reason\n\nclauxton pause --history\n# \u2192 View all pause history and statistics\n\n# \ud83d\udd04 Resume work (v0.11.1 NEW!)\nclauxton resume\n# \u2192 Shows where you left off and suggests next actions\n\nclauxton resume --yesterday\n# \u2192 Also shows yesterday's activity for context\n\n# \ud83d\udd0d Unified search (v0.11.1 NEW!)\nclauxton search \"authentication\"\n# \u2192 Searches KB, Tasks, and Files all at once\n\nclauxton search \"API\" --kb-only --limit 10\n# \u2192 Search with filters and custom limits\n\n# \ud83d\udcca Daily summary (v0.11.1 NEW!)\nclauxton daily\n# \u2192 End-of-day review: completed tasks, time tracking, next actions\n\nclauxton daily --date 2025-10-24\n# \u2192 View specific date\n\nclauxton daily --json\n# \u2192 JSON output for integrations\n\n# \ud83d\udcc8 Weekly summary (v0.11.1 NEW!)\nclauxton weekly\n# \u2192 Week's accomplishments, velocity, trends\n\nclauxton weekly --week -1\n# \u2192 Last week's summary\n\n# \ud83d\udcc9 Productivity trends (v0.11.1 NEW!)\nclauxton trends\n# \u2192 30-day productivity analysis with insights\n\nclauxton trends --days 7\n# \u2192 Last week's trends\n\n# Add knowledge to your Knowledge Base\nclauxton kb add\n# Enter: Title, Category, Content, Tags\n\n# Search with TF-IDF relevance ranking\nclauxton kb search \"FastAPI authentication\"\n# Results are ranked by relevance - most relevant first!\n\n# Get next recommended task (AI-powered)\nclauxton task next\n\n# Search symbols across codebase\nclauxton repo search \"authenticate\" --mode exact\n# \u2192 authenticate_user (function) at auth.py:10-20\n# AuthService.verify (method) at auth.ts:45-60\n\nclauxton repo search \"user login\" --mode semantic\n# \u2192 Find symbols by meaning (requires scikit-learn)\n\n# Undo last operation (v0.10.0 feature)\nclauxton undo # Undo with confirmation\nclauxton undo --history # View operation history\n\n# Configure confirmation mode (v0.10.0 feature)\nclauxton config set confirmation_mode auto # Balanced (default)\nclauxton config set confirmation_mode always # Maximum safety\nclauxton config set confirmation_mode never # Maximum speed\nclauxton config list # View all configuration\n```\n\n### Install from Source (Development)\n\n```bash\ngit clone https://github.com/nakishiyaman/clauxton.git\ncd clauxton\npip install -e .\n```\n\n### MCP Integration with Claude Code\n\nSet up Clauxton as MCP tools in Claude Code (22+ tools available):\n\n```bash\n# \ud83c\udd95 v0.11.0: Automatic setup with single command\nclauxton mcp setup\n# \u2192 Detects your platform and Python environment\n# \u2192 Generates .claude-plugin/mcp-servers.json automatically\n# \u2192 Ready in seconds!\n\n# Check configuration status\nclauxton mcp status\n\n# Alternative: Manual setup (Linux/macOS)\n./setup-mcp.sh\n\n# Or see detailed guide\ndocs/MCP_INTEGRATION_GUIDE.md\n```\n\n**With v0.10.0 (Released 2025-10-22)**, Claude Code uses Clauxton with enhanced features:\n\n```\nYou: \"Build a Todo app with FastAPI\"\n\nClaude Code: (Automatically creates 10 tasks via MCP, no manual commands needed)\n \"Created 10 tasks. Starting with TASK-001: FastAPI setup\"\n\nYou: \"Sounds good!\"\n\nClaude Code: (Begins implementation)\n```\n\n**No more manual CLI commands** - just natural conversation! See `CLAUDE.md` for details.\n\n---\n\n## \u2728 Features\n\n- \ud83e\udde0 **Persistent Knowledge Base** - Store architecture decisions, patterns, constraints across sessions\n- \ud83d\udccb **Task Management** - AI-powered task tracking with automatic dependency inference\n- \u26a0\ufe0f **Conflict Detection** - Predict file conflicts before they occur, get safe execution order\n- \ud83d\udd0d **TF-IDF Search** - Relevance-based search with intelligent ranking (powered by scikit-learn)\n- \ud83d\uddfa\ufe0f **Repository Map** - \u2b50 **NEW v0.11.0**: Automatic codebase indexing with symbol search (exact/fuzzy/semantic)\n- \ud83c\udf05 **Daily Workflow Commands** - \u2b50 **NEW v0.11.1**: `morning` briefing, `daily`/`weekly` summaries, `trends` analysis, `pause`/`resume` tracking, unified `search`\n- \ud83d\udd12 **Privacy First** - Local-only by default, no cloud dependencies\n- \ud83e\udd16 **MCP Integration** - Seamless integration with Claude Code via Model Context Protocol (22 tools)\n\n### \u2705 Core Features (v0.10.0)\n\n#### \ud83d\udd0d TF-IDF Relevance Search\n- \u2705 **Intelligent Ranking**: TF-IDF algorithm ranks results by relevance (powered by scikit-learn)\n- \u2705 **Automatic Fallback**: Gracefully falls back to keyword search if scikit-learn unavailable\n- \u2705 **Fast Performance**: Validated with 200+ knowledge base entries\n- \u2705 **Query Understanding**: Understands multi-word queries and technical terms\n- \u2705 **See**: [Search Algorithm Documentation](docs/search-algorithm.md)\n\n#### \ud83d\udcda Knowledge Base Management\n- \u2705 **Persistent Context**: Store architecture decisions, patterns, constraints, conventions\n- \u2705 **Category System**: 5 categories (architecture, constraint, decision, pattern, convention)\n- \u2705 **YAML Storage**: Human-readable, Git-friendly format\n- \u2705 **CRUD Operations**: Add, get, update, delete, list entries\n- \u2705 **Version Management**: Automatic versioning on updates\n- \u2705 **Atomic Writes**: Safe file operations with automatic backups\n- \u2705 **Secure Permissions**: 700/600 permissions for privacy\n\n#### \u2705 Task Management System\n- \u2705 **Full CRUD**: Add, get, update, delete, list tasks\n- \u2705 **Smart Dependencies**: Auto-inferred from file overlap + manual dependencies\n- \u2705 **DAG Validation**: Cycle detection prevents circular dependencies\n- \u2705 **Priority Management**: 4 levels (Critical > High > Medium > Low)\n- \u2705 **AI Recommendations**: `task next` suggests optimal next task\n- \u2705 **Progress Tracking**: Track status (pending, in_progress, completed, blocked)\n- \u2705 **Time Estimates**: Optional hour estimates for planning\n\n#### \ud83d\ude80 v0.10.0 Features (Transparent Integration)\n**Bulk Operations**:\n- \u2705 **YAML Bulk Import**: Create multiple tasks from YAML file - 30x faster than manual\n- \u2705 **KB Export**: Export Knowledge Base to Markdown documentation\n- \u2705 **Progress Display**: Real-time progress bars for bulk operations (100+ items)\n\n**Safety & Recovery**:\n- \u2705 **Undo/Rollback**: Reverse accidental operations with full history tracking\n- \u2705 **Error Recovery**: Transactional import with `rollback`/`skip`/`abort` strategies\n- \u2705 **YAML Safety**: Security checks to prevent code injection attacks\n- \u2705 **Backup Enhancement**: Automatic backups before every write operation (last 10 kept)\n- \u2705 **Enhanced Validation**: Pre-Pydantic validation with clear error messages\n\n**User Experience**:\n- \u2705 **Confirmation Prompts**: Threshold-based warnings for bulk operations\n- \u2705 **Configurable Confirmation Mode**: Set HITL level (always/auto/never)\n- \u2705 **Operation Logging**: Structured logging with daily log files (30-day retention)\n- \u2705 **Better Error Messages**: Actionable errors with context + suggestion + commands\n- \u2705 **Performance Optimization**: 10x faster bulk operations\n\n**Total**: 13 new features in v0.10.0\n\n#### \ud83d\uddfa\ufe0f Repository Map (v0.11.0 - Released 2025-10-24)\n**Automatic Codebase Intelligence**:\n- \u2705 **File Indexing**: Recursive scanning with `.gitignore` support (1000+ files in <2s)\n- \u2705 **Symbol Extraction**: Functions, classes, methods, interfaces, types with signatures\n- \u2705 **Multi-Language Support** (12 languages):\n - **Python** \u2705 Complete (functions, classes, methods, docstrings, type hints)\n - **JavaScript** \u2705 Complete (ES6+, classes, arrow functions, async/await)\n - **TypeScript** \u2705 Complete (interfaces, type aliases, generics, type annotations)\n - **Go** \u2705 Complete (functions, methods, structs, interfaces, type aliases, generics)\n - **Rust** \u2705 Complete (functions, methods, structs, enums, traits, type aliases, generics)\n - **C++** \u2705 Complete (functions, classes, structs, namespaces, templates)\n - **Java** \u2705 Complete (classes, interfaces, methods, enums, annotations, constructors)\n - **C#** \u2705 Complete (classes, interfaces, structs, methods, properties, records, extensions)\n - **PHP** \u2705 Complete (classes, functions, methods, traits, enums, promoted properties, attributes)\n - **Ruby** \u2705 Complete (classes, modules, methods, module mixins, singleton methods, attr_*)\n - **Swift** \u2705 Complete (classes, structs, protocols, extensions, enums, init methods, properties)\n - **Kotlin** \u2705 Complete (classes, data/sealed classes, interfaces, objects, companion objects, suspend functions)\n- \u2705 **3 Search Modes**:\n - **Exact**: Fast substring matching with priority scoring\n - **Fuzzy**: Typo-tolerant using Levenshtein distance\n - **Semantic**: TF-IDF meaning-based search (requires scikit-learn)\n- \u2705 **CLI Commands**: `repo index`, `repo search`, `repo status`\n- \u2705 **MCP Integration**: `index_repository()`, `search_symbols()` tools\n- \u2705 **Performance**: 1000+ files/1-2s indexing, <0.01s search\n- \u2705 **Storage**: JSON format in `.clauxton/map/` (~10-50KB per project)\n\n**Example Usage**:\n```bash\n# Index your codebase (Python, JavaScript, TypeScript)\nclauxton repo index\n# \u2192 Indexed 50 files, found 200 symbols in 0.15s\n# - 15 Python files (50 functions, 20 classes)\n# - 20 TypeScript files (80 functions, 15 interfaces, 10 type aliases)\n# - 15 JavaScript files (40 functions, 10 classes)\n\n# Search for functions\nclauxton repo search \"authenticate\" --mode exact\n# \u2192 authenticate_user (function) at auth.py:10-20\n# getAuthToken (function) at auth.ts:30-35\n# AuthService.verify (method) at auth-service.ts:45-60\n\n# Search for TypeScript interfaces\nclauxton repo search \"User\" --mode exact\n# \u2192 User (interface) at types.ts:5-10\n# UserService (class) at user-service.ts:15-50\n# getUserById (function) at api.ts:100-110\n\n# Semantic search by meaning\nclauxton repo search \"user login\" --mode semantic\n# \u2192 authenticate_user, verify_credentials, check_session...\n# AuthService, LoginRequest, validateToken...\n```\n\n**Programming API**:\n```python\nfrom pathlib import Path\nfrom clauxton.intelligence.symbol_extractor import (\n PythonSymbolExtractor,\n JavaScriptSymbolExtractor,\n TypeScriptSymbolExtractor,\n GoSymbolExtractor,\n)\n\n# Extract TypeScript symbols\nts_extractor = TypeScriptSymbolExtractor()\nsymbols = ts_extractor.extract(Path(\"src/types.ts\"))\n\nfor symbol in symbols:\n print(f\"{symbol['name']} ({symbol['type']}) at line {symbol['line_start']}\")\n # Output:\n # User (interface) at line 5\n # AuthRequest (type_alias) at line 10\n # AuthService (class) at line 15\n\n# Extract Go symbols\ngo_extractor = GoSymbolExtractor()\ngo_symbols = go_extractor.extract(Path(\"pkg/user.go\"))\n\nfor symbol in go_symbols:\n if symbol['type'] == 'method':\n print(f\"{symbol['name']} (method on {symbol['receiver']})\")\n else:\n print(f\"{symbol['name']} ({symbol['type']})\")\n # Output:\n # User (struct)\n # GetName (method on *User)\n # SetName (method on *User)\n```\n\n**Total**: Week 1 complete (81 tests, 92%/90% coverage)\n\n#### \ud83d\udd0c MCP Server Integration (22 Tools)\n**Knowledge Base Tools** (7):\n- \u2705 `kb_search` - TF-IDF relevance-ranked search\n- \u2705 `kb_add` - Add new knowledge entry\n- \u2705 `kb_list` - List all entries (filterable by category)\n- \u2705 `kb_get` - Get entry by ID\n- \u2705 `kb_update` - Update existing entry\n- \u2705 `kb_delete` - Delete entry\n- \u2705 `kb_export_docs` - **NEW v0.10.0**: Export KB to Markdown docs\n\n**Task Management Tools** (7):\n- \u2705 `task_add` - Create task with auto-dependency inference\n- \u2705 `task_import_yaml` - **NEW v0.10.0**: Bulk import tasks from YAML\n- \u2705 `task_list` - List tasks (filterable by status/priority)\n- \u2705 `task_get` - Get task details\n- \u2705 `task_update` - Update task fields\n- \u2705 `task_next` - Get AI-recommended next task\n- \u2705 `task_delete` - Delete task\n\n**Conflict Detection Tools** (3):\n- \u2705 `detect_conflicts` - Detect file conflicts for a task\n- \u2705 `recommend_safe_order` - Get optimal task execution order\n- \u2705 `check_file_conflicts` - Check if files are being edited\n\n**Operation Management Tools** (2) - **NEW v0.10.0**:\n- \u2705 `undo_last_operation` - Reverse accidental operations\n- \u2705 `get_recent_operations` - View operation history\n\n**Logging Tools** (1) - **NEW v0.10.0**:\n- \u2705 `get_recent_logs` - View recent operation logs\n\n**Repository Map Tools** (2) - \u2b50 **NEW v0.11.0**:\n- \u2705 `index_repository` - Index codebase with symbol extraction\n- \u2705 `search_symbols` - Search symbols with exact/fuzzy/semantic modes\n\n#### \ud83d\udcca Quality Metrics\n- \u2705 **1228 Tests** - Comprehensive test coverage (758 \u2192 1228, +470 tests in v0.11.0):\n - Core modules: 87-96% coverage (knowledge_base, task_manager, conflict_detector, etc.)\n - Intelligence modules: 91-92% coverage (repository_map, symbol_extractor, parser) - **NEW v0.11.0**\n - 441 intelligence tests covering 12 languages (Python, JS, TS, Go, Rust, C++, Java, C#, PHP, Ruby, Swift, Kotlin)\n - MCP server: 35% coverage (22 tools, all tested individually)\n - CLI modules: 84-100% coverage (main, tasks, conflicts, config, repository)\n - Utils modules: 15-29% coverage (targeted for future improvement)\n- \u2705 **91% Coverage** - High code quality maintained across all modules\n- \u2705 **Type Safe** - Full Pydantic validation with strict mode\n- \u2705 **Production Ready** - Stable v0.11.0 release with 12-language Repository Map\n\n### \u26a0\ufe0f Conflict Detection\n\n#### \u26a0\ufe0f Pre-merge Conflict Detection\n- \u2705 **File Overlap Detection**: Detects file conflicts between tasks\n- \u2705 **Risk Scoring**: Calculates risk (LOW <40%, MEDIUM 40-70%, HIGH >70%)\n- \u2705 **Safe Execution Order**: Recommends optimal task execution order\n- \u2705 **File Availability Check**: Check if files are currently being edited\n- \u2705 **CLI Commands**: `conflict detect`, `conflict order`, `conflict check`\n- \u2705 **MCP Tools**: Full integration for Claude Code\n\n### \ud83d\udd2e Future Enhancements\n\n**v0.11.0 Complete** (Released 2025-10-24) \u2705:\n- \u2705 **Repository Map**: 12-language symbol extraction\n- \u2705 **3 Search Modes**: Exact, Fuzzy, Semantic\n- \u2705 **441 intelligence tests** across all languages\n- \u2705 **Performance**: 1000+ files in 1-2s\n- \u2705 **MCP Integration**: 2 new tools (22 total)\n\n**v0.12.0 Roadmap** (Planned):\n- \ud83d\udccb **Line-Level Conflict Detection**: Detect conflicts at code line level\n- \ud83d\udccb **Drift Detection**: Track scope expansion in tasks\n- \ud83d\udccb **Enhanced Event Logging**: Complete audit trail with events.jsonl\n- \ud83d\udccb **Lifecycle Hooks**: Pre-commit and post-edit hooks\n- \ud83d\udccb **Web Dashboard**: Browser-based UI for task/KB management\n\n---\n\n## \ud83d\udce6 Installation\n\n### PyPI Installation (Recommended)\n\n```bash\n# Install latest stable version (includes all features)\npip install clauxton\n\n# Verify installation\nclauxton --version # Should show: clauxton, version 0.11.0\n\n# Install specific version (example)\npip install clauxton==0.10.1\n```\n\n**What's Included**:\n- \u2705 Knowledge Base management (CRUD + TF-IDF search + Markdown export)\n- \u2705 Task Management system with auto-dependencies + YAML bulk import\n- \u2705 Conflict Detection (pre-merge conflict prediction)\n- \u2705 Undo/Rollback functionality with operation history\n- \u2705 Configurable confirmation modes (always/auto/never)\n- \u2705 Operation logging with 30-day retention\n- \u2705 Automatic backups (last 10 retained)\n- \u2705 MCP Server (22 tools for Claude Code)\n- \u2705 All dependencies (scikit-learn, numpy, pydantic, click, pyyaml, gitpython, mcp)\n\n### Development Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/nakishiyaman/clauxton.git\ncd clauxton\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate # On macOS/Linux\n# or\nvenv\\Scripts\\activate # On Windows\n\n# Install in editable mode\npip install -e .\n\n# Run tests\npytest\n```\n\n### Requirements\n\n- **Python**: 3.11 or higher\n- **Dependencies** (auto-installed with pip):\n - `pydantic>=2.0` - Data validation\n - `click>=8.1` - CLI framework\n - `pyyaml>=6.0` - YAML parsing\n - `gitpython>=3.1` - Git integration\n - `mcp>=1.0` - MCP server\n - `scikit-learn>=1.3` - TF-IDF search\n - `numpy>=1.24` - Required by scikit-learn\n\n**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](docs/search-algorithm.md) for details.\n\n---\n\n## \ud83d\ude80 Usage\n\n### Daily Workflow Commands (NEW v0.11.1)\n\n```bash\n# Quick project overview - See everything at a glance\nclauxton overview\nclauxton overview --limit 5 # Show 5 entries per category\n\n# Resume work - Get back into context after a break\nclauxton resume\n\n# Project statistics - Understand project health\nclauxton stats\n```\n\n### Quick Add Shortcuts (NEW v0.11.1)\n\nFaster than interactive commands - no prompts, just add!\n\n```bash\n# Quick Knowledge Base entries (10x faster)\nclauxton add-architecture \"Microservices\" \"Using Docker containers for each service\"\nclauxton add-decision \"Use PostgreSQL\" \"Chosen for JSONB support\" --tags database,backend\nclauxton add-constraint \"Max 1000 items\" \"API returns maximum 1000 items per request\"\nclauxton add-pattern \"Repository Pattern\" \"All DB access through repositories\"\nclauxton add-convention \"snake_case\" \"Use snake_case for Python variables\"\n\n# Quick task creation\nclauxton quick-task \"Setup backend\"\nclauxton quick-task \"Fix authentication bug\" --high\nclauxton quick-task \"Security patch CVE-2024-001\" --critical\n```\n\n### Knowledge Base Commands\n\n```bash\n# Initialize Clauxton in your project\nclauxton init\n\n# Add knowledge entry (interactive)\nclauxton kb add\n\n# Search Knowledge Base (TF-IDF relevance ranking)\nclauxton kb search \"architecture\" # Results ranked by relevance\nclauxton kb search \"API\" --category architecture\nclauxton kb search \"FastAPI\" --limit 5 # Limit to top 5 results\n\n# List all entries\nclauxton kb list\nclauxton kb list --category decision\n\n# Get entry by ID\nclauxton kb get KB-20251019-001\n\n# Update entry\nclauxton kb update KB-20251019-001 --title \"New Title\"\nclauxton kb update KB-20251019-001 --content \"New content\" --category decision\n\n# Delete entry\nclauxton kb delete KB-20251019-001\nclauxton kb delete KB-20251019-001 --yes # Skip confirmation\n\n# Export Knowledge Base to Markdown docs (v0.10.0)\nclauxton kb export --output-dir ./docs/kb\n\n# Export as compact summary - Perfect for team onboarding! (NEW v0.11.1)\nclauxton kb export --output-dir ./docs/kb --summary\n```\n\n### Task Management Commands\n\n```bash\n# Add a new task\nclauxton task add --name \"Setup database\" --priority high\n\n# Add task with dependencies\nclauxton task add \\\n --name \"Add API endpoint\" \\\n --depends-on TASK-001 \\\n --files \"src/api/users.py\" \\\n --estimate 3.5\n\n# List all tasks\nclauxton task list\nclauxton task list --status pending\nclauxton task list --priority high\n\n# Get task details\nclauxton task get TASK-001\n\n# Update task\nclauxton task update TASK-001 --status in_progress\nclauxton task update TASK-001 --priority critical\n\n# Get next recommended task (AI-powered)\nclauxton task next\n\n# Delete task\nclauxton task delete TASK-001\n\n# Bulk import tasks from YAML (NEW v0.10.0)\nclauxton task import tasks.yml\nclauxton task import tasks.yml --dry-run # Validate without creating\n```\n\n**YAML Bulk Import Example** (`tasks.yml`):\n```yaml\ntasks:\n - name: \"Setup FastAPI project\"\n priority: high\n files_to_edit:\n - main.py\n - requirements.txt\n estimated_hours: 2.5\n\n - name: \"Create database models\"\n priority: high\n depends_on:\n - TASK-001\n files_to_edit:\n - models/user.py\n - models/post.py\n estimated_hours: 3.0\n\n - name: \"Write API tests\"\n priority: medium\n depends_on:\n - TASK-002\n estimated_hours: 4.0\n```\n\nSee [YAML Task Format Guide](docs/YAML_TASK_FORMAT.md) for complete specification.\n\n### MCP Server Integration\n\nThe Clauxton MCP Server provides full Knowledge Base and Task Management for Claude Code:\n\n```json\n// .claude-plugin/mcp-servers.json\n{\n \"mcpServers\": {\n \"clauxton\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"clauxton.mcp.server\"],\n \"cwd\": \"${workspaceFolder}\"\n }\n }\n}\n```\n\n**Knowledge Base Tools**:\n- `kb_search(query, category?, limit?)` - Search with TF-IDF relevance ranking\n- `kb_add(title, category, content, tags?)` - Add new entry\n- `kb_list(category?)` - List all entries\n- `kb_get(entry_id)` - Get entry by ID\n- `kb_update(entry_id, title?, content?, category?, tags?)` - Update entry\n- `kb_delete(entry_id)` - Delete entry\n\n> **Note**: Search results are automatically ranked by relevance using TF-IDF algorithm. Most relevant entries appear first.\n\n**Task Management Tools**:\n- `task_add(name, description?, priority?, depends_on?, files?, kb_refs?, estimate?)` - Add task\n- `task_import_yaml(yaml_content, dry_run?, skip_validation?)` - **NEW v0.10.0**: Bulk import tasks from YAML\n- `task_list(status?, priority?)` - List tasks with filters\n- `task_get(task_id)` - Get task details\n- `task_update(task_id, status?, priority?, name?, description?)` - Update task\n- `task_next()` - Get AI-recommended next task\n- `task_delete(task_id)` - Delete task\n\nSee [MCP Server Guide](docs/mcp-server.md) for complete documentation.\n\n### Conflict Detection Commands\n\n```bash\n# Check conflicts before starting a task\nclauxton conflict detect TASK-001\n\n# Get safe execution order for multiple tasks\nclauxton conflict order TASK-001 TASK-002 TASK-003\n\n# Check if specific files are being edited\nclauxton conflict check src/api/users.py src/models/user.py\n```\n\nSee [Conflict Detection Guide](docs/conflict-detection.md) for complete documentation.\n\n### Undo/History Commands (NEW v0.10.0)\n\n```bash\n# Undo last operation (with confirmation)\nclauxton undo\n\n# View operation history\nclauxton undo --history\nclauxton undo --history --limit 20 # Show last 20 operations\n\n# Force undo without confirmation\nclauxton undo --yes\n```\n\nSee [Error Handling Guide](docs/ERROR_HANDLING_GUIDE.md) for recovery strategies.\n\n### Configuration Commands (NEW v0.10.0)\n\n```bash\n# Set confirmation mode\nclauxton config set confirmation_mode always # Strict (confirm every operation)\nclauxton config set confirmation_mode auto # Balanced (threshold-based, default)\nclauxton config set confirmation_mode never # Fast (no confirmations)\n\n# Get configuration value\nclauxton config get confirmation_mode\n\n# List all configuration\nclauxton config list\n```\n\nSee [Configuration Guide](docs/configuration-guide.md) for all available settings.\n\n### Knowledge Base YAML Structure\n\nAfter running `clauxton kb add`, your entries are stored in `.clauxton/knowledge-base.yml`:\n\n```yaml\nversion: '1.0'\nproject_name: my-project\n\nentries:\n - id: KB-20251019-001\n title: Use FastAPI framework\n category: architecture\n content: |\n All backend APIs use FastAPI framework.\n\n Reasons:\n - Async/await support\n - Automatic OpenAPI docs\n - Excellent performance\n tags:\n - backend\n - api\n - fastapi\n created_at: '2025-10-19T10:30:00'\n updated_at: '2025-10-19T10:30:00'\n version: 1\n```\n\n**Categories**:\n- `architecture`: System design decisions\n- `constraint`: Technical/business constraints\n- `decision`: Important project decisions with rationale\n- `pattern`: Coding patterns and best practices\n- `convention`: Team conventions and code style\n\nSee [YAML Format Reference](docs/yaml-format.md) for complete schema documentation.\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Current Architecture (v0.10.0)\n\n```\nclauxton/\n\u251c\u2500\u2500 core/ # Core business logic\n\u2502 \u251c\u2500\u2500 models.py # Pydantic data models \u2705\n\u2502 \u251c\u2500\u2500 knowledge_base.py # KB CRUD operations \u2705\n\u2502 \u251c\u2500\u2500 task_manager.py # Task lifecycle + DAG validation \u2705\n\u2502 \u251c\u2500\u2500 search.py # TF-IDF search implementation \u2705\n\u2502 \u251c\u2500\u2500 conflict_detector.py # Conflict detection \u2705\n\u2502 \u251c\u2500\u2500 operation_history.py # Undo/history tracking \u2705\n\u2502 \u2514\u2500\u2500 confirmation_manager.py # HITL confirmations \u2705\n\u251c\u2500\u2500 utils/ # Utility modules\n\u2502 \u251c\u2500\u2500 yaml_utils.py # Safe YAML I/O \u2705\n\u2502 \u251c\u2500\u2500 file_utils.py # Secure file operations \u2705\n\u2502 \u251c\u2500\u2500 backup_manager.py # Backup management \u2705\n\u2502 \u2514\u2500\u2500 logger.py # Operation logging \u2705\n\u251c\u2500\u2500 cli/ # CLI interface\n\u2502 \u251c\u2500\u2500 main.py # Main CLI + KB commands \u2705\n\u2502 \u251c\u2500\u2500 tasks.py # Task management commands \u2705\n\u2502 \u251c\u2500\u2500 conflicts.py # Conflict detection commands \u2705\n\u2502 \u2514\u2500\u2500 config.py # Configuration commands \u2705\n\u2514\u2500\u2500 mcp/ # MCP Server integration\n \u2514\u2500\u2500 server.py # 17 MCP tools \u2705\n```\n\n**Storage**:\n- `.clauxton/knowledge-base.yml` - Knowledge Base entries\n- `.clauxton/tasks.yml` - Task definitions\n- `.clauxton/operation-history.jsonl` - Operation history (undo)\n- `.clauxton/logs/` - Daily operation logs\n- `.clauxton/backups/` - Automatic backups (last 10)\n\nSee [docs/architecture.md](docs/architecture.md) for complete design.\n\n---\n\n## \ud83d\udcda Documentation\n\n### User Guides\n- [Quick Start Guide](docs/quick-start.md) - Get started in 5 minutes (CLI)\n- **[Developer Workflow Guide](docs/DEVELOPER_WORKFLOW_GUIDE.md)** - Complete development workflow with examples and diagrams \u2728 v0.10.0\n- **[Installation Guide](docs/INSTALLATION_GUIDE.md)** - Shell alias setup, virtual environment isolation explained\n- **[MCP Integration Guide](docs/MCP_INTEGRATION_GUIDE.md)** - Step-by-step Claude Code integration (22 tools)\n- [Tutorial: Your First Knowledge Base](docs/tutorial-first-kb.md) - 30-minute beginner guide\n- [Use Cases & Examples](docs/use-cases.md) - Real-world scenarios and implementations\n- [MCP Server Quick Start](docs/mcp-server-quickstart.md) - Get started with Claude Code\n- [Task Management Guide](docs/task-management-guide.md) - Complete task management documentation\n- [YAML Task Format Guide](docs/YAML_TASK_FORMAT.md) - YAML bulk import specification \u2728 v0.10.0\n- [Search Algorithm](docs/search-algorithm.md) - TF-IDF search explanation\n- [YAML Format Reference](docs/yaml-format.md) - Complete Knowledge Base YAML specification\n- [MCP Server Guide](docs/mcp-server.md) - Complete MCP Server documentation\n- [Conflict Detection Guide](docs/conflict-detection.md) - Complete conflict detection documentation\n- [Configuration Guide](docs/configuration-guide.md) - Configuration management \u2728 v0.10.0\n- [Logging Guide](docs/logging-guide.md) - Operation logging system \u2728 v0.10.0\n- [Backup Guide](docs/backup-guide.md) - Backup management \u2728 v0.10.0\n\n### Developer Guides\n- [Architecture Overview](docs/architecture.md) - System design and data flow\n- [Development Guide](docs/development.md) - Setup and contribution guide\n- [Technical Design](docs/technical-design.md) - Implementation details (\u26a0\ufe0f Currently in Japanese, English version coming in v0.10.1)\n- [Error Handling Guide](docs/ERROR_HANDLING_GUIDE.md) - Error handling patterns \u2728 v0.10.0\n- [Performance Guide](docs/performance-guide.md) - Performance optimization \u2728 v0.10.0\n- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions \u2728 v0.10.0\n- [Contributing](CONTRIBUTING.md) - Contribution guidelines\n\n---\n\n## \ud83e\uddea Testing\n\nClauxton has comprehensive test coverage (85%, 1,367 tests) with optimized execution time.\n\n### Quick Tests (Default - Recommended)\n\n```bash\npytest # ~2 minutes, 1,348 tests\n```\n\nAutomatically excludes performance tests for fast feedback during development.\n\n### Performance Tests\n\n```bash\npytest -m \"performance\" # ~70 minutes, 19 tests\n```\n\nRun before releases or when optimizing performance. Also runs automatically every Sunday via CI.\n\n### All Tests\n\n```bash\npytest -m \"\" # ~80 minutes, 1,367 tests\n```\n\nComplete test suite including all performance tests.\n\n### Coverage Report\n\n```bash\npytest --cov=clauxton --cov-report=html\nopen htmlcov/index.html # View detailed coverage report\n```\n\n### Test Statistics\n\n- **Total Tests**: 1,367\n- **Default Tests**: 1,348 (excludes 19 performance tests)\n- **Coverage**: 85%\n- **CI Execution Time**: ~5-8 minutes\n- **Performance Tests**: Weekly (Sundays 02:00 UTC) + Manual trigger\n\n### CI/CD\n\n- **Push/PR**: Runs default tests automatically (~8 minutes)\n- **Weekly Schedule**: Performance tests every Sunday at 02:00 UTC\n- **Manual Trigger**: Run performance tests via GitHub Actions \"Run workflow\" button\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## \ud83d\udcca Project Status\n\n| Phase | Status | Completion | Release |\n|-------|--------|------------|---------|\n| **Phase 0: Foundation** | \u2705 Complete | 100% | v0.1.0 |\n| **Phase 1: Core Engine** | \u2705 Complete | 100% | v0.8.0 |\n| **Phase 2: Conflict Detection** | \u2705 Complete | 100% | v0.9.0-beta |\n| **Phase 3: Enhanced UX** | \u2705 Complete | 100% | **v0.10.0** (Released 2025-10-22) |\n| **Phase 4: Repository Map** | \u2705 Complete | 100% | **v0.11.0** (Released 2025-10-24) |\n| Polish & Documentation | \ud83d\udccb Planned | 0% | v0.12.0 (target) |\n| v1.0 Public Launch | \ud83d\udccb Planned | 0% | v1.0.0 (target) |\n\n**Phase 1 Complete** (v0.8.0 - Released 2025-10-19) \u2705:\n- \u2705 Knowledge Base CRUD (6 MCP tools + CLI)\n- \u2705 TF-IDF Relevance Search (scikit-learn powered)\n- \u2705 Task Management (6 MCP tools + CLI)\n- \u2705 Auto Dependency Inference (file overlap detection)\n- \u2705 DAG Validation (cycle detection)\n- \u2705 Full Documentation (20 guides)\n- \u2705 **267 tests, 94% coverage**\n\n**Phase 2 Complete** (v0.9.0-beta - Released 2025-10-20) \u2705:\n- \ud83c\udd95 Conflict Detection (file-based conflict prediction)\n- \ud83c\udd95 Risk Scoring (LOW/MEDIUM/HIGH)\n- \ud83c\udd95 Safe Execution Order (topological sort + conflict-aware)\n- \ud83c\udd95 3 CLI Commands (detect, order, check)\n- \ud83c\udd95 3 MCP Tools (15 tools total)\n- \ud83c\udd95 **390 tests (+123), 94% coverage maintained**\n- \ud83c\udd95 Comprehensive migration guide\n- \ud83c\udd95 **Production ready release**\n\n**Phase 3 Complete** (v0.10.0 - Released 2025-10-22) \u2705:\n- \ud83c\udd95 Bulk Task Import/Export (YAML format, 30x faster)\n- \ud83c\udd95 Undo Functionality (reverse operations, view history)\n- \ud83c\udd95 Human-in-the-Loop Confirmations (3 modes: always/auto/never)\n- \ud83c\udd95 KB Documentation Export (Markdown generation)\n- \ud83c\udd95 Enhanced Validation (YAML safety, dependency validation)\n- \ud83c\udd95 2 new MCP Tools (17 tools total: undo_last_operation, get_recent_operations)\n- \ud83c\udd95 **758 tests (+368), 91% coverage achieved**\n- \ud83c\udd95 **13 comprehensive documentation files**\n- \ud83c\udd95 **Production ready, stable release**\n\n**Phase 4 Complete** (v0.11.0 - Released 2025-10-24) \u2705:\n- \ud83d\uddfa\ufe0f **Repository Map** - Automatic codebase intelligence\n- \ud83c\udd95 **12-Language Support**: Python, JavaScript, TypeScript, Go, Rust, C++, Java, C#, PHP, Ruby, Swift, Kotlin\n- \ud83c\udd95 **Multi-Language Symbol Extraction**: Functions, classes, methods, interfaces, types with full metadata\n- \ud83c\udd95 **3 Search Modes**: Exact (fast substring), Fuzzy (typo-tolerant), Semantic (TF-IDF meaning-based)\n- \ud83c\udd95 **CLI Commands**: `repo index`, `repo search`, `repo status`\n- \ud83c\udd95 **2 new MCP Tools** (22 tools total: index_repository, search_symbols)\n- \ud83c\udd95 **Performance**: 1000+ files in 1-2s indexing, <0.01s search\n- \ud83c\udd95 **441 intelligence tests** (12 languages, 91% coverage)\n- \ud83c\udd95 **1,228 total tests** (+470 from v0.10.0)\n- \ud83c\udd95 **Production ready with comprehensive error handling**\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history.\n\n---\n\n## \ud83d\udd12 Security\n\nClauxton takes security seriously and follows industry best practices:\n\n### Security Measures\n\n- **Static Analysis**: Automated security scanning with [Bandit](https://github.com/PyCQA/bandit) in CI/CD\n- **Safe YAML Loading**: Uses `yaml.safe_load()` to prevent code execution\n- **Secure File Permissions**:\n - `.clauxton/` directory: 700 (owner only)\n - Data files: 600 (owner read/write only)\n- **Input Validation**: All inputs validated with Pydantic models\n- **No Command Injection**: No `shell=True` without sanitization\n- **Path Traversal Protection**: All file operations validated against project root\n\n### Security Scanning Results\n\nLatest scan (Session 8, 2025-10-21):\n- **Lines Scanned**: 5,609\n- **Issues Found**: 0\n- **Severity**: MEDIUM or higher checked\n- **Status**: \u2705 **PASSED**\n\n### Reporting Security Issues\n\n**DO NOT** create public issues for security vulnerabilities.\n\nInstead, please:\n1. Email security concerns to the maintainers\n2. Include: description, reproduction steps, potential impact, suggested fix\n3. We will respond within 48 hours\n\nSee [SECURITY.md](SECURITY.md) for detailed security guidelines.\n\n---\n\n## \ud83d\udd17 Links\n\n- **PyPI**: [https://pypi.org/project/clauxton/](https://pypi.org/project/clauxton/)\n- **GitHub**: [https://github.com/nakishiyaman/clauxton](https://github.com/nakishiyaman/clauxton)\n- **GitHub Releases**: [https://github.com/nakishiyaman/clauxton/releases](https://github.com/nakishiyaman/clauxton/releases)\n- **Issues**: [https://github.com/nakishiyaman/clauxton/issues](https://github.com/nakishiyaman/clauxton/issues)\n- **Discussions**: [https://github.com/nakishiyaman/clauxton/discussions](https://github.com/nakishiyaman/clauxton/discussions)\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\nThis 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.\n\n**Note**: Clauxton is an independent project and is not officially affiliated with Anthropic or Claude Code.\n\n---\n\n**Built with \u2764\ufe0f for Claude Code users**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Context that persists for Claude Code - Knowledge Base, Task Management, and Conflict Detection",
"version": "0.12.0",
"project_urls": {
"Documentation": "https://github.com/nakishiyaman/clauxton/wiki",
"Homepage": "https://github.com/nakishiyaman/clauxton",
"Issues": "https://github.com/nakishiyaman/clauxton/issues",
"Repository": "https://github.com/nakishiyaman/clauxton"
},
"split_keywords": [
"ai-assistant",
" claude",
" claude-code",
" context",
" knowledge-base",
" mcp",
" plugin",
" task-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ae5c80e4f977202d8146c821acbc4f935e4a5c2621aa11803b4959ed70af537a",
"md5": "720bfcace8b5cafd6ed94a14a1ceedb1",
"sha256": "de119558a43ff177f7ee85373564bfa71bb1acd11db2da76a18ab115af35c764"
},
"downloads": -1,
"filename": "clauxton-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "720bfcace8b5cafd6ed94a14a1ceedb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 159094,
"upload_time": "2025-10-26T08:35:10",
"upload_time_iso_8601": "2025-10-26T08:35:10.092774Z",
"url": "https://files.pythonhosted.org/packages/ae/5c/80e4f977202d8146c821acbc4f935e4a5c2621aa11803b4959ed70af537a/clauxton-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0c8911287bd80a6f59efad3ca03889443d799d9f6da024c464faac59c67a4e83",
"md5": "02d4eda659175a60e5b476f71b75d1dc",
"sha256": "9bc16856c4ed32e253326f0a47c1b4354f2313fd09c34e3a152d2d3af5fa9c37"
},
"downloads": -1,
"filename": "clauxton-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "02d4eda659175a60e5b476f71b75d1dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 1125029,
"upload_time": "2025-10-26T08:36:38",
"upload_time_iso_8601": "2025-10-26T08:36:38.411774Z",
"url": "https://files.pythonhosted.org/packages/0c/89/11287bd80a6f59efad3ca03889443d799d9f6da024c464faac59c67a4e83/clauxton-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 08:36:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nakishiyaman",
"github_project": "clauxton",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clauxton"
}
JSON
