Contributing your first PR

Interested in contributing to x? Bug fixes, new features, documentation improvements, and test coverage are all welcome. Here's everything you need to get started.

Dev setup

Terminal

# Clone the repo
$ git clone https://github.com/ClaudeX-md/claudex.git
$ cd x

# Install dependencies
$ npm install

# Run the test suite
$ npm test

# Build TypeScript
$ npm run build

# Run locally from source
$ node dist/cli.js

Project structure

Directory layout

x/
  src/
    cli.ts              # Entry point
    claude.ts           # Agent loop + write verification
    budget.ts           # Budget tracking + enforcement
    metrics.ts          # Token usage + cost calculation
    gateway.ts          # API proxy server
    sandbox.ts          # Sandboxed execution
    cron.ts             # Scheduled job runner
    commands/
      stats.ts          # x stats command
      serve.ts          # x serve command
      cron.ts           # x cron command
  test/
    bench.test.ts       # Benchmark harness tests
    budget.test.ts      # Budget module tests
    cron.test.ts        # Cron module tests
    sandbox.test.ts     # Sandbox tests
  bench/
    example-suite.json  # Reference benchmark suite
  web/
    index.html          # Landing page
    wiki/               # This wiki

Making changes

Fork the repo on GitHub and clone your fork
Branch from main: git checkout -b feat/my-feature
Make your changes — keep PRs focused on a single concern
Add tests for any behavioral changes. Tests live in test/ and use Vitest
Run checks:

Terminal

$ npm test              # all tests must pass
$ npm run build          # TypeScript must compile

PR guidelines

Title — Short, descriptive. Use conventional commits: feat:, fix:, docs:, test:, refactor:
Description — Explain what changed, why, and how to test it. Link any related issues.
Size — Smaller is better. A focused 50-line PR gets reviewed in hours. A 500-line PR sits for days.
Tests — If you changed behavior, add or update tests. If you fixed a bug, add a regression test.
No unrelated changes — Don't refactor neighboring code, update formatting, or fix typos in unrelated files. One concern per PR.

First-time contributors: Look for issues tagged good first issue on GitHub. These are scoped, well-described, and have maintainer context in the comments. They're designed to be completable in a single session.

Code style

TypeScript, strict mode
Named exports, no default exports
Avoid any — use specific types or unknown
Comments explain why, not what
No unnecessary abstractions — three similar lines are better than a premature helper

Review process

A maintainer will review your PR within a few days. Reviews focus on:

Correctness — does it do what it claims?
Simplicity — is this the simplest way to solve the problem?
Test coverage — are the important paths tested?
Consistency — does it match existing patterns in the codebase?

Feedback is collaborative, not adversarial. If a reviewer requests changes, they'll explain why. If you disagree, discuss it in the thread.