Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (116 loc) · 5.74 KB

CONTRIBUTING.md

File metadata and controls

161 lines (116 loc) · 5.74 KB
Raw

Contributing to cmux

Prerequisites

  • macOS 14+

  • Xcode 26 (the pinned toolchain); Xcode 16.2 on Intel Macs running macOS 14 also builds the macOS app (best effort)

  • Zig (install via brew install zig)

  • Rust — scripts/setup.sh requires rustup, and every app build compiles the bundled cmux-cua engine with cargo. The official installer puts both in ~/.cargo/bin, which is where setup.sh looks:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    Homebrew's rustup formula works too, but it is keg-only and no longer ships rustup-init, so add $(brew --prefix rustup)/bin to PATH and run rustup default stable yourself.

  • On Xcode 26 the Metal compiler is a separately downloaded component, and the build fails without it. Select the intended full Xcode installation first (DEVELOPER_DIR, if exported, overrides xcode-select), then install the component:

    xcodebuild -downloadComponent MetalToolchain

Getting Started

  1. Clone the repository with submodules:

    git clone --recursive https://github.com/manaflow-ai/cmux.git
cd cmux

  2. Run the setup script:

    ./scripts/setup.sh

    This will:

    • Initialize git submodules (ghostty, homebrew-cmux)
    • Install the pinned Rust toolchain
    • Fetch a checksum-pinned prebuilt GhosttyKit.xcframework, falling back to building it from source with Zig (force the source build with CMUX_GHOSTTYKIT_NO_PREBUILT=1)
    • Create the necessary symlinks

  3. Build the debug app:

    ./scripts/reload.sh --tag my-feature

    The script prints the .app path. Cmd-click to open, or pass --launch to open automatically.

Development Scripts

Script Description
./scripts/setup.sh One-time setup (submodules + xcframework)
./scripts/reload.sh Build Debug app (pass --launch to also open it)
./scripts/reloadp.sh Build and launch Release app
./scripts/reload2.sh Reload both Debug and Release
./scripts/rebuild.sh Clean rebuild

Team dogfood setup

DEBUG builds can auto-sign-in as you and auto-attach an iOS build to your Mac with no manual steps. Each developer does a one-time setup with their own Stack account.

Run this once:

scripts/setup-team-dev.sh

It prompts for your Stack email and password (the password is never echoed), verifies them against Stack, and writes ~/.secrets/cmuxterm-dev.env with chmod 600. Re-running it is safe; if you are already configured it prints the account and exits. To reset, delete ~/.secrets/cmuxterm-dev.env and run it again.

After that, every dev build signs you in automatically:

scripts/dev-setup.sh --tag <your-initials>

That builds the tagged macOS DEBUG app auto-signed-in as you, enables the iOS pairing host, mints an attach ticket, and launches the iOS dev build auto-attached to your Mac. Use --surface mac for macOS only. See scripts/dev-setup.sh --help for all flags.

This is DEBUG-only and per-user. The credentials file lives outside the repo and is never committed; scripts/cmuxterm-dev.env.example is the in-repo template. Release builds never read these credentials (the auto-sign-in path is compiled out of release).

Web and JS Tooling

Run Biome from the repository root with:

bun run biome:check

The root biome.json intentionally scopes biome check . to maintained web and JS/TS sources. It excludes generated bundles, build outputs, vendored trees, and review-tool metadata such as .greptile/. Biome formatting and import sorting are disabled for now; do not wire this into required CI until the remaining source lint diagnostics are paid down.

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/cmux && xcodebuild -project cmux.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_v2/test_update_timing.py && python3 tests_v2/test_signals_auto.py && python3 tests_v2/test_ctrl_socket.py && python3 tests_v2/test_notifications.py'

UI tests (run on VM)

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

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 changes
git add .
git commit -m "Description of changes"
git push manaflow my-feature

Keeping the fork updated

cd ghostty
git fetch origin
git checkout main
git merge origin/main
git push manaflow main

Then update the parent repo:

cd ..
git add ghostty
git commit -m "Update ghostty submodule"

See docs/ghostty-fork.md for details on fork changes and conflict notes.

License

By contributing to this repository, you agree that:

  1. Your contributions are licensed under the project's GNU General Public License v3.0 or later (GPL-3.0-or-later).
  2. You grant Manaflow, Inc. a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license to use, reproduce, modify, sublicense, and distribute your contributions under any license, including a commercial license offered to third parties.