Skip to main content
We welcome contributions from everyone! This guide will help you understand our development workflow and standards.

​
Code of Conduct

​
Our Pledge

We are committed to providing a welcoming and inclusive environment for everyone. All participants are expected to uphold these standards.

​
Our Standards

We expect all participants to:
  • Be respectful and considerate in all interactions
  • Welcome newcomers and help them learn the codebase
  • Accept constructive feedback gracefully
  • Focus on what is best for the community and project

​
Enforcement

Instances of unacceptable behavior may be reported to: [email protected] All complaints will be reviewed and investigated promptly and fairly.
This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

​
Getting Started

Before you begin contributing:
1

Fork and clone the repository

git clone https://github.com/YOUR-USERNAME/craft-agents-oss.git
cd craft-agents-oss
2

Create a feature branch

Use descriptive branch names that follow our naming conventions:
git checkout -b feature/add-new-tool
3

Make your changes

Follow our code style and development practices outlined below.
4

Test your changes

Run type checks and ensure the app works:
bun run typecheck:all
bun run electron:dev

​
Branch Naming Conventions

Use clear, descriptive branch names that indicate the type and purpose of changes:
PrefixPurposeExample
feature/New featuresfeature/add-new-tool
fix/Bug fixesfix/resolve-auth-issue
refactor/Code refactoringrefactor/simplify-agent-loop
docs/Documentation updatesdocs/update-readme
test/Test additions or fixestest/add-session-tests
chore/Maintenance taskschore/update-dependencies

​
Code Style Guidelines

​
TypeScript Standards

// Use meaningful names
export async function createAgentSession(
  workspaceId: string,
  options: SessionOptions
): Promise<AgentSession> {
  // Implementation
}

// Add JSDoc for complex functions
/**
 * Summarizes large tool responses using Claude Haiku
 * @param response - The raw tool response
 * @param intent - The intended use context
 * @returns Summarized response text
 */
export function summarizeResponse(
  response: string,
  intent: string
): Promise<string> {
  // Implementation
}

​
Code Organization

  • Follow existing patterns in the codebase
  • Use meaningful variable and function names
  • Add comments for complex logic that isn’t self-explanatory
  • Keep functions focused on a single responsibility
  • Prefer composition over inheritance

​
Key Areas of the Codebase

AreaLocationPurpose
Agent Logicpackages/shared/src/agent/Core agent implementation and permissions
Authenticationpackages/shared/src/auth/OAuth, tokens, credential management
MCP Integrationpackages/shared/src/mcp/Model Context Protocol servers
UI Componentspackages/ui/src/Reusable React components
Electron Appapps/electron/Desktop application shell
Session Managementpackages/shared/src/sessions/Session persistence and state
Sourcespackages/shared/src/sources/MCP, API, and local data sources

​
Commit Conventions

Use clear, descriptive commit messages that explain what changed and why: 
git commit -m "feat: add support for custom OAuth providers"
git commit -m "fix: resolve race condition in session persistence"
git commit -m "docs: update API integration guide"
git commit -m "refactor: simplify agent permission checking logic"

​
Commit Message Format

<type>: <subject>

<optional body>

<optional footer>
Types:
  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • refactor - Code refactoring (no functional changes)
  • test - Adding or updating tests
  • chore - Maintenance tasks
  • perf - Performance improvements

​
Pull Request Process

1

Create a clear PR title

Use the same format as commit messages:
feat: add background task progress tracking
fix: resolve session loading race condition
docs: improve MCP integration guide
2

Write a comprehensive description

Use this template:
## Summary
Brief description of what this PR does and why.

## Changes
- Change 1: Added feature X
- Change 2: Fixed issue with Y
- Change 3: Refactored Z for clarity

## Testing
Describe how you tested these changes:
- Tested scenario A
- Verified fix for issue B
- Checked regression on feature C

## Screenshots (if applicable)
Include screenshots for UI changes
3

Ensure all checks pass

Before submitting:
bun run typecheck:all
4

Request review

Tag relevant maintainers or wait for automatic review assignment.
PRs that don’t pass type checking or have linting errors will not be merged. Please fix all issues before requesting review.

​
Testing Guidelines

​
Manual Testing

For UI changes, test:
  • Core functionality works as expected
  • Edge cases are handled properly
  • Different screen sizes render correctly
  • Keyboard shortcuts still work
  • Performance is not degraded

​
Automated Testing

Run the test suite: 
bun test

​
Documentation

When adding new features:
  • Update relevant documentation in the repository
  • Add JSDoc comments for public APIs
  • Include examples in code comments where helpful
  • Update README.md if necessary

​
Questions and Support

​
Getting Help

  • Open an issue for bugs or feature requests
  • Start a discussion for questions or ideas
  • Check existing issues before creating new ones

​
Issue Template

## Description
Clear description of the issue or feature request

## Steps to Reproduce (for bugs)
1. Step one
2. Step two
3. Expected vs actual behavior

## Environment
- OS: [e.g., macOS 14.0]
- Craft Agents version: [e.g., 0.6.0]
- Node/Bun version: [e.g., Bun 1.x]

​
License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0. This project uses:

​
Recognition

All contributors will be recognized in the project. Significant contributions may be highlighted in release notes.
Thank you for contributing to Craft Agents! Your efforts help make agent-native software more accessible to everyone.

​
Next Steps

Setup

Set up your development environment

Building

Learn how to build for production

Build docs developers (and LLMs) love

Get started for freeTalk to us