Calmhive v14.0.0 Architecture

July 6, 2025 · View on GitHub

Technical guide for understanding and extending Calmhive CLI

Overview

Calmhive v14.0.0 features a comprehensive 6-command architecture that provides clear separation between interactive chat, headless automation, background processing, and scheduled automation. Built on Node.js with MCP integration for powerful tools and natural language scheduling.

⬅️ Back to README | 🌐 Calmhive.com | 🔗 Prompthive.sh

Core Commands

🗣️ calmhive chat - Interactive Claude

Purpose: Direct conversation with Claude with full tool access

# Interactive session
calmhive chat

# Direct question
calmhive chat "analyze this codebase"

# Pipe mode
echo "question" | calmhive chat -p

# Continue previous session
calmhive chat -c "let's continue"

# Resume specific session
calmhive chat -r

# Use different model
calmhive chat --model opus "complex analysis task"

Features:

  • ✅ Supports ALL Claude flags (-c, -r, -p, --model, etc.)
  • ✅ Auto tool access (86 tools: 15 core + 71 MCP integrations)
  • ✅ True interactive experience
  • ✅ Perfect for Q&A, exploration, debugging

🚀 calmhive run - Headless Automation

Purpose: Non-interactive task execution with smart prompting

# Execute tasks headlessly
calmhive run "create comprehensive test suite"
calmhive run "fix authentication bug and verify"
calmhive run "analyze performance and create report"
calmhive run "refactor API for better maintainability"

Features:

  • ✅ TRUE headless execution (non-interactive)
  • ✅ Smart prompting with MCP integration
  • ✅ Sequential thinking for complex tasks
  • ✅ Automatic verification requirements
  • ✅ Comprehensive tool integration
  • ✅ Perfect for automation, scripts, CI/CD

🎤 calmhive voice - Voice Interface

Purpose: Voice input to Claude (with text fallback)

calmhive voice --test    # Test voice dependencies
calmhive voice           # Start voice interface

📊 calmhive tui - Process Management

Purpose: Terminal UI for monitoring and managing processes

calmhive tui            # Launch TUI
calmhive tui -m         # Monitor-only mode

🔄 calmhive afk - Background Processing

Purpose: Long-running background tasks with monitoring

# Start background task
calmhive afk "analyze entire codebase and create documentation" --iterations 5

# Monitor processes
calmhive afk status              # Compact view
calmhive afk status -d           # Detailed view
calmhive afk tail <session-id>   # Live logs
calmhive afk stop <session-id>   # Stop session

📅 calmhive schedule - Automated Task Scheduling

Purpose: Natural language cron scheduling with Claude integration

# Create scheduled tasks
calmhive schedule create "daily at 9am" "calmhive run 'analyze security logs'"
calmhive schedule create "weekly on Friday" "calmhive afk 'generate reports' --iterations 5"

# Manage schedules
calmhive schedule list           # Show all scheduled tasks
calmhive schedule status         # Check schedule daemon
calmhive schedule stop <id>      # Remove scheduled task

When to Use Each Command

CommandUse CaseModeExample
chatQuestions, exploration, debuggingInteractive"How does this code work?"
runTasks, fixes, automationHeadless"Fix the login bug"
voiceHands-free interactionInteractiveVoice input
tuiProcess monitoringInteractiveVisual process management
afkLong-running tasksBackgroundMulti-step analysis
scheduleAutomated recurring tasksDaemon"Daily security audit"

Architecture Highlights

  • Clean Separation: Interactive (chat) vs Headless (run) vs Background (afk) vs Scheduled (schedule)
  • True Automation: Proper stdin handling enables genuinely non-interactive execution
  • Natural Language Scheduling: Convert "daily at 9am" to cron expressions via ClaudeCronParser
  • Template System: Variable substitution for complex automation workflows
  • MCP Integration: 95+ tools available including Sequential Thinking, Playwright, GitHub, Asana
  • Adaptive Retry: Intelligent handling of Claude API usage limits
  • Context Compression: Automatic /compact handling when approaching context limits
  • Process Management: SQLite-backed session tracking with beautiful TUI

Implementation Details

Chat Command

  • Direct passthrough to Claude
  • Automatically adds all 95+ tools (15 core + 80+ MCP integrations)
  • Supports all Claude flags unchanged
  • Uses stdio: 'inherit' for full interactivity

Run Command

  • Uses Claude -p flag correctly
  • Pipes stdin (like AFk) for true headless execution
  • Smart prompting encourages MCP tool usage
  • Includes verification requirements
  • No stdio: 'inherit' - truly non-interactive

Schedule Command

  • Natural language cron scheduling via ClaudeCronParser
  • Template variable substitution support
  • Background daemon manages scheduled tasks
  • Integrates with AFk for complex automation workflows
  • JSON-based schedule persistence

