v0.3.3 - Fix broken npm package

Release Notes - v0.3.3

Release Date: 2025-12-09
Previous Version: 0.3.2
Release Type: Patch (Critical bug fix)

---

Summary

Critical fix for broken v0.3.2 npm package. The v0.3.2 release was published without the dist/ directory, making the package non-functional.

What Happened

The v0.3.2 npm publish failed because:

1. The clean script removed .tsbuildinfo
2. But TypeScript actually creates tsconfig.tsbuildinfo
3. Stale build cache caused TypeScript to skip compilation
4. The dist/ directory was removed but not rebuilt
5. npm published an empty package

What's Fixed

• Clean script now removes the correct file (tsconfig.tsbuildinfo)
• Fresh build verified before publish

---

Bug Fixes

Fixed broken npm package

v0.3.2 contained only 3 files (LICENSE, README.md, package.json) instead of the full compiled package. Users who installed v0.3.2 would get a non-functional package.

If you installed v0.3.2, please upgrade immediately:

npm install claudine@0.3.3

Fixed clean script

Changed build cleanup from .tsbuildinfo to tsconfig.tsbuildinfo to match the actual filename TypeScript generates.

---

Migration Guide

If you have v0.3.2 installed:

npm update claudine
# or
npm install claudine@latest

---

Verification

After installation, verify the package is complete:

ls node_modules/claudine/dist/
# Should show: cli.js, index.js, and subdirectories

v0.3.2 - Tech Debt Cleanup & Type Safety

Release Notes - v0.3.2

Release Date: 2025-12-08
Previous Version: 0.3.1
Release Type: Patch (Tech debt cleanup, type safety improvements)

---

Summary

This patch release focuses on tech debt cleanup, type safety improvements, and dead code removal. No new features - purely internal quality improvements.

Highlights

• Type Safety: Replaced Record<string, any> with explicit row type interfaces
• Configurability: maxChainDepth now configurable via DependencyHandler.create() options
• Defense-in-Depth: Database CHECK constraint on resolution column
• Dead Code Removal: Removed 3 unused/deprecated methods from QueueHandler

---

Technical Improvements

Configurable Chain Depth Limit

The DependencyHandler.create() factory method now accepts an optional options parameter:

const handler = await DependencyHandler.create(
  dependencyRepo,
  taskRepo,
  logger,
  eventBus,
  { maxChainDepth: 50 }  // Optional, defaults to 100
);

This allows tests and deployments to customize the DoS protection limit.

Explicit Row Type Interfaces

Replaced dynamic Record<string, any> types with explicit interfaces:

• DependencyRow - Type-safe database row mapping for dependencies
• TaskRow - Type-safe database row mapping for tasks

This improves IDE autocomplete and catches type errors at compile time.

Database CHECK Constraint

Added CHECK constraint on resolution column via migration v2:

CHECK (resolution IN ('pending', 'completed', 'failed', 'cancelled'))

This provides defense-in-depth validation at the database level, complementing TypeScript validation.

---

Removed

Dead Code Cleanup

Removed 3 unused methods from QueueHandler:

• getQueueStats() - Copied entire task array just to return count
• getNextTask() - Deprecated, replaced by NextTaskQuery event
• requeueTask() - Deprecated, replaced by RequeueTask event

These methods had no callers and were marked deprecated without a removal timeline.

---

Documentation

Fixed Incorrect Complexity Claim

Updated getMaxDepth() documentation from incorrect "O(1) cached" to accurate "O(V+E) with internal memoization".

Architecture Documentation

Added CHECK constraint note to docs/architecture/TASK_ARCHITECTURE.md.

---

Migration Guide

No breaking changes. This is a drop-in replacement for v0.3.1.

---

Contributors

• Code review and cleanup via Claude Code /code-review workflow

🚀 Claudine v0.3.1

Release Notes - v0.3.1

