Skip to main content
Thank you for your interest in contributing to cmux! This guide will help you get started with development.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • macOS 14+
  • Xcode 15+
  • Zig - Install via Homebrew: brew install zig

​
Getting started

​
1. Clone the repository

Clone the repository with submodules: 
git clone --recursive https://github.com/manaflow-ai/cmux.git
cd cmux

​
2. Run the setup script

Initialize submodules and build dependencies: 
./scripts/setup.sh
This script will:
  • Initialize git submodules (ghostty, homebrew-cmux)
  • Build the GhosttyKit.xcframework from source
  • Create necessary symlinks

​
3. Build and run

Launch the debug app: 
./scripts/reload.sh

​
Development scripts

The following scripts help streamline development:
ScriptDescription
./scripts/setup.shOne-time setup (submodules + xcframework)
./scripts/reload.shBuild and launch Debug app
./scripts/reloadp.shBuild and launch Release app
./scripts/reload2.shReload both Debug and Release
./scripts/rebuild.shClean rebuild

​
Rebuilding GhosttyKit

If you make changes to the ghostty submodule, rebuild the xcframework: 
cd ghostty
zig build -Demit-xcframework=true -Doptimize=ReleaseFast

​
Running tests

​
Basic tests (run on VM)

ssh cmux-vm 'cd /Users/cmux/GhosttyTabs && xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination "platform=macOS" build && pkill -x "cmux DEV" || true && APP=$(find /Users/cmux/Library/Developer/Xcode/DerivedData -path "*/Build/Products/Debug/cmux DEV.app" -print -quit) && open "$APP" && for i in {1..20}; do [ -S /tmp/cmux.sock ] && break; sleep 0.5; done && python3 tests/test_update_timing.py && python3 tests/test_signals_auto.py && python3 tests/test_ctrl_socket.py && python3 tests/test_notifications.py'

​
UI tests (run on VM)

ssh cmux-vm 'cd /Users/cmux/GhosttyTabs && xcodebuild -project GhosttyTabs.xcodeproj -scheme cmux -configuration Debug -destination "platform=macOS" -only-testing:cmuxUITests test'

​
Working with the Ghostty submodule

The ghostty submodule points to manaflow-ai/ghostty, a fork of the upstream Ghostty project.

​
Making changes to ghostty

cd ghostty
git checkout -b my-feature
# make your changes
git add .
git commit -m "Description of changes"
git push manaflow my-feature

​
Keeping the fork updated

To sync with upstream Ghostty: 
cd ghostty
git fetch origin
git checkout main
git merge origin/main
git push manaflow main
Then update the parent repository: 
cd ..
git add ghostty
git commit -m "Update ghostty submodule"
See docs/ghostty-fork.md in the repository for details on fork changes and conflict notes.

​
Ways to contribute

There are many ways to get involved with cmux:

​
Community engagement

​
Code contributions

  • Fix bugs and submit pull requests
  • Add new features that align with cmux’s philosophy
  • Improve documentation
  • Write tests

​
Bug reports and feature requests

  • Create detailed GitHub issues
  • Include reproduction steps for bugs
  • Provide context and use cases for feature requests

​
Development guidelines

When contributing code:
  • Follow existing code style and conventions
  • Write clear commit messages
  • Test your changes thoroughly
  • Update documentation as needed
  • Keep changes focused and atomic
Before making significant changes, consider opening a discussion or issue to align with the project’s direction and avoid duplicate work.

​
License

By contributing to this repository, you agree that your contributions are licensed under the project’s GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

​
Community

Connect with the cmux community: