AstroTerminal

A fast, native macOS terminal for deep work: shell and vim at the center, with a Raycast-style command palette (⌘K) and (later) project capsule features — file explorer, diff, and focus mode.

Status: Phase 0 MVP. Tabs, PTY, themes, and the ⌘K command palette are in place. Splits, project explorer, diff view, and focus mode are planned.

Features

Now	What you get
Tabs	⌘T new, ⌘W close (with running-process guard), ⌘⇧]/⌘⇧[ cycle
PTY	Real shell via SwiftTerm. Vim works — / reaches the shell, not the app
Palette	⌘K opens a fuzzy command palette. /help, /config get/set/list, /tab new/close/list, /theme <name>
Themes	default, catppuccin-mocha, one-dark. Live-applied via /theme. Persisted to ~/.config/astro/config.toml

Roadmap

• 0.1 — Split panes
• 1 — Project folder + file explorer + "open in vim"
• 2 — Git diff pane
• 3 — Pomodoro / focus mode

Requirements

• macOS 14 (Sonoma) or later
• Xcode 16+ (Swift 6)
• Apple Silicon or Intel Mac

Install

Pre-built signed .app will be available on Releases and via Homebrew cask (planned). For now, build from source.

Build from source

git clone https://github.com/LordPenguin11/AstroTerminal.git
cd AstroTerminal
open Apps/AstroTerminal/AstroTerminal.xcodeproj
# ⌘R in Xcode

Or via SPM (builds the modules; the app still launches via Xcode):

swift build
swift test

Architecture

SPM modular monolith, Swift 6 strict concurrency:

Apps/AstroTerminal/        # Composition root (SwiftUI App + commands)
Packages/AstroCore/        # PTY, EventBus, ConfigService, TabManager (no UI)
Packages/AstroKit/         # FeatureRegistry, QuickCommandEngine, protocols (no AppKit/SwiftUI)
Packages/AstroTerminalUI/  # SwiftUI views, SwiftTerm wrapper, theme apply

Layering rules:

• AstroCore imports no UI framework.
• AstroKit imports no UI framework.
• Feature packages communicate only through EventBus and AstroKit protocols.
• The app target talks to AstroTerminalUI's AppEnvironment — never reaches into AstroCore.

CI enforces these via grep guards in .github/workflows/ci.yml.

Configuration

~/.config/astro/config.toml. Set values from inside the app:

⌘K  →  /config set terminal.theme catppuccin-mocha
⌘K  →  /config set terminal.font_size 14

Available keys: terminal.theme, terminal.font_family, terminal.font_size, quick_command.palette_trigger.

Known limitations (Phase 0)

• IME composition not visualized (Vietnamese, Japanese, Chinese, Korean, etc.). The terminal engine (SwiftTerm) stubs the marked-text portion of NSTextInputClient — composing characters aren't drawn while you type, though final committed text reaches the shell correctly. Workaround: switch to a non-composing input method while typing in vim.
• No App Sandbox. Interactive shells need tcsetpgrp(3) which the macOS sandbox blocks. The app is signed with the Hardened Runtime entitlement; Sandbox is intentionally off. Matches iTerm2 / Ghostty / Warp / Alacritty.

Contributing

See CONTRIBUTING.md and the Code of Conduct.

Bug reports and feature ideas → Issues.
Open-ended questions → Discussions.

License

MIT — see LICENSE.