Skip to main content

think-tool Reference

Complete reference documentation for the think-tool MCP server.

Configuration​

Configuration File​

Default location: ~/.think-tool/config.json

{
  "license": "string",
  "reflection": {
    "autoTrigger": "boolean",
    "verbosity": "minimal|normal|detailed",
    "saveHistory": "boolean",
    "historyPath": "string",
    "maxHistorySize": "number",
    "triggers": {
      "commands": ["string"],
      "keywords": ["string"],
      "patterns": ["regex"],
      "complexity": "number",
      "errorRate": "number"
    },
    "export": {
      "format": "markdown|json|csv",
      "includeTimestamps": "boolean",
      "includeContext": "boolean"
    }
  },
  "server": {
    "port": "number",
    "host": "string",
    "ssl": {
      "enabled": "boolean",
      "cert": "string",
      "key": "string"
    }
  },
  "logging": {
    "level": "debug|info|warn|error",
    "file": "string",
    "maxSize": "string",
    "maxFiles": "number"
  }
}

Environment Variables​

Override configuration with environment variables:

VariableDescriptionDefault
THINK_TOOL_LICENSELicense keyRequired
THINK_TOOL_PORTServer port3461
THINK_TOOL_HOSTServer hostlocalhost
THINK_TOOL_VERBOSITYReflection detailnormal
THINK_TOOL_AUTO_TRIGGEREnable auto-triggertrue
THINK_TOOL_HISTORY_PATHHistory location~/.think-tool/history
THINK_TOOL_LOG_LEVELLogging levelinfo

CLI Commands​

Server Management​

# Start server
think-tool start [options]
  --port <number>      Server port
  --host <string>      Server host
  --config <path>      Config file path

# Stop server
think-tool stop

# Restart server
think-tool restart

# Check status
think-tool status

Configuration Management​

# View configuration
think-tool config show

# Set configuration value
think-tool config set <key> <value>

# Reset to defaults
think-tool config reset

# Validate configuration
think-tool config validate

History Management​

# View history
think-tool history [options]
  --since <date>       Start date
  --until <date>       End date
  --tag <string>       Filter by tag
  --limit <number>     Result limit

# Export history
think-tool export [options]
  --format <type>      Output format
  --output <path>      Output file
  --since <date>       Start date
  --tag <string>       Filter by tag

# Clear history
think-tool history clear [--before <date>]

# Search history
think-tool search <query> [options]
  --type <reflection|decision|error>
  --limit <number>

License Management​

# View license info
think-tool license info

# Verify license
think-tool license verify

# Update license
think-tool license update <key>

API Reference​

MCP Protocol​

think-tool implements the Model Context Protocol:

interface ThinkToolMCP {
  // Trigger reflection
  reflect(params: ReflectParams): ReflectionResult;
  
  // Get reflection history
  getHistory(params: HistoryParams): HistoryResult;
  
  // Export reflections
  export(params: ExportParams): ExportResult;
  
  // Configure server
  configure(params: ConfigParams): ConfigResult;
}

Reflection Parameters​

interface ReflectParams {
  // Type of reflection
  type: 'decision' | 'analysis' | 'debug' | 'review';
  
  // Context for reflection
  context: string;
  
  // Additional metadata
  metadata?: {
    tags?: string[];
    priority?: 'low' | 'medium' | 'high';
    relatedTo?: string[];
  };
  
  // Verbosity override
  verbosity?: 'minimal' | 'normal' | 'detailed';
}

Reflection Result​

interface ReflectionResult {
  // Unique reflection ID
  id: string;
  
  // Timestamp
  timestamp: string;
  
  // Reflection content
  content: {
    summary: string;
    details?: string;
    decisions?: Decision[];
    learnings?: Learning[];
  };
  
  // Metadata
  metadata: {
    duration: number;
    tokenCount: number;
    triggerType: string;
  };
}

Trigger Configuration​

Command Triggers​

Reflection triggers on specific Claude commands:

{
  "triggers": {
    "commands": [
      "bash",          // Shell commands
      "edit",          // File edits
      "write",         // File creation
      "delete",        // File deletion
      "git",           // Git operations
      "deploy"         // Deployment commands
    ]
  }
}

Keyword Triggers​

Trigger on specific keywords in prompts:

{
  "triggers": {
    "keywords": [
      "production",
      "security",
      "performance",
      "architecture",
      "delete",
      "critical",
      "payment",
      "authentication"
    ]
  }
}

Pattern Triggers​

Use regex patterns for complex triggers:

{
  "triggers": {
    "patterns": [
      "implement.*authentication",
      "refactor.*database",
      "optimize.*performance",
      "deploy.*production",
      "migrate.*data"
    ]
  }
}

Complexity Triggers​

Trigger based on task complexity:

