Skip to content
Gee-Code

Contributing

Gee-Code is open-source and we welcome contributions. This guide covers everything you need to get from zero to a merged pull request.

Prerequisites

Section titled “Prerequisites”
  • Python 3.10+ — the runtime and all backend code
  • Node.js 18+ — for the MCP server layer and the docs site
  • Git — with a GitHub account
  • A working installation of Gee-Code (see Installation)

Setting Up a Dev Environment

Section titled “Setting Up a Dev Environment”

1. Fork and clone

Section titled “1. Fork and clone”

Fork the repository on GitHub, then clone your fork:

Terminal window
git clone https://github.com/<your-username>/gee-code.git
cd gee-code

2. Create a virtual environment

Section titled “2. Create a virtual environment”
Terminal window
python -m venv .venv
source .venv/bin/activate

3. Install in development mode

Section titled “3. Install in development mode”
Terminal window
pip install -e ".[dev]"

This installs gee-code as an editable package with development dependencies (pytest, ruff, etc.).

4. Optional extras

Section titled “4. Optional extras”
Terminal window
# Token counting support
pip install -e ".[tokens]"


# PDF reading support
pip install -e ".[pdf]"


# Everything
pip install -e ".[all]"

5. Browser automation (optional)

Section titled “5. Browser automation (optional)”

If you’re working on browser tools:

Terminal window
gee-code setup browser

6. Verify your setup

Section titled “6. Verify your setup”
Terminal window
gee-code --version
gee-code setup check

Project Structure

Section titled “Project Structure”
gee-code/
├── gee_code/           # Main Python package
│   ├── ai/             # AI provider adapters and model routing
│   ├── agents/         # Agent system, flights, swarms
│   ├── auth/           # Authentication
│   ├── beads/          # Task graph planning and execution
│   ├── chat/           # Chat session management
│   ├── companion/      # Companion server (daemon, tunnel)
│   ├── context/        # Context management and extractors
│   ├── events/         # Event system
│   ├── explore/        # Codebase exploration
│   ├── mcp/            # MCP server implementation
│   ├── memory/         # Persistent memory
│   ├── modes/          # Autonomous modes and daemon
│   ├── permissions/    # Permission system
│   ├── plugins/        # Plugin loading and management
│   ├── rlm/            # RLM sandbox
│   ├── setup/          # Setup and dependency management
│   ├── surfaces/       # UI surfaces (web, terminal)
│   ├── tasks/          # Background task management
│   ├── tools/          # 100+ built-in tools
│   └── ui/             # Terminal UI components
├── web-surface/        # Web UI (Vite + TypeScript)
├── docs-site/          # Documentation (Astro Starlight)
├── tests/              # Test suite
└── scripts/            # Build and release scripts

Code Standards

Section titled “Code Standards”

Python

Section titled “Python”

We use Ruff for linting and formatting.

  • Line length: 100 characters
  • Target version: Python 3.10
  • Lint rules: E, F, I, N, W (with E501 ignored since we handle line length at 100)

Run the linter:

Terminal window
ruff check gee_code/
ruff format --check gee_code/

Auto-fix issues:

Terminal window
ruff check --fix gee_code/
ruff format gee_code/

JavaScript/TypeScript (web-surface)

Section titled “JavaScript/TypeScript (web-surface)”
Terminal window
cd web-surface
npm run lint
npm run build

Commit messages

Section titled “Commit messages”

Write clear, descriptive commit messages. We use a conventional format:

feat(tools): add screenshot tool for DevBrowser
fix(memory): prevent duplicate memory entries
docs(getting-started): update installation steps
chore(deps): bump anthropic to 0.75.0

Prefixes: feat, fix, docs, chore, refactor, test, perf

Scope (optional): the subsystem affected — tools, agents, memory, modes, ai, mcp, beads, companion, docs, web-surface, etc.

Running Tests

Section titled “Running Tests”
Terminal window
# Run the full suite
pytest


# Run all tests including integration
bash tests/run_all_tests.sh


# Run a specific test file
pytest tests/test_rlm_sandbox.py


# Run with verbose output
pytest -v

Tests use pytest with pytest-asyncio for async test support. The test configuration is in pyproject.toml.

Making Changes

Section titled “Making Changes”

1. Create a branch

Section titled “1. Create a branch”
Terminal window
git checkout -b feat/your-feature-name

2. Make your changes

Section titled “2. Make your changes”

Follow the code standards above. Keep changes focused — one feature or fix per branch.

3. Test your changes

Section titled “3. Test your changes”

Run the relevant tests before submitting. If you’re adding a new feature, add tests for it.

4. Submit a pull request

Section titled “4. Submit a pull request”

Push your branch and open a PR against main. Include:

  • A clear description of what changed and why
  • Screenshots or terminal output if the change is visual or behavioral
  • Any relevant issue numbers

What to Contribute

Section titled “What to Contribute”

Good first contributions

Section titled “Good first contributions”
  • Documentation improvements — typos, clarifications, missing examples
  • Tool descriptions — better help text for existing tools
  • Bug reports — detailed reproduction steps help enormously

Larger contributions

Section titled “Larger contributions”
  • New tools — add capabilities to gee_code/tools/
  • Provider adapters — support for additional AI models in gee_code/ai/
  • Skills — reusable skill packages (see Creating Skills)
  • Plugins — bundled extensions (see Building Plugins)

Before you start

Section titled “Before you start”

For anything beyond a small fix, open an issue or discussion first. This saves time — we can confirm the change is wanted and point you toward the right approach before you write code.

Documentation

Section titled “Documentation”

The docs site lives in docs-site/ and uses Astro Starlight.

Run the docs locally

Section titled “Run the docs locally”
Terminal window
cd docs-site
npm install
npm run dev

The site will be available at http://localhost:4321.

Build and verify

Section titled “Build and verify”
Terminal window
cd docs-site
npm run build

This catches broken links, missing frontmatter, and other issues. Always build before submitting doc changes.

Writing docs

Section titled “Writing docs”
  • Use the existing page structure as a guide — frontmatter with title and description, then content
  • Keep language direct and concrete
  • Include code examples where they help
  • Link to related pages using absolute paths (e.g., /getting-started/installation/)

Release Process

Section titled “Release Process”

Releases are managed by the core team using the scripts in scripts/:

Terminal window
# Build a release package
./scripts/build-release.sh


# Create a release (dry-run first)
./scripts/release.sh --dry-run --minor

Contributors don’t need to worry about versioning — we handle that during the merge.

Getting Help

Section titled “Getting Help”