Release Date: 2025-12-01
Previous Version: 0.3.0
Release Type: Patch (Bug fixes, security improvements, performance optimizations)

---

Summary

This patch release focuses on security hardening, performance optimizations, and critical bug fixes for the task dependency system introduced in v0.3.0.

Highlights

• CRITICAL FIX: Graph corruption bug in cycle detection that could cause unpredictable task execution
• Security: Input validation limits prevent DoS attacks on dependency system
• Performance: Settling workers tracking prevents spawn burst overload
• Reliability: Atomic multi-dependency transactions ensure data consistency

---

Security Fixes

CRITICAL: Graph Corruption Fix (Issue #28)

Deep copy in wouldCreateCycle() prevents dependency graph corruption.

Problem: Shallow copy (new Map(this.graph)) corrupted the dependency graph because Set values remained as references. Cycle detection could permanently add edges to the graph, causing unpredictable task execution.

Solution: Proper deep copy implementation:

new Map(Array.from(this.graph.entries()).map(([k, v]) => [k, new Set(v)]))

npm audit vulnerabilities fixed

Resolved 3 security issues:

• HIGH: glob CLI command injection (GHSA-5j98-mcp5-4vw2)
• MODERATE: body-parser denial of service (GHSA-wqch-xfxh-vrr4)
• MODERATE: vite path traversal on Windows (GHSA-93m4-6634-74q7)

Input Validation Limits (Issue #12)

Security hardening for dependency system:

• Maximum 100 dependencies per task to prevent DoS attacks
• Maximum 100 dependency chain depth to prevent stack overflow
• Clear error messages with current counts and limits
• Validation enforced at repository level for consistency

Configuration Validation Logging

No longer silently falls back to defaults when environment variables fail validation.

---

Performance Improvements

Settling Workers Tracking

Prevents spawn burst overload during high-load scenarios:

• Load average is a 1-minute rolling average that doesn't reflect recent spawns
• New recordSpawn() tracks workers in 15-second settling window
• Projects resource usage including workers not yet reflected in metrics
• Increased minSpawnDelayMs from 50ms to 1000ms for additional protection

Batch Dependency Resolution

10x speedup for dependency resolution operations (Issue #10).

Incremental Graph Updates

Eliminated O(N) findAll() calls with incremental graph updates (Issue #13).

---

Bug Fixes

• Command Injection: Fixed potential security vulnerabilities in git operations
• Test Reliability: Fixed flaky tests with proper mocking
• Parameter Consistency: Aligned CLI and MCP tool parameters

---

Technical Improvements

• Type safety: Replaced any type with Worker in getWorkerStats() return type
• Test compatibility: Added recordSpawn() to TestResourceMonitor

Atomic Multi-Dependency Transactions (Issue #11)

Data consistency improvements:

• New addDependencies() batch method with atomic all-or-nothing semantics
• Transaction rollback on any validation failure (cycle detection, duplicate, task not found)
• Prevents partial dependency state in database
• DependencyHandler updated to use atomic batch operations

Chain Depth Calculation

New DependencyGraph.getMaxDepth() algorithm:

• DFS with memoization for O(V+E) complexity
• Handles diamond-shaped graphs efficiently
• Used for security validation of chain depth limits

---

Test Coverage

• 5 new tests for settling workers tracking in ResourceMonitor
• 3 regression tests for graph immutability after cycle checks
• 18 tests for v0.3.1 security and consistency improvements:
  • 11 tests for atomic batch dependency operations (rollback, validation)
  • 3 tests for max dependencies per task validation (100 limit)
  • 1 test for max chain depth validation (100 limit)
  • 7 tests for DependencyGraph.getMaxDepth() algorithm

---

Documentation Updates

• Updated docs/architecture/TASK_ARCHITECTURE.md with correct deep copy pattern
• Fixed stale line numbers in docs/TASK-DEPENDENCIES.md (wouldCreateCycle at line 240)
• Fixed outdated version references and comments throughout codebase

---

Commits Included

fe6ad81 docs: fix outdated version references and comments (#34)
cb3da65 fix: tech debt cleanup - DRY utilities, performance optimizations, and documentation fixes (#33)
a924484 fix(tests): use inclusive bounds in packet loss rate assertion
1d35db1 fix(core): deep copy in wouldCreateCycle() prevents graph corruption + settling workers tracking (#32)
bcc8314 docs: update architecture docs for factory pattern (#30)
5e69695 fix: address code review feedback from incremental graph updates PR (#29)
c44fccc perf: Incremental Graph Updates - Eliminate O(N) findAll() Calls (#13) (#27)
e2fe6a2 perf: batch dependency resolution for 10x speedup (#10) (#26)
83de98d feat: v0.3.1 Quick Wins - Atomic Transactions & Input Validation (#23)
09a04e0 chore: documentation housekeeping and organization (#22)

---

Upgrade Instructions

From v0.3.0

This is a drop-in replacement. No migration required.

npm install -g claudine@0.3.1

Breaking Changes

None. This is a fully backward-compatible patch release.

---

Links

• Full Changelog
• Task Dependencies Documentation
• Architecture Documentation
• GitHub Issues

🚀 Claudine v0.3.0

🚀 Claudine v0.3.0 - Task Dependencies

Major Features

🔗 Task Dependencies with DAG-based Cycle Detection

The headline feature of v0.3.0 enables tasks to depend on other tasks, with automatic dependency resolution and cycle detection.

Key Capabilities:

• Dependency Declaration: Specify task dependencies via dependsOn array in task specifications
• Cycle Detection: DFS-based algorithm prevents both simple (A→B→A) and transitive (A→B→C→A) cycles
• Automatic State Transitions: Tasks automatically move from BLOCKED → QUEUED when dependencies complete
• Multiple Dependencies: Tasks can depend on multiple prerequisites simultaneously
• Diamond Patterns: Full support for complex dependency graphs (A→B, A→C, B→D, C→D)
• Failure Propagation: When a dependency fails, dependent tasks automatically fail

MCP API Enhancement:

await delegateTask({
  prompt: "deploy to production",
  dependsOn: ["task-build", "task-test"]  // New in v0.3.0
});

Event-Driven Integration:

• TaskDependencyAdded - Emitted when dependency relationship created
• DependencyResolved - Emitted when blocking dependency completes
• TaskUnblocked - Emitted when all dependencies resolved, triggers automatic queuing

Technical Implementation:

• Synchronous better-sqlite3 transactions for TOCTOU race condition protection
• Foreign key constraints with database-level referential integrity
• Composite indexes for optimized dependency lookups
• Handler-level graph cache to prevent N+1 query pattern

---

Bug Fixes

🔒 Security - TOCTOU Race Condition Fix

Critical security fix preventing race conditions in concurrent dependency creation.

Issue: Async transactions allowed JavaScript event loop to interleave between cycle detection and dependency insertion, potentially creating cycles despite validation.

Fix: Implemented synchronous .transaction() for true atomicity per Wikipedia TOCTOU principles - check and use operations are now atomic with no event loop yielding.

Impact: Prevents concurrent requests from creating circular dependencies.

🛠️ Error Handling Improvements

Issue: addDependency() converted all errors to SYSTEM_ERROR, masking semantic error types like TASK_NOT_FOUND and INVALID_OPERATION.

Fix: Preserve ClaudineError types throughout the error handling chain, allowing upstream code to correctly distinguish error types.

Impact: Better error handling and debugging experience.

🏃 Race Condition in QueueHandler

Issue: Event data could become stale between emission and handling, potentially enqueueing cancelled/failed tasks.

Fix: Fetch fresh task state from repository before enqueueing unblocked tasks.

Impact: Additional safety layer against race conditions during task unblocking.

📋 Migration Error Handling

Issue: getCurrentSchemaVersion() caught all errors and returned 0, potentially hiding permission errors, corruption, or connection issues.

Fix: Only catch "no such table" errors, re-throw all other errors.

Impact: Prevents silent failures that could cause data loss during migrations.

---

Infrastructure & Quality

✅ CI/CD Improvements

• Memory Management: Fixed heap exhaustion by using test:unit instead of running full suite multiple times
• Test Stability: Added 5ms timing tolerance for flaky network latency tests
• Worker-Handler Tests: Skipped in CI due to >6GB memory requirements (runs locally)
• Contents Permission: Added write permission for automated releases

📊 Code Quality

• Maintainability Score: 76.2/100 (GOOD)
• JSDoc Documentation: Added comprehensive documentation to all public methods
• Type Safety: Enhanced TypeScript type narrowing in error handling
• Test Coverage: 74 new tests for dependency system (100% passing)

📖 Documentation

• ARCHITECTURE_QUICK_REFERENCE.md: Quick reference for system architecture (308 lines)
• TASK_ARCHITECTURE.md: Detailed task system design documentation (747 lines)
• COMPLEXITY_AUDIT_REPORT.md: Comprehensive code quality audit
• docs/task-dependencies.md: Complete API documentation (707 lines)
• docs/test-stability-fixes.md: Test stability improvements documentation

🏗️ Database Schema Migrations

Implemented version-based migration system for safe production upgrades:

• schema_migrations table tracks applied migrations
• Transaction-wrapped migrations for safety
• Incremental version upgrades
• Baseline schema at v1

---

Test Coverage

🧪 Comprehensive Test Suite

• 74 new tests for task dependencies (all passing)
• 23 tests for DependencyGraph (cycle detection, topological sort)
• 35 tests for DependencyRepository (CRUD operations, TOCTOU protection)
• 16 tests for DependencyHandler (event-driven resolution)
• 7 integration tests for end-to-end workflows

Total: 81 tests passing (638 total across entire codebase)

---

Breaking Changes

None - All changes are backward compatible. The dependsOn field is optional in task specifications.

---

Known Limitations & Future Work

Two architectural improvements deferred to v0.3.1:

• Issue #20: Replace in-memory cycle detection with database-native recursive CTE for better scalability
• Issue #21: Move baseline schema into migration v1 for single source of truth

See ROADMAP.md for v0.3.1 plans.

---

Installation

npm install -g claudine@0.3.0

Or add to your .mcp.json:

{
  "mcpServers": {
    "claudine": {
      "command": "npx",
      "args": ["-y", "claudine@0.3.0", "mcp", "start"]
    }
  }
}

---

What's Next

v0.3.1 (Performance Optimizations):

• Database-native cycle detection with recursive CTEs
• Bulk dependency operations
• Dependency cache layer
• Query optimizations for large graphs

v0.4.0 (Advanced Features):

• Conditional dependencies
• Task retry with exponential backoff
• Resource constraints per task
• Enhanced worktree management

See ROADMAP.md for complete roadmap.

---

Upgrade Notes

No special upgrade steps required. Simply update to 0.3.0:

npm install -g claudine@0.3.0

Existing databases will automatically migrate to v1 schema on first startup.

---

Contributors

Special thanks to:

• Dean Sharon (@dean0x) - Feature implementation
• Claude Code - Development assistance and code review
• qodo-merge-for-open-source - PR review and quality checks

---

Links

• 📦 NPM Package: https://www.npmjs.com/package/claudine
• 📝 Full Documentation: https://github.com/dean0x/claudine/blob/main/docs/task-dependencies.md
• 🐛 Issues: https://github.com/dean0x/claudine/issues
• 💬 Discussions: https://github.com/dean0x/claudine/discussions

---

🤖 Generated with Claude Code

🚀 Claudine v0.2.3

🚀 Claudine v0.2.3 - Performance & Architecture Improvements

Major Features

Performance Optimization

• Heap-based Priority Queue: Replaced O(n²) array operations with O(log n) min-heap implementation
  • 100x performance improvement: 1000 tasks now process in 10ms (down from 1000ms)
  • O(1) task lookups via Map-based indexing
  • FIFO ordering preserved within same priority level

Architecture Improvements

• Strict Result Pattern Enforcement: Removed all throw statements from event handlers
  • BaseEventHandler.handleEvent() now returns Result<void>
  • BaseEventHandler.executeWithRetry() returns Result<void> after exhausting retries
  • Event system is now 100% exception-free in business logic

Security & Resource Management

• Simplified DoS Protection: Removed redundant rate limiting in favor of existing resource-level protections
  • Queue size limits (RESOURCE_EXHAUSTED when full)
  • Resource monitoring (workers only spawn when system has capacity)
  • Spawn throttling (prevents fork bombs)
  • Local-only MCP design doesn't require session-based rate limiting

Bug Fixes

• Critical: EventBus Timer Leak - Fixed resource leak where EventBus cleanup timer wasn't disposed

  • Container.dispose() now properly calls eventBus.dispose() to clear setInterval timers
  • Integration tests updated to use await container.dispose() instead of clear()
  • Eliminates "Unhandled Rejection: Channel closed" errors in test suite

• Test Infrastructure - Fixed TypeScript type mismatches in TestLogger

  • Updated context parameters from any to Record<string, unknown>
  • Now properly implements Logger interface

• Bootstrap Result Handling - Fixed integration tests to unwrap Result<Container>

  • All tests now properly handle bootstrap() returning Promise<Result<Container>>
  • Improved error handling and validation in test setup

• Path Validation - Added comprehensive path validation to prevent traversal attacks

  • Working directory validation at MCP adapter boundary
  • Security hardening for file system operations

Breaking Changes

⚠️ API Changes:

1. BaseEventHandler Methods - Event handlers now return Results instead of throwing:

   // BEFORE (v0.2.2):
   protected async handleEvent(): Promise<void> // Could throw
   
   // AFTER (v0.2.3):
   protected async handleEvent(): Promise<Result<void>> // Returns Result

2. Bootstrap Function - Now returns Result for consistent error handling:

   // BEFORE (v0.2.2):
   const container = await bootstrap();
   
   // AFTER (v0.2.3):
   const result = await bootstrap();
   if (!result.ok) throw new Error('Bootstrap failed');
   const container = result.value;

Migration Guide

For Custom Event Handlers

If you've created custom event handlers extending BaseEventHandler:

// Update your handler methods to return Result<void>
class MyCustomHandler extends BaseEventHandler {
  // BEFORE:
  private async handleMyEvent(event: MyEvent): Promise<void> {
    // ... may throw
  }

  // AFTER:
  private async handleMyEvent(event: MyEvent): Promise<Result<void>> {
    // ... return ok(undefined) or err(error)
    return ok(undefined);
  }
}

For Bootstrap Consumers

If you're using bootstrap() directly:

// Update to unwrap Result
const result = await bootstrap();

if (!result.ok) {
  // Handle bootstrap failure
  console.error('Bootstrap failed:', result.error.message);
  process.exit(1);
}

const container = result.value;
// Continue with container usage

For Container Lifecycle

Always use dispose() instead of clear():

// BEFORE:
container.clear(); // ❌ Doesn't clean up resources

// AFTER:
await container.dispose(); // ✅ Properly disposes EventBus, workers, database

Test Results

• 638 tests passing - All unit, integration, and E2E tests pass cleanly
• Zero unhandled rejections - Fixed timer leak that caused test errors
• Performance validated - Heap-based queue tested with 1000+ tasks

Technical Details

Priority Queue Implementation

The new heap-based implementation uses:

• Binary min-heap for O(log n) enqueue/dequeue
• Map-based index for O(1) task lookups and removal
• Insertion counter for FIFO ordering within same priority
• Proper heap invariant maintenance via bubble-up/bubble-down

Resource Cleanup

The disposal chain now properly cascades:

1. Container.dispose() - Emits shutdown events
2. WorkerPool.killAll() - Terminates all workers
3. Database.close() - Closes SQLite connections
4. EventBus.dispose() - Clears cleanup timer
5. Container.clear() - Clears service registry

Event-Driven Architecture

All components now strictly follow event-driven patterns:

• No direct throws in event handlers
• All operations return Result
• EventBus handles error propagation
• Consistent error handling across all layers

Installation

npm install -g claudine@0.2.3

What's Next

See ROADMAP.md for upcoming features:

• Enhanced git worktree support
• GitHub PR automation improvements
• Advanced autoscaling strategies
• Distributed task execution

🚀 Claudine v0.2.2 - Enhanced Reliability & Developer Experience

Major Features

• 🔄 Retry Logic with Exponential Backoff: Smart retry mechanism for transient failures in git operations and GitHub API calls, improving reliability in unstable network conditions
• 🏷️ Process Naming: Easy process identification with named processes (claudine-cli, claudine-mcp) and environment variables for workers, enabling better process management
• 🌳 Git Worktree Support: Branch-based task isolation using git worktrees prevents conflicts between parallel tasks
• 🐙 GitHub Integration: Automatic PR creation from task results with configurable merge strategies and custom PR titles/descriptions

Improvements

• CLI/MCP Parameter Alignment: Full parameter parity between CLI and MCP tools
  • Added --tail parameter to logs command
  • Added reason parameter to cancel command
• Error Handling: Fixed deprecated listTasks() method usage in CLI status command
• Process Management: Workers now include CLAUDINE_WORKER environment variable with task ID
• Documentation: Comprehensive updates to README, ROADMAP, CLAUDE.md, and FEATURES.md

Bug Fixes

• Fixed CLI commands not exiting properly after successful execution
• Corrected typo in .gitignore (ouput → output)
• Removed tracked .docs folder from git while preserving local files

Developer Experience

• Task retry mechanism design documented for handling interrupted tasks
• Improved test configuration and fixed flaky tests
• All 135 tests passing consistently

Breaking Changes

None - All changes are backward compatible

Installation

npm install -g claudine@0.2.2

What's Next

• Implementation of automatic task retry on interruption
• Enhanced resource monitoring and adaptive scaling
• WebSocket support for real-time task updates

See ROADMAP.md for the complete list of upcoming features.

Contributors

This release includes contributions from Claude Code 🤖

---

For more information, visit the GitHub repository

🚀 Claudine v0.2.1 - Event-Driven Architecture & CLI Interface

Major Features

🖥️ Direct CLI Interface

No more MCP reconnections needed for testing! New commands:

claudine delegate "analyze the codebase for security issues"
claudine status                    # Check all tasks  
claudine status <task-id>          # Check specific task
claudine logs <task-id>            # Get task output
claudine cancel <task-id> "reason" # Cancel with reason

🏗️ Complete Event-Driven Architecture Overhaul

• EventBus Coordination: All components now communicate through events, not direct method calls
• Zero Direct State Management: TaskManager is purely event-driven
• Specialized Event Handlers:
  • PersistenceHandler - Database operations
  • QueueHandler - Task queue management
  • WorkerHandler - Worker lifecycle
  • OutputHandler - Output capture and logs
• Race Condition Elimination: Event-driven design prevents worker pool races

Critical Bug Fixes

🐛 Process Handling

• Fixed Claude CLI Hanging: Replaced stdin JSON injection hack with proper stdio: ['ignore', 'pipe', 'pipe']
• Robust Process Spawning: No more meaningless workarounds or stdin expectations

🐛 Exit Code Preservation

• Fixed Success Status Bug: Changed code || null to code ?? null to preserve exit code 0
• Proper Task Completion: Tasks now correctly complete with success status instead of failing

🐛 Event System

• Fixed Missing TaskQueued Events: Tasks were stuck in queued status due to missing event emissions
• Singleton EventBus: All components now share the same EventBus instance

Documentation Overhaul

📚 Golden Circle Framework

• README.md: Applied Sinek's WHY → HOW → WHAT structure for better user engagement
• Clear Problem Statement: Specific pain points users face with sequential Claude Code execution
• Compelling Vision: Transform servers into AI powerhouses

📚 Complete Documentation Update

• CLAUDE.md: Rewritten to reflect event-driven architecture
• FEATURES.md: Updated with v0.2.1 capabilities and event patterns
• CHANGELOG.md: Consolidated and accurate version history

Technical Improvements

🔧 Architecture

• Event-Driven Coordination: TaskDelegated, TaskQueued, WorkerSpawned events
• Cleaner Separation: Each handler has clear, isolated responsibilities
• Better Error Handling: Improved error propagation through Result pattern

🔧 Developer Experience

• Faster Testing: CLI commands eliminate MCP reconnection overhead
• Better Debugging: Event flow easier to trace than direct method calls
• Production Ready: Significantly more stable and reliable

Breaking Changes

None - All changes are internal architecture improvements. MCP tools remain fully compatible.

Migration

• Automatic: No user action required
• Backward Compatible: All existing MCP tool usage continues to work
• CLI Addition: New CLI commands are additive features

Installation

# Global installation (recommended)
npm install -g claudine@0.2.1

# Or from source
git clone https://github.com/dean0x/claudine.git
cd claudine
npm install && npm run build

What's Next

See ROADMAP.md:

• v0.3.0: Task dependency resolution (Q4 2025)
• v0.4.0: Distributed processing (Q1 2026)

---

Full Details: CHANGELOG.md
Repository: https://github.com/dean0x/claudine
Issues: GitHub Issues

🚀 Claudine v0.2.0 - Task Persistence & Stability

Major Features

✨ Task Persistence

• SQLite-based persistence: All tasks are now stored in a local SQLite database
• Automatic recovery: Tasks queued before a crash are automatically re-queued on startup
• Platform-specific storage:
  • Unix/Mac: ~/.claudine/claudine.db
  • Windows: %APPDATA%/claudine/claudine.db
• Task history: Complete history of all delegated tasks with status, logs, and metadata

🔧 MCP Connection Stability

• Fixed stdout/stderr separation: Logs now properly go to stderr, keeping stdout clean for MCP protocol
• Improved CLI integration: Fixed dynamic import issues for reliable MCP server startup
• Better error handling: Graceful handling of connection issues and proper error reporting

🎯 Claude CLI Integration

• Corrected CLI flags: Using --print for non-interactive mode (not --no-interaction)
• Proper prompt passing: Prompts now passed as command arguments with --print flag
• Maintained permission bypass: --dangerously-skip-permissions for automated execution

Architecture Improvements

SOLID Refactoring

• Dependency Injection: Complete DI container implementation
• Result Types: Functional error handling without exceptions
• Clean Interfaces: Well-defined contracts between components
• Immutable State: No mutations, always return new objects
• Composable Functions: Pipe-based function composition

Database Design

• WAL mode: Write-Ahead Logging for better concurrency
• Prepared statements: Efficient and secure database operations
• Automatic migrations: Database schema created automatically
• Output overflow handling: Large outputs (>100KB) stored as files

Bug Fixes

• Fixed MCP server connection issues
• Resolved Claude CLI command execution errors
• Fixed process spawning with correct arguments
• Corrected logging to avoid stdout pollution
• Fixed task recovery on startup

Breaking Changes

• None - fully backward compatible with v0.1.x

Migration Guide

No migration needed. The database will be created automatically on first run.

What's Next

• Phase 2: Git worktree support for isolated task execution
• Phase 3: Web dashboard for task monitoring
• Phase 4: Task dependencies and chaining
• Phase 5: Distributed execution across multiple machines

Installation

# npm
npm install -g claudine

# or use npx
npx claudine mcp start

Configuration

Add to your MCP configuration:

{
  "mcpServers": {
    "claudine": {
      "command": "claudine",
      "args": ["mcp", "start"]
    }
  }
}

Contributors

• Initial implementation and architecture
• SOLID refactoring and persistence layer
• MCP protocol fixes and stability improvements

---

For detailed documentation, visit: https://github.com/dean0x/claudine

Claudine v0.1.0 - Initial Release

Introducing Claudine: Your MCP Sidekick for Claude Code

Claudine is an MCP (Model Context Protocol) server that enables Claude Code to delegate tasks to background Claude Code instances, allowing for true parallel task execution without context switching.

✨ Features

Core Tools

• DelegateTask: Spawn background Claude Code processes with custom prompts
• TaskStatus: Monitor task execution state in real-time
• TaskLogs: Retrieve captured output from delegated tasks
• CancelTask: Gracefully terminate running tasks

Advanced Capabilities

• Custom Working Directories: Control exactly where tasks execute
• Git Worktree Isolation: Run experimental changes in isolated environments
• Auto-Permissions: Skip file permission prompts with --dangerously-skip-permissions
• Smart Output Capture: 10MB buffer with overflow protection

📦 Installation

# Clone the repository
git clone https://github.com/dean0x/claudine.git
cd claudine

# Install and build
npm install
npm run build

# Test the installation
node dist/cli.js mcp test

🎯 Use Cases

• Parallel Development: Work on API while tests update in background
• Bulk Refactoring: Update imports across entire codebase
• Documentation Generation: Auto-generate docs while coding
• Test Execution: Run test suites without blocking development
• Code Analysis: Analyze codebase complexity in background

📊 Example Usage

In Claude Code, after configuring MCP:

Use DelegateTask to run: "Generate comprehensive API documentation"

Use TaskStatus to check the current task

Use TaskLogs to retrieve the output

With optional parameters:

Use DelegateTask with workingDirectory "/workspace/docs" to run: "Create README"

Use DelegateTask with useWorktree true to run: "Experimental refactor"

🔧 Configuration

Add to ~/.config/claude/mcp_servers.json:

{
  "mcpServers": {
    "claudine": {
      "command": "node",
      "args": ["/absolute/path/to/claudine/dist/index.js"],
      "env": {}
    }
  }
}

🖥️ CLI Usage

# Start the MCP server manually
claudine mcp start

# Test in mock mode
claudine mcp test

# Show help
claudine help

📈 Performance

• Server startup: <100ms
• Tool response: <50ms
• Task execution: Variable based on task complexity
• Memory usage: ~45MB base

🚦 Current Limitations (MVP)

• Single task execution (no concurrency yet)
• In-memory state (no persistence)
• No task dependencies or priorities
• 30-minute timeout per task

🗺️ Roadmap

v0.2.0 - Concurrency

• Multiple concurrent tasks (3-5)
• Task queue management
• Priority levels

v0.3.0 - CLI Interface

• Direct task delegation: claudine delegate "task"
• Status monitoring: claudine status
• Log retrieval: claudine logs <id>

v0.4.0 - Persistence

• SQLite task history
• Resume after restart
• Task search and filtering

🤝 Contributing

We welcome contributions! Feel free to:

• Report bugs via GitHub Issues
• Suggest features
• Submit pull requests

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with Anthropic's MCP SDK
• Developed with Claude Code
• Special thanks to the MCP community

📞 Support

• Issues: GitHub Issues
• Documentation: Full Docs
• Examples: Use Cases

🎉 Get Started

1. Clone and install Claudine
2. Configure MCP in Claude Code
3. Start delegating tasks!

Ready to parallelize your Claude Code workflow? Let's go! 🚀

---

Repository: https://github.com/dean0x/claudine
Version: 0.1.0
Release Date: August 17, 2025