Skip to main content

Using think-tool

Learn how to effectively use think-tool to enhance Claude's reasoning capabilities.

Basic Usage​

Automatic Reflections​

Once installed, think-tool automatically triggers reflections:

You: Implement user authentication

Claude: [REFLECTION] Planning authentication implementation:
- Requirements: Secure, scalable, user-friendly
- Options considered:
  1. JWT: Stateless, good for APIs ✓
  2. Sessions: Stateful, server burden
  3. OAuth: Complex for simple auth
- Decision: JWT with refresh tokens

Now implementing authentication...

Manual Triggers​

Force reflection with keywords:

You: Think carefully about our database schema

Claude: [REFLECTION] Database schema analysis:
- Current entities: User, Product, Order
- Relationships:
  - User 1:N Order (customer)
  - Product N:M Order (through OrderItem)
- Considerations:
  - Normalization: Currently 3NF
  - Performance: May need denormalization
  - Scalability: Partition by date?
...

Reflection Patterns​

Decision Making​

You: Should we use GraphQL or REST?

Claude: [REFLECTION] API Architecture Decision:

Evaluating GraphQL:
+ Flexible queries
+ Strong typing
+ Real-time subscriptions
- Learning curve
- Complexity overhead

Evaluating REST:
+ Simple, well-understood
+ Great tooling
+ Cache-friendly
- Over/under-fetching
- Multiple requests

Context Analysis:
- Team size: Small (3 devs)
- Experience: REST experts
- Requirements: Simple CRUD

Recommendation: REST
- Faster development
- Team expertise
- Sufficient for needs

Problem Solving​

You: Users report slow page loads

Claude: [REFLECTION] Performance Investigation:

1. Gathering metrics:
   - Page load: 4.2s average
   - TTFB: 1.8s
   - Client render: 2.4s

2. Analyzing bottlenecks:
   - Server response slow ✓
   - Large JavaScript bundle ✓
   - Unoptimized images ✓

3. Root causes:
   - N+1 queries in API
   - No code splitting
   - Missing image CDN

4. Solution priority:
   1. Fix N+1 queries (quick win)
   2. Implement code splitting
   3. Add image optimization

Let me start with the queries...

Error Debugging​

You: Getting "undefined is not a function" error

Claude: [REFLECTION] Debugging TypeError:

Error location: app.js:142
Stack trace analysis:
- getUserData() called
- Attempts user.getName()
- user is undefined

Hypothesis chain:
1. Is user null? Checking...
2. Async race condition? Possible
3. Incorrect import? No

Found: API returns null for deleted users
Missing: Null check before method call

Solution: Add defensive programming

Advanced Usage​

Configuring Verbosity​

Control reflection detail level:

# Minimal reflections
think-tool config set verbosity minimal

# Normal (default)
think-tool config set verbosity normal

# Detailed analysis
think-tool config set verbosity detailed

Example outputs:

Minimal:

[REFLECTION] Choosing React over Vue due to team experience.

Normal:

[REFLECTION] Framework selection:
- React: Team knows it, large ecosystem ✓
- Vue: Simpler, but learning curve
Decision: React

Detailed:

[REFLECTION] Framework selection process:
Criteria weighted analysis:
1. Team expertise (40%): React 10/10, Vue 3/10
2. Ecosystem (30%): React 9/10, Vue 8/10
3. Performance (20%): React 8/10, Vue 9/10
4. Learning curve (10%): React 6/10, Vue 9/10

Weighted scores:
- React: 8.8/10
- Vue: 6.7/10

Decision: React
Rationale: Team productivity outweighs other factors

Reflection Triggers​

Customize when reflections occur:

{
  "triggers": {
    "commands": ["bash", "edit", "write"],
    "keywords": ["production", "delete", "security"],
    "patterns": [
      "implement.*authentication",
      "refactor.*database",
      "optimize.*performance"
    ],
    "complexity": 8,
    "errorRate": 0.1
  }
}

Exporting Reflections​

Export reflection history:

# Export as markdown
think-tool export --format markdown --output reflections.md

# Export as JSON for analysis
think-tool export --format json --output reflections.json

# Export with filters
think-tool export --since "2024-01-01" --tag "architecture"

