Ghostty Agent Forge by ContextLattice

A Ghostty-native command deck for making local AI agents visible, memory-connected, and operationally reliable.

Ghostty Agent Forge gives local AI agents terminal visibility, stable shell tools, and ContextLattice memory hooks on macOS.

What It Does

Ghostty Agent Forge bootstraps a macOS terminal workstation for agentic development:

• Ghostty-first terminal setup with zsh and Homebrew.
• Fast zsh startup with native completions, fzf-tab, zoxide, autosuggestions, and syntax highlighting.
• Agent-safe shell behavior across Codex, Claude Code, Gemini CLI, OpenCode, Hermes/Ultra, OMP, Droid, Pi, Mercury, background workers, launchd jobs, and non-TTY shells.
• ContextLattice-aware defaults for memory search, preflight checks, and local agent identity.
• macOS TCC/FDA diagnostic rules so file-access failures are not mistaken for broken zsh or Unix permissions.
• Reproducible setup scripts for cloning the same terminal environment on another Mac.

Why This Exists

Local AI agents live and die by terminal quality.

If the shell is slow, noisy, over-permissioned, under-permissioned, or full of interactive prompts, agents waste cycles and fail in ways that look like reasoning failures. This repo treats the terminal as part of the agent runtime: observable, reproducible, and safe for both humans and background agent processes.

ContextLattice provides the memory and coordination plane. Ghostty Agent Forge provides the macOS terminal forge around it.

ContextLattice: https://github.com/sheawinkler/ContextLattice

Quick Start

Run a dry run first:

./scripts/bootstrap-ghostty-agent-forge.zsh --dry-run

Then apply:

./scripts/bootstrap-ghostty-agent-forge.zsh
exec zsh -l

If Homebrew is not installed:

./scripts/bootstrap-ghostty-agent-forge.zsh --install-homebrew

If you want to skip the ContextLattice prompt:

./scripts/bootstrap-ghostty-agent-forge.zsh --no-contextlattice-prompt

To explicitly clone the free public ContextLattice repo:

./scripts/bootstrap-ghostty-agent-forge.zsh --install-contextlattice

After install, the gaf CLI is available from ~/.local/bin/gaf:

gaf doctor
gaf resources status
gaf resources tools --missing-only
gaf macos status
gaf macos restore --yes
gaf tcc status
gaf tcc open full-disk-access
gaf memory preflight
gaf behavior status
gaf behavior install --prime --yes
gaf behavior doctor
gaf harnesses status
gaf codex list
gaf self status
gaf claude permissions status
gaf claude permissions install --dry-run
gaf bench 5
gaf rules

Installation Profiles

Ghostty Agent Forge assumes two storage profiles:

• internal-ssd: keep Ghostty, Homebrew, zsh modules, completions, launchers, app bundles, and small fast state local.
• external-ssd: keep large data, logs, archives, backups, sealed telemetry partitions, and bulk model/data stores external.

For agent-heavy machines, do not put core terminal/runtime tools on the same external path that is handling high-write ingest. A Thunderbolt or PCIe external SSD can have excellent bandwidth while still suffering from APFS metadata churn, fseventsd pressure, SQLite WAL/checkpoint contention, and page-cache thrash when live writes and heavy queries hit the same volume.

High-write pipelines should use a two-lane layout:

hot lane   = append-only ingest, minimal readers
query lane = sealed partitions, indexes, summaries

More detail: docs/install-storage-profiles.md.

Installed Tool Stack

The bootstrap installs:

brew install spaceship fzf fzf-tab zsh-autosuggestions zsh-syntax-highlighting zoxide direnv fd ripgrep docker jq gh

It can optionally install:

brew install --cask ghostty

For heavy local workloads, it can also install the resource-ops stack:

./scripts/bootstrap-ghostty-agent-forge.zsh --resource-tools
gaf resources ensure --yes

Resource tools are intentionally low-bloat and terminal-native: btop, procs, smartmontools, dust, dua-cli, dysk, ncdu, gdu, rclone, restic, watchman, hyperfine, and yq.

Shell Architecture

The script writes modular zsh files under ~/.config/ghostty-agent-forge/zsh/ and sources them from managed blocks in ~/.zprofile and ~/.zshrc.

Load order:

