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 instant search filtering (start typing to narrow the list — the overlay takes the keyboard the instant it starts opening, so nothing you type is lost to the animation), substring highlighting, arrow key navigation, and ⌘1–⌘9 quick selection; its pill is hidden while the focused terminal runs a foreground process
• Pull requests (⌘P) — when the focused terminal is inside a GitHub-cloned repo, the ⌘P pill loads and shows the current branch's PR number (e.g. #123), scaled to fit the pill; expand it to list open PRs (via gh pr list) with search filtering and check out a branch with gh pr checkout; the pill is hidden while the focused terminal runs a foreground process
• Diff review comments — click diff lines in the ⌘D overlay to leave inline comments with multiline wrapping, then send them all to a running agent (or start one) with the "Send to agent" button
• Selection-to-agent context — release after selecting terminal text to reveal a narrow robot button anchored just outside the selection; the button follows the selection while scrolling; choose Claude, Codex, or Gemini in a centered modal with highlighted dropdown navigation, review the fully wrapped context in a scrollable field, enter wrapped multiline instructions, cancel if needed, or launch a new agent in the selected terminal's working directory with the selection submitted as its initial prompt without embedding large contexts in the shell command line
• Story viewer — run architect story <filename> to open a scrollable overlay that renders PR story files with prose text and diff-colored code blocks
• MCP session spawning — run from an MCP client to ask the running Architect app to create a terminal session in a requested working directory

Terminal Essentials

• Smooth animated transitions for grid expansion, contraction, and reflow (cells and borders move/resize together)
• Context-aware shortcut pills stay right-aligned with fixed spacing, compact when a pill is unavailable, and animate into their new positions; newly available pills enter after the existing row reflows to avoid overlapping hit targets and remain non-interactive until they reach a clear slot; the worktree, recent-folder, and pull-request pills are hidden while the focused terminal runs a foreground process and any open picker closes immediately
• Wakeable idle input handling keeps typing responsive after short idle periods instead of waiting on a fixed sleep window
• 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
• Every text field (recent-folder and reader/story search, worktree name, diff comments, selection-agent instructions) behaves like a macOS text field: a blinking caret, Backspace deletes one character, ⌥Backspace the previous word, ⌘Backspace the whole field, ⌘A selects everything (the next keystroke or paste replaces it), and ⌘C/⌘V copy and paste. The selection-agent field accepts multiline instructions with ⇧↩; plain ↩ launches, while Escape or Cancel dismisses it. Pasting multi-line text into a one-line field drops the newlines, and text longer than the field fades out at its edge instead of spilling past it. Emoji are scaled to the surrounding line height wherever they appear (search fields, comments, reader mode, stories, selection-agent instructions)
• 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, ⌘P for pull requests (GitHub repos), ⌘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 reserves space; clipped parent paths marquee only while the Architect window has input focus, and terminal dimensions track grid/full mode so content wraps inside the visible area
• Scrollback with trackpad/wheel support and an auto-hiding draggable scrollbar in terminal views
• OSC 8 hyperlinks and plain-text URLs open with Cmd+Click (Cmd+hover underlines them), including inside TUIs that capture the mouse such as Claude Code's fullscreen mode and Codex; Architect keeps that click instead of reporting it to the app, because mouse reports cannot carry the Cmd key

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. The MCP helper is bundled at ./Architect.app/Contents/MacOS/architect-mcp. 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

The formula automatically selects the compatible macOS SDK when Zig 0.16.0 encounters the arm64e-only SDK shipped with newer macOS toolchains.

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/

# MCP clients can use the helper on PATH
architect-mcp

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

Source builds install both executables under zig-out/bin/: architect and architect-mcp.

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

On first launch, Architect shows a faint in-terminal hint with the core shortcuts and the architect hook setup command. The hint is shown once and is not sent to the shell.

MCP

architect-mcp is a stdio MCP server for local clients. It exposes one tool, spawn_session, which forwards the request to the running Architect app. It does not launch Architect by itself.

spawn_session arguments:

{
  "cwd": "/absolute/path/to/worktree",
  "command": "codex",
  "display_name": "Issue 291"
}

cwd is required. command and display_name are optional. On success, the tool returns structured content with status, session_id, and slot_index. If Architect is not running, the grid is full, cwd is invalid, or spawning fails, the tool returns an MCP tool error with a stable code and message.

For release downloads, use:

./Architect.app/Contents/MacOS/architect-mcp

For Homebrew installs, architect-mcp is also symlinked onto PATH; the app-bundle fallback is:

$(brew --prefix)/Cellar/architect/$(brew list --versions architect | awk '{print $2}')/Architect.app/Contents/MacOS/architect-mcp

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. If a saved window position is no longer usable after a display change, Architect starts with the platform's default placement instead.

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.
• Pull request list says to install gh: Architect checks the inherited PATH and the standard Homebrew locations /opt/homebrew/bin/gh and /usr/local/bin/gh. If gh is installed elsewhere, make its executable path available to the app or use a standard Homebrew installation.
• 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, plus the architect-mcp spawn_session interface.
• 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