Smart Prompting in Run

The run command automatically enhances your task with:

  • Instructions to use MCP tools appropriately
  • Sequential thinking for complex analysis
  • Verification requirements
  • Knowledge storage suggestions
  • Protocol compliance ("lets bee friends")

Tool Access & MCP Setup

All commands have access to 95+ tools:

  • 15 Default Tools: File ops, search, bash, web tools, etc.
  • 80+ Safe MCP Tools: Read-only operations across 10+ MCP servers
    • Memento: Knowledge graph operations
    • Sequential Thinking: Structured analysis
    • GitHub/GitMCP: Code research
    • Playwright: Browser automation
    • Context7: Library documentation
    • Figma: Design file access
    • And more...

Setting Up MCP Tools

IMPORTANT: Calmhive requires Claude Max, Pro, or Teams subscription for MCP (Model Context Protocol) tools. Claude Free users can use basic chat/run commands but advanced features are limited.

Why Claude Max? While Pro/Teams subscriptions work perfectly, Claude Max offers 5-20x higher rate limits, making it ideal for long-running AFk sessions and heavy automation workflows.

Easy Setup: The fastest way to get MCP tools working is:

  1. Install Claude Desktop and configure your MCP tools there
  2. Import to Claude CLI: 
    claude mcp add-from-claude-desktop -s user
  3. Verify: Run calmhive chat "test sequential thinking" to confirm tools work

For detailed MCP setup instructions, see the Terminal Velocity blog post which covers installation of essential tools like Sequential Thinking.

File Structure

v3/
├── bin/calmhive          # Main entry point
├── cmd/                  # Command implementations
│   ├── chat             # Interactive Claude
│   ├── run              # Headless automation
│   ├── afk              # Background processing
│   ├── voice            # Voice control
│   ├── tui              # Terminal UI
│   ├── schedule         # Natural language scheduling
│   └── work             # Intelligent task automation
├── lib/                 # Core libraries
│   ├── adaptive-retry.js       # Usage limit handling
│   ├── process-manager.js      # AFk process control
│   ├── session-database.js     # SQLite session storage
│   ├── tool-manager.js         # MCP tool integration
│   ├── compact-handler.js      # Context compression 
│   ├── context-monitor.js      # Usage tracking
│   └── scheduler/              # Scheduling engine
│       ├── schedule-engine.js  # Core scheduling logic
│       └── claude-cron-parser.js # Natural language to cron
└── config/
    └── allowed-tools.json      # 95+ available tools (15 core + 80+ MCP)

Testing

Run Test Suite

cd /path/to/calmhive/v3
node tests/run-all-tests.js

Manual Testing

# Test each command type
calmhive chat "hello"           # Interactive
calmhive run "create test.txt"  # Headless
calmhive afk "analyze" -i 1     # Background
calmhive voice --test           # Voice deps
calmhive tui                   # Process UI
calmhive schedule list          # Scheduling
calmhive work "fix bug"         # Smart automation

Contributing

  1. Add a Command: Create new file in cmd/ directory following existing patterns
  2. Add a Tool: Update config/allowed-tools.json with safe MCP tools
  3. Test: Add tests to tests/ and update run-all-tests.js
  4. Document: Update README.md and this file

Key Components

Adaptive Retry (lib/adaptive-retry.js)

Handles Claude API usage limits with exponential backoff (30s → 60s → 120s → 240s...)

Process Manager (lib/process-manager.js)

Manages AFk background processes with proper cleanup and iteration tracking. Includes integrated context compression handling.

Session Database (lib/session-database.js)

SQLite storage for process metadata, logs, and state management

Schedule Engine (lib/scheduler/schedule-engine.js)

Core scheduling logic for managing cron-based automation:

  • Daemon process management
  • Task execution coordination
  • Error handling and retry logic
  • Schedule persistence and restoration

Claude Cron Parser (lib/scheduler/claude-cron-parser.js)

Natural language to cron expression conversion:

  • Converts "daily at 9am" to "0 9 * * *"
  • Supports complex scheduling patterns
  • Validates and normalizes expressions
  • JSON output format for automation

Compact Handler (lib/compact-handler.js)

Automatically handles context compression when Claude approaches limits:

  • Tries multiple /compact command formats for compatibility
  • Provides fallback manual compression strategies
  • Integrates seamlessly with AFk sessions

Context Monitor (lib/context-monitor.js)

Tracks and analyzes context usage patterns:

  • Monitors context consumption across iterations
  • Logs compression attempts and success rates
  • Generates usage reports for optimization

Need help? Check the README or run calmhive <command> --help