1. .zprofile: readable-cwd recovery, Homebrew shellenv, OrbStack path, umask 022.
2. .zshrc: system path floor and existing user config.
3. completion.zsh: zsh completion policy before Oh My Zsh calls compinit.
4. Oh My Zsh with only plugins=(git).
5. post-omz.zsh: fzf-tab and fzf terminal widgets, TTY-only.
6. contextlattice.zsh: optional ContextLattice env defaults and helper commands.
7. tools.zsh: zoxide, direnv, lazy nvm.
8. prompt-spaceship.zsh: Homebrew-managed Spaceship prompt.
9. late-widgets.zsh: autosuggestions and syntax highlighting, TTY-only.

ContextLattice Hooks

The bootstrap can prompt to install ContextLattice from the public repo:

https://github.com/sheawinkler/ContextLattice

The contextlattice.zsh module adds:

• CONTEXTLATTICE_ORCHESTRATOR_URL=http://127.0.0.1:8075
• MEMMCP_ORCHESTRATOR_URL compatibility alias
• stable local agent identity defaults
• cl-health
• cl-search
• cl-preflight
• memwrite

These helpers are intentionally lightweight. They should not start services, reset permissions, or mutate memory unless explicitly invoked.

Agent Behavior Packs

Ghostty Agent Forge can install private behavior packs that render compact, managed rule blocks into multiple harnesses while keeping proprietary policy out of this public repository.

The Sheawinkler private pack is expected at:

sheawinkler/contextlattice-agent-prime

Install requires the authenticated GitHub login to be sheawinkler:

gaf behavior install --prime --yes
gaf behavior status
gaf behavior doctor
gaf harnesses doctor

For local pack development:

gaf behavior install --prime --source ~/Documents/Projects/contextlattice-agent-prime --yes

More detail: docs/agent-behavior-packs.md.

Harness Coverage

The forge is provider-neutral. gaf harnesses status reports the installed binary and current Prime policy projection for every supported harness; JSON is available for agents and CI:

gaf harnesses status
gaf harnesses status --json
gaf harnesses doctor

Codex account profiles are a narrower convenience lane, not the behavior architecture. They keep multiple Codex logins in isolated state homes while using the same installed binary:

gaf codex add pro ~/.codex-pro-2 --yes
gaf codex status --all
gaf codex login pro
gaf codex pro

These helpers never log out another account and never install another Codex binary. More detail: docs/agent-harnesses.md.

Updating The Forge

After the first bootstrap, update the public forge with:

gaf self status
gaf self update --dry-run
gaf self update --yes

The updater clones the requested ref into a temporary directory, refuses downgrades, requires a newer VERSION, runs that checkout's bootstrap, and verifies the installed version.

Installations older than 0.2.0 do not have gaf self; update those once from a fresh clone with ./scripts/bootstrap-ghostty-agent-forge.zsh. Later upgrades use the self-update command.

Claude Code Permissions

GAF can install a Claude Code Bash approval hook for agent-heavy local work:

gaf claude permissions install --dry-run
gaf claude permissions install --yes
gaf claude permissions doctor

The hook auto-allows non-sudo Bash/zsh/git/python/python3 commands and leaves executable sudo behind Claude Code's normal approval prompt. It preserves unrelated settings and replaces only exact Bash hook groups in PreToolUse and PermissionRequest.

More detail: docs/claude-permissions.md.

Agent Control Plane

Ghostty Agent Forge ships a small local CLI:

gaf doctor                 # shell/tool/TCC/ContextLattice/resource checks
gaf ensure --yes           # install missing required Homebrew formulae
gaf resources status       # current disk, swap, process-state, and warning snapshot
gaf resources snapshot --append
gaf resources hotspots ~/Documents /Volumes/wd_black
gaf resources install-agent --load
gaf bench 5                # zsh startup benchmark
gaf macos status           # post-update macOS performance drift audit
gaf macos restore --yes    # reapply safe user-level post-update settings
gaf behavior status        # inspect installed private behavior pack
gaf behavior list          # list immutable installed pack versions
gaf behavior doctor        # verify private pack render and harness blocks
gaf behavior rollback 0.2.3 --yes
gaf harnesses status --json
gaf codex status --all
gaf self update --dry-run
gaf claude permissions status
gaf claude permissions install --yes
gaf claude permissions doctor
gaf blackbox -- <command>  # run command with local JSONL telemetry
gaf profile export         # export machine capability profile
gaf rules                  # print the agent runtime contract

Runtime contract:

config/agent-runtime.json

The contract defines shell modes, expected tools, ContextLattice defaults, safety rules, and observability locations. Agents can read it without scanning the whole repo.

Verification

After installation, run:

