Developer Notes

Repository Orientation

Building GhosttyKit

The Xcode project links ghostty/macos/GhosttyKit.xcframework. This framework is generated from the pinned Ghostty submodule and is not stored directly in the repository.

Prerequisites

• The full Xcode application, with xcode-select pointing to /Applications/Xcode.app/Contents/Developer, and Xcode's optional Metal Toolchain component.
• Zig 0.15.2 (or a newer patch in the 0.15 series). Zig 0.16 is not source-compatible with the pinned Ghostty version. With Homebrew, install the versioned formula using brew install zig@0.15.
• The Ghostty git submodule initialized at ghostty/.

From the repository root, prepare and build the framework:

git submodule update --init --recursive
brew install zig@0.15
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcodebuild -downloadComponent MetalToolchain
./scripts/build_ghostty.sh

The build script automatically uses Homebrew's keg-only zig@0.15 binary when the default zig command is an incompatible version. It also discovers and selects Xcode's registered Metal toolchain, which Xcode 26 may not select implicitly for command-line builds. The build is complete when ghostty/macos/GhosttyKit.xcframework exists. After generating it for the first time, clean and rebuild the app in Xcode.

Missing XCFramework

If Xcode reports There is no XCFramework found at '.../ghostty/macos/GhosttyKit.xcframework', first check whether ghostty/ is empty. An empty directory means the submodule has not been initialized; run the submodule command above, then run ./scripts/build_ghostty.sh. If the script rejects the active developer directory, select the full Xcode installation with the command above rather than the standalone Command Line Tools. If the build says it cannot execute metal, install the Metal Toolchain component with xcodebuild -downloadComponent MetalToolchain and retry.

Design Rules

• Keep engine-specific behavior behind SessionEngineBackend where possible.
• Do not assume Codex has Claude todo files.
• Use atomic writes for files watched by app services.
• Preserve user-managed skill, agent, instruction, and rule files when mirroring into engine-specific directories.
• Avoid blocking the main actor when reading transcript directories, SQLite, or git state.

Adding A New Engine

1. Add a case to AIEngine with display name, short name, and accent color.
2. Implement SessionEngineBackend.
3. Register the backend in KanbanManager and AutoResumeService.
4. Add launch, resume, and fork command generation.
5. Update analytics parsing if the new engine has transcripts or token data.
6. Update UI engine selectors and documentation.

Changing EPIC Schema

EpicRecord is the on-disk schema. Any schema change must preserve existing JSONL parsing or include a migration path. Because agents may write inbox commands independently, update both the app parser and the managed EPIC skill text if command shape changes.

Changing Approval Hooks

Hook changes involve bundled Python resources, hook installer paths, app-side socket decoding, permission models, and analytics. Keep wire JSON stable unless both hook scripts and HookSocketServer are updated together.

Validation Checklist

• Confirm ghostty/macos/GhosttyKit.xcframework exists.
• Build the app in Xcode.
• Launch a new Claude session and a new Codex session.
• Resume one existing session for each supported engine.
• Verify Kanban reloads after external transcript/task changes.
• Create, assign, auto-resume, and complete an EPIC.
• Trigger an approval request and verify the response reaches the CLI.
• Open Analytics for a project with both Claude and Codex history.
• Inspect git changes and load a diff for a modified file.

Bundled Wiki Maintenance

This wiki is a static bundle under docs/wiki. Pages use local assets/wiki.css and assets/wiki.js, so they can be opened directly from disk or served by any static file server. When the product changes, update the relevant topic page and keep the sidebar links identical across pages.