Cmux Ghostty

cmux Ghostty

GhosttyKit builds

When rebuilding GhosttyKit.xcframework, always use Release optimizations:

cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast

Submodule workflow

Ghostty changes must be committed in the ghostty submodule and pushed to the manaflow-ai/ghostty fork. Keep docs/ghostty-fork.md up to date with any fork changes and conflict notes.

cd ghostty
git remote -v  # origin = upstream, manaflow = fork
git checkout -b <branch>
git add <files>
git commit -m "..."
git push manaflow <branch>

To keep the fork up to date with upstream:

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

Then update the parent repo with the new submodule SHA:

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

Submodule safety

When modifying a submodule, always push the submodule commit to its remote main branch before committing the updated pointer in the parent repo. Never commit on a detached HEAD or temporary branch; the commit can be orphaned and lost.

Verify with:

cd <submodule> && git merge-base --is-ancestor HEAD origin/main

Detailed reference

• Read references/submodule-safety.md before committing submodule pointer updates or resolving Ghostty fork conflicts.

Submodule Safety

Submodule commits can be easy to lose. The parent repository records only a commit SHA, not the branch that made the SHA reachable.

Safe sequence

1. Enter the submodule. 2. Create or select the intended branch. 3. Commit the submodule changes. 4. Push the submodule commit to the correct remote. 5. Verify the pushed branch contains the commit. 6. Return to the parent repository. 7. Commit the updated submodule pointer.

For Ghostty:

cd ghostty
git remote -v
git checkout -b <branch>
git add <files>
git commit -m "..."
git push manaflow <branch>

If the parent pointer is supposed to track fork main, make sure the commit is an ancestor of that remote branch:

git fetch manaflow main
git merge-base --is-ancestor HEAD manaflow/main

The top-level CLAUDE note uses origin/main as the generic verification form for submodules. In the Ghostty submodule, check the actual remote names first because origin may be upstream and manaflow may be the fork.

Detached HEAD hazard

Do not commit submodule changes on a detached HEAD and then update the parent pointer. That creates a parent commit pointing at a SHA that may not be reachable from any remote branch. A future checkout or CI job can fail to fetch it.

Fork documentation

Keep docs/ghostty-fork.md updated when fork changes or conflict notes matter for future upstream merges. The point is to preserve why the fork diverged, not just that it diverged.

GhosttyKit optimization

Rebuild GhosttyKit.xcframework with ReleaseFast:

cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast

Debug or default optimization builds can hide performance characteristics and should not be used for the checked-in framework refresh path.