OpenShell/CONTRIBUTING.md

Contributing to OpenShell

Prerequisites

Install mise. This is used to set up the development environment.

# Install mise (macOS/Linux)
curl https://mise.run | sh

After installing mise, activate it with mise activate or add it to your shell.

Shell setup examples:

# Fish
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish

# Zsh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

Project requirements:

• Rust 1.88+
• Python 3.12+
• Docker (running)

Getting Started

# One-time trust
mise trust

# Launch a sandbox (deploys a cluster if one isn't running)
mise run sandbox

Building the openshell CLI

Inside this repository, openshell is a local shortcut script at scripts/bin/openshell. The script will

1. Build navigator-cli if needed.
2. Run the local debug CLI binary under target/debug/openshell.

Because mise adds scripts/bin to PATH for this project, you can run openshell directly from the repo.

openshell --help
openshell sandbox create -- codex

Main Tasks

These are the primary mise tasks for day-to-day development:

Task	Purpose
mise run cluster	Bootstrap or incremental deploy
mise run sandbox	Create a sandbox on the running cluster
mise run test	Default test suite
mise run e2e	Default end-to-end test lane
mise run ci	Full local CI checks (lint, compile/type checks, tests)
mise run docs	Build and serve documentation locally
mise run clean	Clean build artifacts

Project Structure

Path	Purpose
crates/	Rust crates
python/	Python SDK and bindings
proto/	Protocol buffer definitions
tasks/	mise task definitions and build scripts
deploy/	Dockerfiles, Helm chart, Kubernetes manifests
architecture/	Architecture docs and plans

Pull Requests

1. Create a feature branch from main
2. Make your changes with tests
3. Run mise run ci to verify
4. Open a PR with a clear description

Commit Messages

This project uses Conventional Commits. All commit messages must follow the format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• chore - Maintenance tasks (dependencies, build config)
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• ci - CI/CD changes
• perf - Performance improvements

Examples:

feat(cli): add --verbose flag to openshell run
fix(sandbox): handle timeout errors gracefully
docs: update installation instructions
chore(deps): bump tokio to 1.40

DCO

All contributions must include a Signed-off-by line in each commit message. This certifies you have the right to submit the work under the project license. See the Developer Certificate of Origin.

git commit -s -m "feat(sandbox): add new capability"

Use the create-github-pr skill to help with opening your pull request.