Contributing Guide

How to set up the development environment, add features, write tests, and submit pull requests.

Development Setup

Fork and clone

git clone https://github.com/YOUR_USERNAME/cdoing-agent.git
cd cdoing-agent

Install dependencies

yarn install

Build all packages

yarn build

Start development mode

yarn dev

Runs all packages in watch mode with Turbo. Changes to any package automatically rebuild dependents.

Test your changes

yarn start

Builds core + ai and launches the CLI for manual testing.

Project Architecture at a Glance

Key Principle

Dependencies flow one way: core ← ai ← cli / vscode. Never import from a higher-level package into a lower-level one.

Package	When to Modify
@cdoing/core	Adding tools, changing permissions/sandbox, new context providers, indexing improvements
@cdoing/ai	LLM provider changes, agent loop behavior, prompt engineering, context management
@cdoing/cli	CLI commands, terminal UI, configuration, output formats
cdoing-vscode	VS Code commands, webview UI, inline editing, autocomplete

Common Contribution Types

Adding a New Tool

This is one of the most common contributions. Follow these steps:

Create packages/core/src/tools/my-tool.ts

import { BaseTool, ToolDefinition } from "./registry";

export class MyTool extends BaseTool {
  definition: ToolDefinition = {
    name: "my_tool",
    description: "Clear description of what this tool does",
    parameters: {
      type: "object",
      properties: {
        input: {
          type: "string",
          description: "What this parameter is for",
        },
      },
      required: ["input"],
    },
  };

  async execute(params: { input: string }): Promise<string> {
    // Your implementation here
    // Always return a string result
    return "Tool result";
  }
}

Export from core index

Add export { MyTool } from "./tools/my-tool"; to packages/core/src/index.ts.

Add your tool to the registry in packages/cli/src/tools.ts.

Add your tool to packages/vscode-extension/src/chat-panel-provider.ts.

Adding a Context Provider

Create packages/core/src/context-providers/my-provider.ts

import { ContextProvider } from "./registry";

export class MyProvider implements ContextProvider {
  trigger = "@mycontext";
  description = "Provides custom context";

  async resolve(args: string): Promise<string> {
    // Fetch and return the context
    return "Context content here";
  }

  getSuggestions(partial: string): string[] {
    return ["@mycontext option1", "@mycontext option2"];
  }
}

Add your provider to the registry in the context providers module.

Adding an LLM Provider

New LLM providers are added in packages/ai/src/provider.ts:

Add a new value to the ModelProvider enum
Add a new case in the provider factory function
Use @langchain/openai for OpenAI-compatible APIs or add a new LangChain package
Update the CLI config wizard in packages/cli/src/config.ts

Code Style Guidelines

TypeScript strict mode — All packages use strict: true
CommonJS output — All packages compile to CommonJS (ES2022 target)
No default exports — Use named exports consistently
JSON Schema for tool parameters — No Zod, no io-ts. Raw JSON Schema for maximum LLM compatibility
Minimal dependencies — Especially in the core package. Think twice before adding a new dependency
Error messages for users — Tool errors should be human-readable strings the LLM can understand and relay

Pull Request Process

Create a feature branch

git checkout -b feature/my-new-feature

Make your changes

Follow the code style guidelines. Keep changes focused — one feature or fix per PR.

Build and test

yarn build
yarn start  # Manual testing

Write a clear commit message

git commit -m "feat(core): add my-tool for doing X

Brief description of what the tool does and why it's useful."

Open a pull request

Include a description of the changes, why they're needed, and how to test them. Reference any related issues.

Commit Message Convention

Follow the conventional commits format:

type(scope): description

Types:
  feat     — New feature
  fix      — Bug fix
  refactor — Code restructuring (no feature change)
  docs     — Documentation only
  chore    — Build, tooling, or dependency changes
  perf     — Performance improvement

Scopes:
  core     — @cdoing/core package
  ai       — @cdoing/ai package
  cli      — @cdoing/cli package
  vscode   — VS Code extension
  docs     — Documentation

File Locations Reference

Quick reference for where to find and modify things:

Want to...	Look at...
Add a new tool	packages/core/src/tools/
Change permission logic	packages/core/src/permissions/index.ts
Modify sandbox rules	packages/core/src/sandbox/
Add a context provider	packages/core/src/context-providers/
Change the indexer	packages/core/src/indexing/
Modify the agent loop	packages/ai/src/agent-runner.ts
Add an LLM provider	packages/ai/src/provider.ts
Change the system prompt	packages/ai/src/system-prompt.ts
Add a CLI flag	packages/cli/src/index.ts
Add a CLI subcommand	packages/cli/src/commands.ts
Modify chat UI (VS Code)	packages/vscode-extension/src/webview/
Add a VS Code command	packages/vscode-extension/src/extension.ts

Need Help?

Open an issue on the repository if you have questions or need guidance on implementing a feature. We're happy to help!