diff --git a/README.md b/README.md index 627a22f..e7fc4ba 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,19 @@ ![Architect Hero](docs/assets/architect-hero.png) -A terminal emulator that displays a configurable grid of interactive terminal sessions with smooth expand/collapse animations. Built on ghostty-vt for terminal emulation and SDL3 for rendering. +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. + +Built on [ghostty-vt](https://github.com/ghostty-org/ghostty) 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.** @@ -15,6 +27,21 @@ A terminal emulator that displays a configurable grid of interactive terminal se ![Architect Demo](docs/assets/architect-demo.gif) +## Features + +### Agent-Focused +- **Status highlights** — agents glow when awaiting approval or done, so you never miss a prompt +- **Grid view** — keep 4+ agents visible simultaneously, expand any one to full screen +- **Worktree picker** (⌘T) — quickly `cd` into git worktrees for parallel agent work on separate branches + +### Terminal Essentials +- Smooth expand/collapse animations between grid and focused views +- Keyboard navigation: ⌘+Return to expand, ⌘1–⌘0 to switch, ⌘W to close, ⌘/ for shortcuts +- Scrollback with trackpad/wheel support and grid indicator when scrolled +- 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) @@ -38,8 +65,9 @@ open Architect.app ``` **Note**: -- 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. + +* 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) @@ -49,7 +77,6 @@ xcode-select --install ``` Install via Homebrew (builds from source): - ```bash # 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 @@ -62,7 +89,6 @@ cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/ ``` Or install directly without tapping: - ```bash brew install https://raw.githubusercontent.com/forketyfork/architect/main/Formula/architect.rb cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/ @@ -71,46 +97,41 @@ cp -r $(brew --prefix)/Cellar/architect/*/Architect.app /Applications/ ### Build from Source See `docs/development.md` for the full development setup. Quick start: - ```bash nix develop just build ``` -## Features - -- Configurable grid of terminal sessions with smooth expand/collapse animations -- Full-window terminal rendering scaled down for grid view -- Keyboard navigation (⌘+Return to expand, ⌘1–⌘0 to switch, ⌘W to close, ⌘/ for shortcuts, ⌘T for worktrees) -- Scrollback with hover wheel/trackpad support and a grid indicator when scrolled -- Worktree picker for quick `cd` into git worktrees -- Persistent window and font size state; terminal cwd restore on macOS -- Cmd+Click opening for OSC 8 hyperlinks -- AI assistant status highlights (awaiting approval / done) -- Kitty keyboard protocol support for enhanced key handling - ## Configuration Architect stores configuration in `~/.config/architect/`: -- `config.toml`: read-only user preferences (edit via `⌘,`). -- `persistence.toml`: runtime state (window position/size, font size), managed automatically. +* `config.toml`: read-only user preferences (edit via `⌘,`). +* `persistence.toml`: runtime state (window position/size, font size), managed automatically. Common settings include font family, theme colors, and grid rows/cols. 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. -- **Reset configuration**: delete `~/.config/architect/config.toml` and `~/.config/architect/persistence.toml`. -- **Known limitations**: emoji fallback is macOS-only; keybindings are currently fixed. +* **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. +* **Reset configuration**: delete `~/.config/architect/config.toml` and `~/.config/architect/persistence.toml`. +* **Known limitations**: emoji fallback is macOS-only; keybindings are currently fixed. ## Documentation -- `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, release, and assistant hook setup. -- `CLAUDE.md`: agent guidelines for code assistants. +* `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, release, and assistant hook setup. +* `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**](https://github.com/forketyfork/stepcat) — Multi-step agent orchestration with Claude Code and Codex +- [**Marx**](https://github.com/forketyfork/marx) — Run Claude, Codex, and Gemini in parallel for PR code review +- [**Claude Nein**](https://github.com/forketyfork/claude-nein) — macOS menu bar app to monitor Claude Code spending ## License