{
  "triggers": {
    "complexity": 8  // 1-10 scale
  }
}

Verbosity Levels​

Minimal​

Quick, one-line reflections:

[REFLECTION] Using PostgreSQL for ACID compliance.

Normal (Default)​

Balanced detail with key points:

[REFLECTION] Database selection:
- PostgreSQL: ACID, complex queries ✓
- MongoDB: Flexible, but eventual consistency
Decision: PostgreSQL for data integrity

Detailed​

Comprehensive analysis:

[REFLECTION] Database selection process:

Requirements:
- Strong consistency (financial data)
- Complex queries (reporting)
- Transactions (multi-step operations)
- Scale: 100k users

PostgreSQL evaluation:
+ ACID compliance
+ Rich query language
+ Mature ecosystem
+ Window functions
- Vertical scaling limits
Score: 9/10

MongoDB evaluation:
+ Horizontal scaling
+ Flexible schema
+ Document model
- Eventual consistency
- Limited transactions
Score: 6/10

Decision: PostgreSQL
Rationale: Consistency > Scale for financial data
Migration path: Can shard later if needed

History Schema​

Storage Format​

Reflections stored as JSON:

{
  "id": "ref_abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "type": "decision",
  "content": {
    "summary": "Chose React over Vue",
    "details": "...",
    "decisions": [{
      "choice": "React",
      "rationale": "Team expertise",
      "alternatives": ["Vue", "Angular"]
    }]
  },
  "metadata": {
    "duration": 1234,
    "tokenCount": 567,
    "triggerType": "keyword",
    "tags": ["architecture", "frontend"],
    "sessionId": "sess_xyz789"
  }
}

Query Syntax​

Search history with structured queries:

# Find all architecture decisions
think-tool search "type:decision tag:architecture"

# Find reflections about performance
think-tool search "performance" --type analysis

# Complex query
think-tool search "database AND (postgres OR mysql)" --since 2024-01-01

Integration Examples​

With Claude Code​

// .claude/settings.json
{
  "mcp": {
    "think-tool": {
      "transport": "local",
      "command": "think-tool",
      "args": ["start", "--config", ".think-tool.json"]
    }
  }
}

With CI/CD​

# GitHub Actions
- name: Install think-tool
  run: npm install -g @claudefast/think-tool

- name: Configure
  env:
    THINK_TOOL_LICENSE: ${{ secrets.THINK_TOOL_LICENSE }}
  run: think-tool config validate

- name: Run with reflection
  run: |
    think-tool start --daemon
    claude -p "Deploy with reflection enabled"
    think-tool export --format json > reflections.json

With Docker Compose​

version: '3.8'
services:
  think-tool:
    image: claudefast/think-tool:latest
    environment:
      - THINK_TOOL_LICENSE=${THINK_TOOL_LICENSE}
      - THINK_TOOL_VERBOSITY=detailed
    ports:
      - "3461:3461"
    volumes:
      - think-tool-data:/data

volumes:
  think-tool-data:

Error Codes​

CodeDescriptionSolution
TT001Invalid licenseCheck license key
TT002Server start failedCheck port availability
TT003Configuration invalidValidate config file
TT004History corruptedRun history repair
TT005Export failedCheck disk space
TT006Connection timeoutCheck network settings
TT007Rate limit exceededUpgrade plan

Performance Tuning​

Memory Usage​

Control memory consumption:

{
  "reflection": {
    "maxHistorySize": 10000,  // Limit history entries
    "pruneAfterDays": 30      // Auto-cleanup
  }
}

Response Time​

Optimize reflection speed:

{
  "reflection": {
    "verbosity": "normal",     // Reduce from detailed
    "asyncProcessing": true,   // Non-blocking
    "cacheResults": true       // Cache similar reflections
  }
}

Security​

Network Security​

{
  "server": {
    "host": "127.0.0.1",  // Local only
    "ssl": {
      "enabled": true,
      "cert": "/path/to/cert.pem",
      "key": "/path/to/key.pem",
      "ca": "/path/to/ca.pem"
    },
    "auth": {
      "type": "token",
      "tokens": ["${AUTH_TOKEN}"]
    }
  }
}

Data Protection​

{
  "security": {
    "encryption": {
      "atRest": true,
      "algorithm": "aes-256-gcm"
    },
    "redaction": {
      "enabled": true,
      "patterns": ["password", "api_key", "secret"]
    }
  }
}

Troubleshooting​

Debug Mode​

Enable detailed logging:

think-tool start --debug

Common Issues​

Reflection not triggering:

# Check triggers
think-tool config show triggers

# Test trigger
think-tool test-trigger "implement authentication"

Performance issues:

# Check metrics
think-tool metrics

# Optimize
think-tool optimize

Next Steps​