README.md

idx0 Documentation Hub

Last updated: 2026-03-25

This folder is the contributor handbook for idx0, a native macOS session-first terminal app built with SwiftUI + AppKit + libghostty.

Start Here

• New contributors: read Contribution Guide, then Style Guide, then Testing Guide.
• Feature or refactor work: read Architecture Deep Dive and Runtime Integrations.
• Data/model changes: read Persistence and State.
• Release hardening and incidents: use Operations Playbook.
• Publishing a version: follow Release Runbook.

Repository Snapshot (2026-03-22)

• Swift files in app/tests/package targets: 161
• Approx Swift LOC: 35,907
• Main app target: idx0 (macOS 14+, Swift 6)
• Test target: idx0Tests
• External runtime dependency: ghostty submodule + GhosttyKit.xcframework symlinked into repo root

Documentation Map

Core Contributor Guides

• Contribution Guide
• Style Guide
• Testing Guide
• Operations Playbook
• Release Runbook

Architecture Guides

• Architecture Deep Dive
• Runtime Integrations
• Persistence and State

Existing Reference Docs (kept and still valid)

• Architecture Map and Ownership Notes
• Engineering Guidelines
• IPC Protocol
• Niri Keybinding Compatibility
• Core Coverage Policy

Core Commands

From repo root:

# One-time setup (submodule + GhosttyKit build/link)
./scripts/setup.sh

# Regenerate project from project.yml
xcodegen generate

# Build tests and app
xcodebuild -project idx0.xcodeproj -scheme idx0 -destination 'platform=macOS' test

# Maintainability policy gate
./scripts/maintainability-gate.sh

# Core coverage gate
./scripts/coverage-core.sh

Contributor Safety Notes

• Do not edit ghostty/ casually. Treat it as an upstream dependency unless a change is explicitly intended.
• Keep command-surface parity intact: menu, shortcuts, command palette, and IPC should map to the same action model.
• Update docs in the same PR for architecture, workflow, schema, IPC, or command-surface changes.