Architect

https://github.com/user-attachments/assets/a4e28a63-557a-44f3-9bae-47b2fd0a5dc6

A terminal built for multi-agent AI coding workflows. Run Claude Code, Codex, or Gemini in parallel and see at a glance which agents need your attention. See more in my article.

Built on ghostty-vt for terminal emulation and SDL3 for rendering.

Why Architect?

Running multiple AI coding agents is the new normal. But existing terminals weren't built for this:

• Agents sit idle waiting for approval while you're focused elsewhere
• Context switching between tmux panes or tabs kills your flow
• No visibility into which agent needs attention right now

Architect solves this with a grid view that keeps all your agents visible, with status-aware highlighting that shows you instantly when an agent is awaiting approval or has completed its task.

[!WARNING]
This project is in the early stages of development. Use at your own risk.

The application is experimental and may have bugs, stability issues, or unexpected behavior.

Features

Agent-Focused

• Status highlights — agents glow when awaiting approval or done, so you never miss a prompt
• Agent session persistence — when you quit Architect, any running Claude, Codex, or Gemini agents are gracefully terminated and their session IDs saved; on next launch the agents resume automatically where they left off
• Dynamic grid — starts with a single terminal in full view; press ⌘N to add a terminal after the current one, and closing terminals compacts the grid forward
• Grid view — keep all agents visible simultaneously, expand any one to full screen
• Worktree picker (⌘T) — quickly cd into git worktrees for parallel agent work on separate branches; new worktrees are created outside the repo tree (configurable via [worktree] in config.toml) with automatic post-create initialization
• Recent folders (⌘O) — quickly cd into recently visited directories with arrow key selection
• Diff review comments — click diff lines in the ⌘D overlay to leave inline comments, then send them all to a running agent (or start one) with the "Send to agent" button
• Story viewer — run architect story <filename> to open a scrollable overlay that renders PR story files with prose text and diff-colored code blocks
• Reader mode (⌘R) — open a centered markdown reader for the selected terminal's history (works in full view and grid) with live updates, bottom pinning, incremental search (⌘F, Enter/Shift+Enter), markdown tables with inline cell styling (bold/italic/code/links/strikethrough), task checkboxes (emoji), clickable links, shared draggable scrollbar, and left-to-right gradient separators before command prompts (OSC 133 + fallback heuristics)

Terminal Essentials

• Smooth animated transitions for grid expansion, contraction, and reflow (cells and borders move/resize together)
• Keyboard navigation: ⌘+Return to expand, ⌘1–⌘0 to switch grid slots, ⌘Arrow to move focus in grid view (plays a brief wave animation on the destination terminal), ⌘N to add, ⌘W to close a terminal (restarts if it's the only terminal), ⌘T for worktrees, ⌘O for recent folders, ⌘D for repo-wide git diff (staged + unstaged + untracked), ⌘R for reader mode, ⌘/ for shortcuts; quit with ⌘Q or the window close button
• Git diff overlay title shows the repo root folder being diffed
• Per-cell cwd bar in grid view with reserved space so terminal content stays visible
• Scrollback with trackpad/wheel support and an auto-hiding draggable scrollbar in terminal views
• OSC 8 hyperlink support (Cmd+Click to open)
• Kitty keyboard protocol for enhanced key handling
• Persistent window state and font size across sessions

Installation

Download Pre-built Binary (macOS)

Download the latest release from the releases page.

For Apple Silicon (M1/M2/M3/M4):

curl -LO https://github.com/forketyfork/architect/releases/latest/download/architect-macos-arm64.tar.gz
tar -xzf architect-macos-arm64.tar.gz
xattr -dr com.apple.quarantine Architect.app
open Architect.app

For Intel Macs:

curl -LO https://github.com/forketyfork/architect/releases/latest/download/architect-macos-x86_64.tar.gz
tar -xzf architect-macos-x86_64.tar.gz
xattr -dr com.apple.quarantine Architect.app
open Architect.app

Note:

• These GitHub release archives are ad-hoc signed so macOS can launch them locally, but they are not Developer ID signed or notarized.
• Clear the quarantine attribute before first launch, or macOS may block the app.
• The archive contains Architect.app. You can launch it with open Architect.app or run ./Architect.app/Contents/MacOS/architect from the terminal. Keep the bundle contents intact.
• Not sure which architecture? Run uname -m - if it shows arm64, use the ARM64 version; if it shows x86_64, use the Intel version.

Homebrew (macOS)

Prerequisites: Xcode Command Line Tools must be installed:

xcode-select --install

Install via Homebrew (builds from source):

# Tap the repository (note: requires full repo URL since the formula is in the main repo)
brew tap forketyfork/architect https://github.com/forketyfork/architect

# Install architect
brew install architect

# Copy the app to your Applications folder
cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/

Or install directly without tapping:

brew install https://raw.githubusercontent.com/forketyfork/architect/main/Formula/architect.rb
cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/

Build from Source

See docs/development.md for the full development setup. Quick start:

nix develop
just build

Hooks

To add hooks for Claude Code, Codex or Gemini, use the architect command available in the terminal:

architect hook claude
architect hook codex
architect hook gemini

Configuration

Architect stores configuration in ~/.config/architect/:

• config.toml: read-only user preferences (edit via ⌘,).
• persistence.toml: runtime state (window position/size, font size, terminal cwds), managed automatically.

Common settings include font family, theme colors, grid font scale, and logging minimum severity ([logging].min_level). On macOS, structured app logs are written to ~/Library/Logs/Architect/ with size-based rotation at 10 MiB, including startup/shutdown markers and grid/full view transition events at INFO. The grid size is dynamic and adapts to the number of terminals. Remove the files to reset to the default values.

Troubleshooting

• App won't open (Gatekeeper): run xattr -dr com.apple.quarantine Architect.app after extracting the release.
• Font not found: ensure the font is installed and set font.family in config.toml. The app falls back to SFNSMono on macOS.
• Missing symbol glyphs: fallbacks try the bundled Symbols Nerd Font, then Arial Unicode MS, then STIXTwoMath (if available) before emoji.
• Emoji alignment: single-codepoint emoji are centered using glyph metrics; if they appear off, try a different primary font or font size.
• Reset configuration: delete ~/.config/architect/config.toml and ~/.config/architect/persistence.toml.
• Crash after closing a terminal: update to the latest build; older builds could crash after terminal close events on macOS.
• Known limitations: emoji fallback is macOS-only; keybindings are currently fixed.

Documentation

• docs/ai-integration.md: set up Claude Code, Codex, and Gemini CLI hooks for status notifications (includes architect notify, architect hook ..., and timestamped backups).
• docs/ARCHITECTURE.md: architecture overview and system boundaries.
• docs/configuration.md: detailed configuration reference for config.toml and persistence.toml.
• docs/development.md: build, test, and release process.
• CLAUDE.md: agent guidelines for code assistants.

Related Tools

Architect is part of a suite of tools I'm building for AI-assisted development:

• Stepcat — Multi-step agent orchestration with Claude Code and Codex
• Marx — Run Claude, Codex, and Gemini in parallel for PR code review
• Claude Nein — macOS menu bar app to monitor Claude Code spending

License

MIT