Practical Examples​

Example 1: Architecture Planning​

You: Design a real-time chat system

Claude: [REFLECTION] Real-time chat architecture:

Requirements Analysis:
- Scale: 10k concurrent users
- Features: 1:1, groups, typing indicators
- Platforms: Web, iOS, Android

Technology Evaluation:

WebSockets:
+ Full duplex
+ Low latency
- Scaling complexity
- Connection management

Socket.io:
+ Fallbacks
+ Reconnection
+ Room management
- Additional abstraction

Server-Sent Events:
+ Simple
+ HTTP/2 compatible
- One-way only

Decision Stack:
- Transport: Socket.io (reliability)
- Backend: Node.js (event-driven)
- Queue: Redis (pub/sub)
- Database: PostgreSQL (messages)
- Cache: Redis (presence)

Architecture:
[Client] <-> [LB] <-> [Socket servers] <-> [Redis] <-> [DB]

Implementing this design...

Example 2: Security Review​

You: Review our authentication for security issues

Claude: [REFLECTION] Security audit of authentication:

Reviewing implementation...

✓ Positive findings:
- Passwords hashed with bcrypt
- HTTPS enforced
- Rate limiting present

⚠️ Concerns found:

1. Weak password policy
   Risk: Brute force susceptible
   Fix: Require 12+ chars, complexity

2. No account lockout
   Risk: Unlimited login attempts
   Fix: Lock after 5 failures

3. JWT secret in code
   Risk: Secret exposure
   Fix: Use environment variable

4. Missing CSRF protection
   Risk: Cross-site attacks
   Fix: Implement CSRF tokens

5. Session timeout too long
   Risk: Session hijacking
   Fix: 30-minute timeout

Priority fixes (by severity):
1. JWT secret exposure (Critical)
2. CSRF protection (High)
3. Account lockout (High)
4. Password policy (Medium)
5. Session timeout (Medium)

Starting with critical fixes...

Example 3: Performance Optimization​

You: Optimize our React app performance

Claude: [REFLECTION] React performance analysis:

Profiling results:
- Initial load: 3.8s
- Largest component: UserDashboard (892ms)
- Re-renders: 47 per interaction
- Bundle size: 2.4MB

Optimization opportunities:

1. Component level:
   - Excessive re-renders
   - Missing React.memo
   - Inline functions in render

2. State management:
   - Global state for local data
   - No selector optimization
   - Missing memoization

3. Bundle optimization:
   - No code splitting
   - Unused dependencies
   - Large images in bundle

4. Network:
   - Sequential API calls
   - No request caching
   - Missing prefetch

Action plan:
1. Add React.memo to 15 components
2. Implement code splitting (save 60%)
3. Optimize images (save 800KB)
4. Parallelize API calls
5. Add React Query for caching

Expected improvement: 65% faster

Implementing optimizations...

Best Practices​

1. Review Reflections​

Periodically review reflections:

Show me today's architectural decisions from think-tool

2. Tag Important Reflections​

Tag that database decision as "important" for future reference

3. Learn from History​

What patterns have we discovered in our performance optimizations?

4. Share Team Knowledge​

Export and share valuable reflections:

think-tool export --tag "architecture" --format markdown > team-decisions.md

5. Iterative Refinement​

Use reflections to improve:

Based on our debugging reflections, what debugging process should we follow?

Integration Tips​

With claude-setup​

/project:develop my-app --with-reflection

[REFLECTION] Project setup decisions:
- Framework: Next.js (SEO + React)
- Database: PostgreSQL (ACID)
- Auth: NextAuth (integrated)
- Styling: Tailwind (utility-first)

With Git Workflows​

Before committing, reflect on the changes and their impact

[REFLECTION] Commit review:
- Changes: Refactored auth module
- Impact: Breaking API change
- Migration: Required for v2 clients
- Risk: Medium (tested thoroughly)

With Testing​

Reflect on our test coverage gaps

[REFLECTION] Test analysis:
- Unit coverage: 85% (good)
- Integration: 60% (needs work)
- E2E: 40% (critical gap)
- Missing: Error scenarios
- Priority: Add error case tests

Next Steps​