{"id":34914355,"url":"https://github.com/forketyfork/architect","last_synced_at":"2026-04-28T16:01:07.795Z","repository":{"id":323024154,"uuid":"1091845749","full_name":"forketyfork/architect","owner":"forketyfork","description":"A flexible terminal grid for multi-agent AI workflows","archived":false,"fork":false,"pushed_at":"2026-04-09T09:54:02.000Z","size":14386,"stargazers_count":27,"open_issues_count":9,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-09T11:27:11.431Z","etag":null,"topics":["agentic-coding","ai-coding","claude-code","codex","gemini","ghostty","sdl3","terminal","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","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/forketyfork.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-07T15:53:26.000Z","updated_at":"2026-04-09T07:13:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forketyfork/architect","commit_stats":null,"previous_names":["forketyfork/architect"],"tags_count":79,"template":false,"template_full_name":null,"purl":"pkg:github/forketyfork/architect","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forketyfork%2Farchitect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forketyfork%2Farchitect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forketyfork%2Farchitect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forketyfork%2Farchitect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forketyfork","download_url":"https://codeload.github.com/forketyfork/architect/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forketyfork%2Farchitect/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32387923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T14:34:11.604Z","status":"ssl_error","status_checked_at":"2026-04-28T14:32:37.009Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-coding","ai-coding","claude-code","codex","gemini","ghostty","sdl3","terminal","zig"],"created_at":"2025-12-26T12:01:12.061Z","updated_at":"2026-04-28T16:01:07.789Z","avatar_url":"https://github.com/forketyfork.png","language":"Zig","readme":"# Architect\n\n[![Build status](https://github.com/forketyfork/architect/actions/workflows/build.yml/badge.svg)](https://github.com/forketyfork/architect/actions/workflows/build.yml)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Zig](https://img.shields.io/badge/language-Zig-orange.svg)](https://ziglang.org/)\n\nhttps://github.com/user-attachments/assets/a4e28a63-557a-44f3-9bae-47b2fd0a5dc6\n\nA 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](https://forketyfork.github.io/blog/2026/01/21/running-4-ai-coding-agents-at-once-the-terminal-i-built-to-keep-up/).\n\nBuilt on [ghostty-vt](https://github.com/ghostty-org/ghostty) for terminal emulation and SDL3 for rendering.\n\n## Why Architect?\n\nRunning multiple AI coding agents is the new normal. But existing terminals weren't built for this:\n\n- **Agents sit idle** waiting for approval while you're focused elsewhere\n- **Context switching** between tmux panes or tabs kills your flow\n- **No visibility** into which agent needs attention right now\n\nArchitect 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.\n\n\u003e [!WARNING]\n\u003e **This project is in the early stages of development. Use at your own risk.**\n\u003e\n\u003e The application is experimental and may have bugs, stability issues, or unexpected behavior.\n\n## Features\n\n### Agent-Focused\n- **Status highlights** — agents glow when awaiting approval or done, so you never miss a prompt\n- **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\n- **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\n- **Grid view** — keep all agents visible simultaneously, expand any one to full screen\n- **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\n- **Recent folders** (⌘O) — quickly `cd` into recently visited directories with instant search filtering (start typing to narrow the list), substring highlighting, arrow key navigation, and ⌘1–⌘9 quick selection\n- **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\n- **Story viewer** — run `architect story \u003cfilename\u003e` to open a scrollable overlay that renders PR story files with prose text and diff-colored code blocks\n- **MCP session spawning** — run `architect-mcp` from an MCP client to ask the running Architect app to create a terminal session in a requested working directory\n- **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)\n\n### Terminal Essentials\n- Smooth animated transitions for grid expansion, contraction, and reflow (cells and borders move/resize together)\n- Wakeable idle input handling keeps typing responsive after short idle periods instead of waiting on a fixed sleep window\n- 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\n- Git diff overlay title shows the repo root folder being diffed\n- Per-cell cwd bar in grid view with reserved space so terminal content stays visible\n- Scrollback with trackpad/wheel support and an auto-hiding draggable scrollbar in terminal views\n- OSC 8 hyperlink support (Cmd+Click to open)\n- Replies to OSC 4/10/11 color queries using the live terminal palette/default colors so Codex and similar CLIs do not stall on startup probes\n- Kitty keyboard protocol for enhanced key handling\n- Persistent window state and font size across sessions\n\n## Installation\n\n### Download Pre-built Binary (macOS)\n\nDownload the latest release from the [releases page](https://github.com/forketyfork/architect/releases).\n\n**For Apple Silicon (M1/M2/M3/M4):**\n```bash\ncurl -LO https://github.com/forketyfork/architect/releases/latest/download/architect-macos-arm64.tar.gz\ntar -xzf architect-macos-arm64.tar.gz\nxattr -dr com.apple.quarantine Architect.app\nopen Architect.app\n```\n\n**For Intel Macs:**\n```bash\ncurl -LO https://github.com/forketyfork/architect/releases/latest/download/architect-macos-x86_64.tar.gz\ntar -xzf architect-macos-x86_64.tar.gz\nxattr -dr com.apple.quarantine Architect.app\nopen Architect.app\n```\n\n**Note**:\n\n* These GitHub release archives are ad-hoc signed so macOS can launch them locally, but they are not Developer ID signed or notarized.\n* Clear the quarantine attribute before first launch, or macOS may block the app.\n* 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.\n* Not sure which architecture? Run `uname -m` - if it shows `arm64`, use the ARM64 version; if it shows `x86_64`, use the Intel version.\n\n### Homebrew (macOS)\n\n**Prerequisites**: Xcode Command Line Tools must be installed:\n```bash\nxcode-select --install\n```\n\nInstall via Homebrew (builds from source):\n```bash\n# Tap the repository (note: requires full repo URL since the formula is in the main repo)\nbrew tap forketyfork/architect https://github.com/forketyfork/architect\n\n# Install architect\nbrew install architect\n\n# Copy the app to your Applications folder\ncp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/\n\n# MCP clients can use the helper on PATH\narchitect-mcp\n```\n\nOr install directly without tapping:\n```bash\nbrew install https://raw.githubusercontent.com/forketyfork/architect/main/Formula/architect.rb\ncp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/\n```\n\n### Build from Source\n\nSee [`docs/development.md`](docs/development.md) for the full development setup. Quick start:\n```bash\nnix develop\njust build\n```\n\nSource builds install both executables under `zig-out/bin/`: `architect` and `architect-mcp`.\n\n## Hooks\n\nTo add hooks for Claude Code, Codex or Gemini, use the `architect` command available in the terminal:\n```bash\narchitect hook claude\narchitect hook codex\narchitect hook gemini\n```\n\n## MCP\n\n`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.\n\n`spawn_session` arguments:\n```json\n{\n  \"cwd\": \"/absolute/path/to/worktree\",\n  \"command\": \"codex\",\n  \"display_name\": \"Issue 291\"\n}\n```\n\n`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`.\n\nFor release downloads, use:\n```bash\n./Architect.app/Contents/MacOS/architect-mcp\n```\n\nFor Homebrew installs, `architect-mcp` is also symlinked onto `PATH`; the app-bundle fallback is:\n```bash\n$(brew --prefix)/Cellar/architect/$(brew list --versions architect | awk '{print $2}')/Architect.app/Contents/MacOS/architect-mcp\n```\n\n## Configuration\n\nArchitect stores configuration in `~/.config/architect/`:\n\n* `config.toml`: read-only user preferences (edit via `⌘,`).\n* `persistence.toml`: runtime state (window position/size, font size, terminal cwds), managed automatically.\n\nCommon 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.\n\n## Troubleshooting\n\n* **App won't open (Gatekeeper)**: run `xattr -dr com.apple.quarantine Architect.app` after extracting the release.\n* **Font not found**: ensure the font is installed and set `font.family` in `config.toml`. The app falls back to `SFNSMono` on macOS.\n* **Missing symbol glyphs**: fallbacks try the bundled Symbols Nerd Font, then `Arial Unicode MS`, then `STIXTwoMath` (if available) before emoji.\n* **Emoji alignment**: single-codepoint emoji are centered using glyph metrics; if they appear off, try a different primary font or font size.\n* **Reset configuration**: delete `~/.config/architect/config.toml` and `~/.config/architect/persistence.toml`.\n* **Crash after closing a terminal**: update to the latest build; older builds could crash after terminal close events on macOS.\n* **Known limitations**: emoji fallback is macOS-only; keybindings are currently fixed.\n\n## Documentation\n\n* [`docs/ai-integration.md`](docs/ai-integration.md): set up Claude Code, Codex, and Gemini CLI hooks for status notifications, plus the `architect-mcp` `spawn_session` interface.\n* [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): architecture overview and system boundaries.\n* [`docs/configuration.md`](docs/configuration.md): detailed configuration reference for `config.toml` and `persistence.toml`.\n* [`docs/development.md`](docs/development.md): build, test, and release process.\n* [`CLAUDE.md`](CLAUDE.md): agent guidelines for code assistants.\n\n## Related Tools\n\nArchitect is part of a suite of tools I'm building for AI-assisted development:\n\n- [**Stepcat**](https://github.com/forketyfork/stepcat) — Multi-step agent orchestration with Claude Code and Codex\n- [**Marx**](https://github.com/forketyfork/marx) — Run Claude, Codex, and Gemini in parallel for PR code review\n- [**Claude Nein**](https://github.com/forketyfork/claude-nein) — macOS menu bar app to monitor Claude Code spending\n\n## License\n\nMIT\n","funding_links":[],"categories":["Fundamentals"],"sub_categories":["Utility"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforketyfork%2Farchitect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforketyfork%2Farchitect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforketyfork%2Farchitect/lists"}