{"id":51413192,"url":"https://github.com/sheawinkler/ghostty-agent-forge","last_synced_at":"2026-07-04T16:30:42.553Z","repository":{"id":364440520,"uuid":"1245392393","full_name":"sheawinkler/ghostty-agent-forge","owner":"sheawinkler","description":"Terminal visibility, zsh/Homebrew bootstrap, and ContextLattice hooks for local AI agents on macOS.","archived":false,"fork":false,"pushed_at":"2026-06-13T02:03:14.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T03:26:18.994Z","etag":null,"topics":["agentic-ai","ai-agents","bootstrap","contextlattice","dev-setup","dotfiles","ghostty","homebrew","macos","shell","terminal","workstation","zsh"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sheawinkler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T07:18:59.000Z","updated_at":"2026-06-13T02:03:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sheawinkler/ghostty-agent-forge","commit_stats":null,"previous_names":["sheawinkler/ghostty-agent-forge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sheawinkler/ghostty-agent-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheawinkler%2Fghostty-agent-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheawinkler%2Fghostty-agent-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheawinkler%2Fghostty-agent-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheawinkler%2Fghostty-agent-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sheawinkler","download_url":"https://codeload.github.com/sheawinkler/ghostty-agent-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sheawinkler%2Fghostty-agent-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35129187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","bootstrap","contextlattice","dev-setup","dotfiles","ghostty","homebrew","macos","shell","terminal","workstation","zsh"],"created_at":"2026-07-04T16:30:41.423Z","updated_at":"2026-07-04T16:30:42.537Z","avatar_url":"https://github.com/sheawinkler.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ghostty Agent Forge by ContextLattice\n\nA Ghostty-native command deck for making local AI agents visible, memory-connected, and operationally reliable.\n\nGhostty Agent Forge gives local AI agents terminal visibility, stable shell tools, and ContextLattice memory hooks on macOS.\n\n## What It Does\n\nGhostty Agent Forge bootstraps a macOS terminal workstation for agentic development:\n\n- Ghostty-first terminal setup with zsh and Homebrew.\n- Fast zsh startup with native completions, fzf-tab, zoxide, autosuggestions, and syntax highlighting.\n- Agent-safe shell behavior for Codex, Claude Code, background workers, launchd jobs, and non-TTY shells.\n- ContextLattice-aware defaults for memory search, preflight checks, and local agent identity.\n- macOS TCC/FDA diagnostic rules so file-access failures are not mistaken for broken zsh or Unix permissions.\n- Reproducible setup scripts for cloning the same terminal environment on another Mac.\n\n## Why This Exists\n\nLocal AI agents live and die by terminal quality.\n\nIf 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.\n\nContextLattice provides the memory and coordination plane. Ghostty Agent Forge provides the macOS terminal forge around it.\n\nContextLattice: https://github.com/sheawinkler/ContextLattice\n\n## Quick Start\n\nRun a dry run first:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh --dry-run\n```\n\nThen apply:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh\nexec zsh -l\n```\n\nIf Homebrew is not installed:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh --install-homebrew\n```\n\nIf you want to skip the ContextLattice prompt:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh --no-contextlattice-prompt\n```\n\nTo explicitly clone the free public ContextLattice repo:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh --install-contextlattice\n```\n\nAfter install, the `gaf` CLI is available from `~/.local/bin/gaf`:\n\n```zsh\ngaf doctor\ngaf resources status\ngaf resources tools --missing-only\ngaf macos status\ngaf macos restore --yes\ngaf tcc status\ngaf tcc open full-disk-access\ngaf memory preflight\ngaf behavior status\ngaf behavior install --prime --yes\ngaf behavior doctor\ngaf claude permissions status\ngaf claude permissions install --dry-run\ngaf bench 5\ngaf rules\n```\n\n## Installation Profiles\n\nGhostty Agent Forge assumes two storage profiles:\n\n- `internal-ssd`: keep Ghostty, Homebrew, zsh modules, completions, launchers, app bundles, and small fast state local.\n- `external-ssd`: keep large data, logs, archives, backups, sealed telemetry partitions, and bulk model/data stores external.\n\nFor 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.\n\nHigh-write pipelines should use a two-lane layout:\n\n```text\nhot lane   = append-only ingest, minimal readers\nquery lane = sealed partitions, indexes, summaries\n```\n\nMore detail: `docs/install-storage-profiles.md`.\n\n## Installed Tool Stack\n\nThe bootstrap installs:\n\n```zsh\nbrew install spaceship fzf fzf-tab zsh-autosuggestions zsh-syntax-highlighting zoxide direnv fd ripgrep docker jq gh\n```\n\nIt can optionally install:\n\n```zsh\nbrew install --cask ghostty\n```\n\nFor heavy local workloads, it can also install the resource-ops stack:\n\n```zsh\n./scripts/bootstrap-ghostty-agent-forge.zsh --resource-tools\ngaf resources ensure --yes\n```\n\nResource tools are intentionally low-bloat and terminal-native: `btop`, `procs`,\n`smartmontools`, `dust`, `dua-cli`, `dysk`, `ncdu`, `gdu`, `rclone`, `restic`,\n`watchman`, `hyperfine`, and `yq`.\n\n## Shell Architecture\n\nThe script writes modular zsh files under `~/.config/ghostty-agent-forge/zsh/` and sources them from managed blocks in `~/.zprofile` and `~/.zshrc`.\n\nLoad order:\n\n1. `.zprofile`: readable-cwd recovery, Homebrew shellenv, OrbStack path, `umask 022`.\n2. `.zshrc`: system path floor and existing user config.\n3. `completion.zsh`: zsh completion policy before Oh My Zsh calls `compinit`.\n4. Oh My Zsh with only `plugins=(git)`.\n5. `post-omz.zsh`: fzf-tab and fzf terminal widgets, TTY-only.\n6. `contextlattice.zsh`: optional ContextLattice env defaults and helper commands.\n7. `tools.zsh`: zoxide, direnv, lazy nvm.\n8. `prompt-spaceship.zsh`: Homebrew-managed Spaceship prompt.\n9. `late-widgets.zsh`: autosuggestions and syntax highlighting, TTY-only.\n\n## ContextLattice Hooks\n\nThe bootstrap can prompt to install ContextLattice from the public repo:\n\n```text\nhttps://github.com/sheawinkler/ContextLattice\n```\n\nThe `contextlattice.zsh` module adds:\n\n- `CONTEXTLATTICE_ORCHESTRATOR_URL=http://127.0.0.1:8075`\n- `MEMMCP_ORCHESTRATOR_URL` compatibility alias\n- stable local agent identity defaults\n- `cl-health`\n- `cl-search`\n- `cl-preflight`\n- `memwrite`\n\nThese helpers are intentionally lightweight. They should not start services, reset permissions, or mutate memory unless explicitly invoked.\n\n## Agent Behavior Packs\n\nGhostty Agent Forge can install private behavior packs that render compact,\nmanaged rule blocks into multiple harnesses while keeping proprietary policy out\nof this public repository.\n\nThe Sheawinkler private pack is expected at:\n\n```text\nsheawinkler/contextlattice-agent-prime\n```\n\nInstall requires the authenticated GitHub login to be `sheawinkler`:\n\n```zsh\ngaf behavior install --prime --yes\ngaf behavior status\ngaf behavior doctor\n```\n\nFor local pack development:\n\n```zsh\ngaf behavior install --prime --source ~/Documents/Projects/contextlattice-agent-prime --yes\n```\n\nMore detail: `docs/agent-behavior-packs.md`.\n\n## Claude Code Permissions\n\nGAF can install a Claude Code Bash approval hook for agent-heavy local work:\n\n```zsh\ngaf claude permissions install --dry-run\ngaf claude permissions install --yes\ngaf claude permissions doctor\n```\n\nThe hook auto-allows non-sudo Bash/zsh/git/python/python3 commands and leaves\nexecutable `sudo` behind Claude Code's normal approval prompt. It preserves\nunrelated settings and replaces only exact `Bash` hook groups in `PreToolUse`\nand `PermissionRequest`.\n\nMore detail: `docs/claude-permissions.md`.\n\n## Agent Control Plane\n\nGhostty Agent Forge ships a small local CLI:\n\n```zsh\ngaf doctor                 # shell/tool/TCC/ContextLattice/resource checks\ngaf ensure --yes           # install missing required Homebrew formulae\ngaf resources status       # current disk, swap, process-state, and warning snapshot\ngaf resources snapshot --append\ngaf resources hotspots ~/Documents /Volumes/wd_black\ngaf resources install-agent --load\ngaf bench 5                # zsh startup benchmark\ngaf macos status           # post-update macOS performance drift audit\ngaf macos restore --yes    # reapply safe user-level post-update settings\ngaf behavior status        # inspect installed private behavior pack\ngaf behavior doctor        # verify private pack render and harness blocks\ngaf claude permissions status\ngaf claude permissions install --yes\ngaf claude permissions doctor\ngaf blackbox -- \u003ccommand\u003e  # run command with local JSONL telemetry\ngaf profile export         # export machine capability profile\ngaf rules                  # print the agent runtime contract\n```\n\nRuntime contract:\n\n```text\nconfig/agent-runtime.json\n```\n\nThe contract defines shell modes, expected tools, ContextLattice defaults, safety rules, and observability locations. Agents can read it without scanning the whole repo.\n\n## Verification\n\nAfter installation, run:\n\n```zsh\nzsh -n ~/.zshrc\nfor f in ~/.config/ghostty-agent-forge/zsh/*.zsh; do zsh -n \"$f\"; done\nzsh -ic 'print START_OK; print $SPACESHIP_VERSION'\nzsh -ic 'whence -w _brew _docker _cargo _uv _pnpm _rg _fd _gh _zoxide'\nzsh -ic 'autoload -Uz compaudit; compaudit'\nfor i in {1..5}; do /usr/bin/time -p zsh -ic exit; done\ntests/smoke.zsh\n```\n\nWarm startup target: under `500ms`.\n\n## Resource Ops\n\n`gaf resources` is the local-heavy-load control plane. It keeps routine monitoring\nsmall enough to run from launchd without becoming the workload:\n\n- `gaf resources status` prints a concise health view.\n- `gaf resources snapshot --append` writes one compact JSONL record.\n- `gaf resources hotspots` runs explicit, on-demand disk triage.\n- `gaf resources install-agent --load` installs a user LaunchAgent with\n  `LowPriorityIO`, `Nice=10`, and a default five-minute interval.\n\nDefault snapshot log:\n\n```text\n/Volumes/wd_black/ghostty-agent-forge/resource-monitor/resource-snapshots-YYYYMMDD.jsonl\n```\n\nIf `/Volumes/wd_black` is not mounted, snapshots fall back to:\n\n```text\n~/.local/state/ghostty-agent-forge/resources/\n```\n\nMore detail: `docs/resource-ops.md`.\n\n## Post-macOS Update Restore\n\nmacOS updates can re-enable background services, Spotlight indexing, or power\ndefaults that are bad for local agent-heavy workloads. Use the macOS restore\nlane after an OS update or if the machine suddenly starts burning CPU on system\ndaemons again:\n\n```zsh\ngaf macos status\ngaf macos restore --yes\ngaf macos install-agent --yes --load\ngaf macos status\n```\n\n`gaf macos restore --yes` applies only user-level, low-risk changes:\n\n- disables selected low-value user LaunchAgents such as Weather, Siri, Photos\n  analysis, and media analysis;\n- prints the sudo-required `pmset` and Spotlight commands instead of running\n  them implicitly;\n- reports the active `codex` CLI path/version so Homebrew path shadowing is\n  visible during post-update checks.\n\nTo pin the safe user-level restore across logins and future OS updates:\n\n```zsh\ngaf macos install-agent --yes --load\n```\n\nThis installs `~/Library/LaunchAgents/com.contextlattice.ghostty-agent-forge.macos-restore.plist`\nwith `RunAtLoad`, `StartInterval=86400`, `LowPriorityIO`, and `Nice=10`. It runs\nonly:\n\n```zsh\nmacos-performance-restore.zsh restore --yes\n```\n\nIt does not run sudo, does not edit TCC databases, does not change Spotlight or\n`pmset`, and does not touch Codex auth state.\n\nIf you want the script to apply sudo-required settings too:\n\n```zsh\ngaf macos restore --yes --system\n```\n\nSystem-level restore currently targets:\n\n```zsh\nsudo pmset -a powermode 2\nsudo pmset -c sleep 0 displaysleep 60 disksleep 10\nsudo pmset -b sleep 30 displaysleep 3 disksleep 10\nsudo mdutil -i off /System/Volumes/Data\nsudo mdutil -i off /\n```\n\n## Rules For Agents\n\n- Non-TTY shells must not load terminal widgets that require ZLE.\n- Do not install broad bash completion packages for zsh.\n- Prefer native zsh completions from Homebrew site-functions.\n- Put generated CLI completions under `~/.config/ghostty-agent-forge/zsh/completions/`, not Homebrew-managed directories.\n- Keep runtime managers lazy.\n- Disable automatic Oh My Zsh startup prompts.\n- Do not reset macOS privacy permissions unless the human explicitly approves it.\n- Diagnose TCC/FDA failures before changing Unix file permissions.\n- Use `gaf tcc targets` and `gaf tcc open \u003cpane\u003e` to identify and approve the responsible app or binary.\n\n## Repository Layout\n\n```text\nghostty-agent-forge/\n  README.md\n  scripts/\n    bootstrap-ghostty-agent-forge.zsh\n    claude-permissions.zsh\n    contextlattice-preflight.zsh\n    macos-tcc-doctor.zsh\n  bin/\n    gaf\n  config/\n    agent-runtime.json\n  zsh/\n    completion.zsh\n    post-omz.zsh\n    contextlattice.zsh\n    tools.zsh\n    prompt-spaceship.zsh\n    late-widgets.zsh\n  docs/\n    agent-shell-rules.md\n    agent-behavior-packs.md\n    agent-runtime-contract.md\n    claude-permissions.md\n    contextlattice-integration.md\n    flight-recorder.md\n    install-storage-profiles.md\n    macos-tcc-fda.md\n    resource-ops.md\n    repo-governance.md\n  tests/\n    smoke.zsh\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheawinkler%2Fghostty-agent-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsheawinkler%2Fghostty-agent-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsheawinkler%2Fghostty-agent-forge/lists"}