Contributing to Thoughtbox

July 6, 2026 · View on GitHub

Thank you for your interest in contributing to Thoughtbox! This guide covers our development workflow, commit conventions, and testing approach.

Client Compatibility Note

Thoughtbox is currently optimized for use with Claude Code. The MCP ecosystem includes many clients with varying levels of support for protocol capabilities — server features (prompts, resources, tools), client features (roots, sampling, elicitation), and behaviors like listChanged notifications. We're actively working on broader client compatibility, but this requires custom adaptations for different clients.

Areas where we especially welcome contributions:

  • Client-specific adapters or compatibility layers
  • Documentation of client behavior differences
  • Bug reports from non-Claude Code clients (please include client name and version)
  • Testing across different MCP clients

If you're interested in helping with client compatibility, see the gateway/ directory for an example of how we handle clients that don't respond to notifications/tools/list_changed mid-turn.

Development Setup

# Clone the repository
git clone https://github.com/Kastalien-Research/thoughtbox.git
cd thoughtbox

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Development with hot reload
pnpm run dev

Commit Conventions

We use structured commit messages optimized for code comprehension tools like thick_read. Good commit history is documentation.

Format

<type>(<scope>): <subject>

<body - explain WHY, not just what>

<footer - references, co-authors>

Types

TypeDescription
featNew feature or capability
fixBug fix
fix(security)Security-related fix
refactorCode restructuring without behavior change
docsDocumentation only
testAdding or updating tests
choreBuild, tooling, dependency updates

Scope (Optional)

The component or area being changed: thoughtbox, notebook, observatory, mental-models, thick-read, persistence, etc.

Writing Good Commit Bodies

The commit body should explain WHY the change was made. Think of future readers using thick_read or git blame who need to understand the reasoning behind the code.

Good:

fix(security): prevent shell injection in git commands

The previous implementation used exec() with template strings,
allowing filenames containing shell metacharacters to execute
arbitrary commands. Changed to execFile() with argument arrays
which passes arguments directly without shell interpretation.

Addresses reviewer feedback from security audit.

Bad:

fix: update thick-read.ts

Changed exec to execFile in git commands.

Ticket References

Include references to issues, PRs, or external tickets:

Fixes #123
Addresses review feedback from #456
Related to PROJ-789

Co-Authored-By

When collaborating with AI tools or pair programming:

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Testing

# Unit and integration tests (vitest)
pnpm test

# Behavioral contract tests (live agent-in-the-loop, requires API access)
pnpm test:behavioral

Unit tests live in src/**/__tests__/ and src/**/*.test.ts. Behavioral contract tests (scripts/agents/test-behavioral-contracts.ts) verify that agent surfaces actually reason about their inputs.

Pull Request Process

  1. Branch from main: Create a feature branch with a descriptive name

    • feat/thick-read - new feature
    • fix/shell-injection - bug fix
    • refactor/storage-layer - refactoring

  2. Make focused commits: Each commit should be atomic and self-explanatory

  3. Run tests: Ensure pnpm test passes before pushing

  4. Create PR with context: Include:

    • Summary of changes
    • Why the change is needed
    • Test plan or verification steps

  5. Address review feedback: Commit fixes separately (don't squash), so reviewers can see what changed

Architecture Overview

src/
├── index.ts              # Entry point (stdio/HTTP transport selection)
├── server-factory.ts     # MCP server factory with tool registration
├── tool-registry.ts      # Progressive disclosure (stage-based tool enabling)
├── tool-descriptions.ts  # Stage-specific tool descriptions
├── thought-handler.ts    # Thoughtbox tool logic with critique support
├── gateway/              # Always-on routing tool for streaming HTTP clients
│   ├── gateway-handler.ts  # Routes to handlers with stage enforcement
│   └── index.ts          # Module exports
├── init/                 # Init workflow and state management
│   ├── tool-handler.ts   # Init tool operations
│   └── state-manager.ts  # Session state persistence
├── sessions/             # Session tool handler
├── persistence/          # Storage layer
├── observatory/          # Real-time visualization UI
├── mental-models/        # 15 reasoning frameworks
├── notebook/             # Literate programming engine
└── resources/            # Documentation and patterns

Key principles:

  • Tools are stateless handlers that receive input and return results
  • State lives in persistence layer with session isolation
  • Observatory is event-driven via WebSocket for real-time updates
  • Progressive disclosure stages tools based on workflow progress
  • Gateway pattern provides always-on routing for clients that don't refresh tool lists

Code Style

  • TypeScript with strict mode
  • ES modules (.js extensions in imports)
  • Zod for schema validation (v4 syntax)
  • No external runtime dependencies beyond Node.js built-ins and MCP SDK

Questions?

Open an issue or discussion on GitHub. We're happy to help!