Contributing - Thinkwell

Thank you for your interest in contributing to Thinkwell! This guide will help you get set up and explain our development workflow.

Development Setup

Prerequisites

Node.js 24+ with native TypeScript support
pnpm as the package manager

Clone and Install

git clone https://github.com/dherman/thinkwell.git
cd thinkwell
pnpm install

Run in Development Mode

You can run TypeScript files directly using Node.js with native TypeScript support:

node --experimental-transform-types src/cli.ts

Build

To build the project:

pnpm build

This uses esbuild to bundle the code, followed by @yao-pkg/pkg for binary packaging.

Important: Do Not Use Bun

This project explicitly does not use Bun for runtime or binary distribution. We encountered fundamental limitations with Bun’s module resolution from its virtual filesystem that prevented user scripts from importing packages. See doc/rfd/pkg-migration.md in the repository for the full technical analysis.

Running Tests

Run the test suite with:

pnpm test

To run tests in watch mode during development:

pnpm test:watch

Commit Message Format

This project uses Conventional Commits for clear history and automated release management. All commit messages should follow this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

Type	Description	Version Bump
`feat`	A new feature	Minor
`fix`	A bug fix	Patch
`docs`	Documentation only changes	None
`style`	Code style changes (formatting, semicolons, etc.)	None
`refactor`	Code changes that neither fix bugs nor add features	None
`perf`	Performance improvements	None
`test`	Adding or updating tests	None
`chore`	Maintenance tasks, dependency updates	None
`ci`	CI/CD configuration changes	None
`build`	Build system or external dependency changes	None

Common Scopes

acp - Core protocol changes
thinkwell - High-level API changes
conductor - Conductor-specific changes
deps - Dependency updates

Breaking Changes

Indicate breaking changes by adding ! after the type:

feat!: change API to use async traits

Or include BREAKING CHANGE: in the commit footer:

feat: redesign conductor protocol

BREAKING CHANGE: conductor now requires explicit capability registration

Examples

feat(conductor): add support for dynamic proxy chains
fix(acp): resolve deadlock in message routing
docs: update README with installation instructions
chore(deps): bump @agentclientprotocol/sdk to 0.12.0

Pull Request Process

Create a branch from main with a descriptive name:
git checkout -b feat/add-new-connector
Make your changes with clear, focused commits following the conventional commits format.
Run tests to ensure your changes work correctly:
pnpm test
Push your branch and open a pull request against main.
Describe your changes in the PR description. Include:
- What the change does
- Why it’s needed
- Any breaking changes or migration steps
Address review feedback by pushing additional commits. We squash merge PRs, so don’t worry about commit count.

Code Style Guidelines

TypeScript

Use TypeScript for all source code
Prefer explicit types over any
Use JSDoc comments for public APIs
Use the @JSONSchema decorator for interfaces that need schema generation

Formatting

The project uses consistent formatting rules. Before committing:

pnpm lint
pnpm format

File Organization

Source code lives in src/
Tests are co-located with source files or in __tests__/ directories
Documentation source is in website/

Naming Conventions

Use camelCase for variables and functions
Use PascalCase for classes, interfaces, and types
Use UPPER_SNAKE_CASE for constants
Use descriptive names that convey intent

Getting Help

If you have questions or need help:

Open a GitHub Issue
Check existing issues for similar problems
Read through the documentation

We appreciate all contributions, whether it’s fixing a typo, improving documentation, or adding new features. Thank you for helping make Thinkwell better!

​Development Setup

​Prerequisites

​Clone and Install

​Run in Development Mode

​Build

​Important: Do Not Use Bun

​Running Tests

​Commit Message Format

​Commit Types

​Common Scopes

​Breaking Changes

​Examples

​Pull Request Process

​Code Style Guidelines

​TypeScript

​Formatting

​File Organization

​Naming Conventions

​Getting Help