BranchTerm

BranchTerm is a native macOS work-intelligence desk: Bloomberg-terminal density and keyboard speed, expressed in language a beginner corporate worker can understand.

It combines four ideas:

• Guided knowledge work: menus for company research, spreadsheet analysis, briefs, decks, meeting preparation, contract review, and deliverable QA.
• Codex as the agent runtime: the app uses the official codex app-server protocol for authentication, persistent threads, streamed output, sandboxing, and token telemetry.
• Safe parallel workspaces: Git worktrees appear as friendly, isolated work areas, so two deliverables can proceed at once without switching one folder back and forth.
• Persistent terminal panes: each pane is a real pseudo-terminal backed by tmux when installed. Closing the app detaches; the underlying processes remain available to reattach.

The terminal is an advanced view, not the front door. A visible action finder (⌘K), normal macOS menus, outcome cards, plain-language forms, files, and an Agent Desk are the primary interface.

What is implemented

Area	Current behavior
Home	Searchable outcome cards and guided forms for seven corporate workflows
Action finder	Bloomberg-style keyboard palette with beginner-readable actions
Agent Desk	Visible thread history and switching, restored transcripts, starter prompts, streaming responses, token and cache telemetry
Prompt Library	Version-visible, SHA-256-addressed context blocks and stable cache-prefix assembly
Workspaces	Visual root-and-branch map, file-change counts, one-click switching, and friendly Git worktree creation
Terminal	Native AppKit surface, PTY, tmux persistence, splits, UTF-8, common ANSI/VT sequences, true color
Files	Searchable workspace deliverables table with type, size, date, and Finder reveal
Documents	Save, Save As…, Open…, edited-state dot, and JSON-based .branchterm files

Run it

Requirements:

• macOS 14 or newer
• Swift 6 toolchain
• Git
• Codex CLI installed and authenticated
• tmux recommended for persistent terminal processes

Choose File → New Project… (⌘N) to create a new project folder. BranchTerm initializes Git automatically; no command-line setup is required. Open Existing Project Folder… connects a folder that is already a Git repository.

Run a development build:

env \
  CLANG_MODULE_CACHE_PATH=.build/module-cache \
  SWIFTPM_MODULECACHE_OVERRIDE=.build/module-cache \
  swift run --disable-sandbox BranchTerm

Build a normal app bundle:

./scripts/build-app.sh

The result is dist/BranchTerm.app. It is ad-hoc signed for local use.

Run the test suite:

env \
  CLANG_MODULE_CACHE_PATH=.build/module-cache \
  SWIFTPM_MODULECACHE_OVERRIDE=.build/module-cache \
  swift test --disable-sandbox

Prompt caching and Codex

BranchTerm does not implement a second cache in front of Codex. Automatic Prompt Library context is currently off by default. When explicitly enabled, it makes the upstream cache more likely to hit:

1. Pinned Prompt Library blocks are sorted in document order and rendered deterministically as developer instructions.
2. Each block carries a SHA-256 content identity so changes are visible.
3. Changing user requests are sent separately as turn input, after the reusable prefix.
4. A saved Codex thread ID is resumed with its worktree.
5. Agent Desk displays cached-read, cache-write, input, and output telemetry supplied by app-server.

OpenAI prompt caching depends on identical prompt prefixes, so changing an early pinned block intentionally starts a different reusable prefix. Use New Thread in Agent Desk after editing pinned context. See the official Prompt caching guide and Codex app-server guide.

Why tmux, worktrees, and Ghostty's architecture matter

• tmux separates a running job from one window. A long analysis can survive a UI restart, and multiple panes can be reattached.
• Git worktrees provide simultaneous checked-out branches while sharing one repository object database. They are ideal for isolating concurrent agent tasks and reviewing their file changes independently.
• Ghostty demonstrates the right native-app boundary: a terminal core behind a C ABI, with a Swift/AppKit/SwiftUI macOS shell and GPU rendering. BranchTerm follows the replaceable-core boundary, but its current terminal grid is an MVP—not libghostty and not yet Ghostty-class compatibility or performance.

Official references: Git worktree, Ghostty architecture, and Ghostty repository.

Corporate knowledge and expert-work packages

A .branchterm document currently saves project pointers, worktree layouts, Codex thread IDs, and reusable prompt context. Project inputs and generated outputs remain ordinary files in the selected worktree, so they can be reviewed and versioned with familiar tools.

The proposed portable training/evaluation format—covering expert demonstrations, provenance, consent, artifacts, and DuckDB indexing—is in docs/EXPERT_PACKAGE.md. DuckDB is best used to query extracted document text, metadata, JSON, CSV, and Parquet; it is not itself a full PDF parser or OCR system.

Honest MVP boundaries

• The custom VT model handles common shell, editor, and tmux behavior but is not a full terminal conformance implementation. libghostty is the intended renderer/core upgrade.
• Workspaces currently require an existing Git repository.
• There is no enterprise connector, SSO/RBAC, approval inbox, content redaction, evaluation runner, or expert-package exporter yet.
• Save As… saves the desk document and references project files; it does not duplicate the entire worktree.
• Codex runs with workspaceWrite and a non-interactive approval policy. A production corporate build should add an approval UI and organization policy controls before enabling broader actions.