zsh -n ~/.zshrc
for f in ~/.config/ghostty-agent-forge/zsh/*.zsh; do zsh -n "$f"; done
zsh -ic 'print START_OK; print $SPACESHIP_VERSION'
zsh -ic 'whence -w _brew _docker _cargo _uv _pnpm _rg _fd _gh _zoxide'
zsh -ic 'autoload -Uz compaudit; compaudit'
for i in {1..5}; do /usr/bin/time -p zsh -ic exit; done
tests/smoke.zsh
python3 tests/public_private_boundary.py

Warm startup target: under 500ms.

Resource Ops

gaf resources is the local-heavy-load control plane. It keeps routine monitoring small enough to run from launchd without becoming the workload:

• gaf resources status prints a concise health view.
• gaf resources snapshot --append writes one compact JSONL record.
• gaf resources hotspots runs explicit, on-demand disk triage.
• gaf resources install-agent --load installs a user LaunchAgent with LowPriorityIO, Nice=10, and a default five-minute interval.

Default snapshot log:

/Volumes/wd_black/ghostty-agent-forge/resource-monitor/resource-snapshots-YYYYMMDD.jsonl

If /Volumes/wd_black is not mounted, snapshots fall back to:

~/.local/state/ghostty-agent-forge/resources/

More detail: docs/resource-ops.md.

Post-macOS Update Restore

macOS updates can re-enable background services, Spotlight indexing, or power defaults that are bad for local agent-heavy workloads. Use the macOS restore lane after an OS update or if the machine suddenly starts burning CPU on system daemons again:

gaf macos status
gaf macos restore --yes
gaf macos install-agent --yes --load
gaf macos status

gaf macos restore --yes applies only user-level, low-risk changes:

• disables selected low-value user LaunchAgents such as Weather, Siri, Photos analysis, and media analysis;
• prints the sudo-required pmset and Spotlight commands instead of running them implicitly;
• reports the active codex CLI path/version so Homebrew path shadowing is visible during post-update checks.

To pin the safe user-level restore across logins and future OS updates:

gaf macos install-agent --yes --load

This installs ~/Library/LaunchAgents/com.contextlattice.ghostty-agent-forge.macos-restore.plist with RunAtLoad, StartInterval=86400, LowPriorityIO, and Nice=10. It runs only:

macos-performance-restore.zsh restore --yes

It does not run sudo, does not edit TCC databases, does not change Spotlight or pmset, and does not touch Codex auth state.

If you want the script to apply sudo-required settings too:

gaf macos restore --yes --system

System-level restore currently targets:

sudo pmset -a powermode 2
sudo pmset -c sleep 0 displaysleep 60 disksleep 10
sudo pmset -b sleep 30 displaysleep 3 disksleep 10
sudo mdutil -i off /System/Volumes/Data
sudo mdutil -i off /

Rules For Agents

• Non-TTY shells must not load terminal widgets that require ZLE.
• Do not install broad bash completion packages for zsh.
• Prefer native zsh completions from Homebrew site-functions.
• Put generated CLI completions under ~/.config/ghostty-agent-forge/zsh/completions/, not Homebrew-managed directories.
• Keep runtime managers lazy.
• Disable automatic Oh My Zsh startup prompts.
• Do not reset macOS privacy permissions unless the human explicitly approves it.
• Diagnose TCC/FDA failures before changing Unix file permissions.
• Use gaf tcc targets and gaf tcc open <pane> to identify and approve the responsible app or binary.
• Keep agent accounts in isolated provider state homes; do not switch by logging out another active profile.
• Identify exact PIDs and dependents before stopping an agent process; do not broadly kill a harness family.

Repository Layout

ghostty-agent-forge/
  VERSION
  README.md
  scripts/
    bootstrap-ghostty-agent-forge.zsh
    claude-permissions.zsh
    codex-accounts.zsh
    self-update.zsh
    behavior-pack.py
    agent-harnesses.py
    contextlattice-preflight.zsh
    macos-tcc-doctor.zsh
  bin/
    gaf
  config/
    agent-runtime.json
  zsh/
    completion.zsh
    post-omz.zsh
    contextlattice.zsh
    tools.zsh
    prompt-spaceship.zsh
    late-widgets.zsh
  docs/
    agent-shell-rules.md
    agent-behavior-packs.md
    agent-harnesses.md
    agent-runtime-contract.md
    claude-permissions.md
    contextlattice-integration.md
    flight-recorder.md
    install-storage-profiles.md
    macos-tcc-fda.md
    resource-ops.md
    repo-governance.md
  tests/
    smoke.zsh

License

MIT