Not a CLI wrapper. Not an Electron shell. A native .app you drag to Applications.
Built with SwiftUI + real PTY. 23 AI providers. Errors get analyzed. Commands get explained.
Features · Providers · Install · CLI · Config · Architecture · Contributing
╔══════════════════════════════════════════════════════════════════════╗
║ ║
║ ┌─────────────────────────────────────────────────────────────┐ ║
║ │ AI Terminal.app ● ● ● │ ║
║ ├─────────────────────────────────────────────────────────────┤ ║
║ │ │ ║
║ │ $ npm run build │ ║
║ │ │ ║
║ │ ERROR in src/index.ts(42,5) │ ║
║ │ TS2345: Argument of type 'string' is not assignable │ ║
║ │ to parameter of type 'number'. │ ║
║ │ │ ║
║ │ ── AI detected error. Analyzing with Groq (0.3s) ── │ ║
║ │ │ ║
║ │ ✦ Type mismatch on line 42. │ ║
║ │ │ ║
║ │ sed -i '' 's/userId/Number(userId)/' src/index.ts │ ║
║ │ ✓ Safe │ ║
║ │ │ ║
║ │ [▶ Run] [📋 Copy] [💡 Explain] │ ║
║ └─────────────────────────────────────────────────────────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════════╝
| Feature | Description |
|---|---|
📦 Native .app Bundle |
Real macOS application — shows in Dock, Launchpad, Spotlight. Just drag to /Applications. |
| 🖥️ Real PTY Terminal | Full zsh --login with ANSI 256-color, tab completion, history. Native forkpty() — not a web view. |
| 🤖 23 AI Providers | Ollama, OpenAI, Anthropic, Gemini, Groq, DeepSeek, Mistral, and 16 more. Auto mode picks the best available. |
| 🔍 Auto Error Detection | Detects errors in terminal output and offers one-click AI analysis with fix commands. |
| ⚡ Token Streaming | AI responses stream in real-time, token-by-token. Groq and Cerebras deliver under 1 second. |
| 💡 Command Suggestions | AI extracts runnable commands from responses with safety ratings (✓ Safe / ⚠ Caution / ✕ Blocked). |
| 🛡️ Safety Layer | Blocks rm -rf /, fork bombs, dd on disks. Warns on sudo, git push --force, DROP TABLE. |
| � Full API Key Management | Configure API keys for all 23 providers. Auto-detects keys from environment variables. Dashboard links for every provider. |
| �🔐 Secret Leak Detection | Warns if API keys, GitHub tokens, or Slack tokens appear in commands or output. |
| 📑 Multi-Session | Multiple terminal tabs, each with its own PTY process and AI conversation context. |
| 🧠 Memory Store | Remembers past errors and solutions. Feeds them back to AI for smarter, project-aware answers. |
| 📂 Context Engine | Auto-detects project type (Node, Python, Rust, Go, Swift, etc.), git branch, and dependencies. |
| 🎛️ Execution Modes | Safe (recommend only), Assisted (suggest + run buttons), Autopilot (auto-execute suggestions). |
| 🌙 Dark Theme | GitHub Dark-inspired color palette with full ANSI 256-color and RGB support. |
| Feature | Description |
|---|---|
| 📊 Pipe Analysis | cmd 2>&1 | ait --analyze — pipe any command's output for instant AI analysis. |
| 💬 Interactive REPL | ait -i — full interactive mode with /slash commands, !shell execution, conversation history. |
| 🏃 Run + Analyze | ait --run "npm test" — runs a command and auto-analyzes errors with AI. |
| 📖 Command Explain | ait --explain "find . -name '*.log' -delete" — get detailed breakdowns of any command. |
| Category | Providers | Notes |
|---|---|---|
| 🏠 Local | Ollama, LM Studio | Free, offline, private. No API key needed. |
| 🆓 Free | Pollinations | No API key. Works out of the box. |
| ☁️ Cloud | OpenAI, Anthropic, Google Gemini, Mistral, Cohere, xAI, DeepSeek, AI21 | Premium models. Requires API keys. |
| ⚡ Fast Inference | Groq, Cerebras, SambaNova, Fireworks, Together, Lepton | Sub-second responses. Free tiers available. |
| 🔀 Aggregators | OpenRouter, DeepInfra, Perplexity, HuggingFace, Replicate | One key → hundreds of models. |
Auto mode resolves the best available provider: local → fast free-tier → cloud → aggregator → Pollinations fallback.
npm install -g ai-terminal-app
ait --helpInstalls the ait CLI globally. Builds from source on npm install (requires Swift 5.9+). Works immediately after install.
git clone https://github.com/3289david/ai-terminal.git
cd ai-terminal
make dmgThis builds AI Terminal-3.0.0.dmg in .build/. Open it, drag AI Terminal.app to Applications — done.
Auto CLI install: When you launch the
.appfor the first time, it automatically installsaitto/usr/local/bin/. No extra steps needed — the CLI is ready to use in any terminal.
make install
# Builds .app and copies to /Applications/AI Terminal.app
# First launch auto-installs `ait` CLI to /usr/local/binmake app # Build .app to .build/
open ".build/AI Terminal.app" # Launch it (auto-installs ait CLI)
cp -R ".build/AI Terminal.app" /Applications/ # Or install manually# Via npm (recommended)
npm install -g ai-terminal-app
# Or via Makefile
make install-cli
# installs `ait` to /usr/local/bin
# Or build and copy manually:
swift build -c release --product ait
cp .build/release/ait /usr/local/bin/
# Or just launch the .app — it auto-installs ait for you!brew tap 3289david/tap
brew install ai-terminal| Target | Description |
|---|---|
make dmg |
Build AI Terminal-3.0.0.dmg drag-to-install package |
make app |
Build AI Terminal.app in .build/ (bundles ait CLI inside) |
make install |
Build .app and copy to /Applications |
make run |
Build .app and launch it |
make cli |
Build CLI binary (ait) |
make install-cli |
Build CLI and install to /usr/local/bin |
make clean |
Remove build artifacts |
A fully-featured headless CLI for use inside any existing terminal.
npm install -g ai-terminal-app
USAGE
ait [OPTIONS] [QUERY...]
command 2>&1 | ait --analyze
ait -i
# Ask anything
ait "how do I find large files on macOS?"
# Analyze an error (pipe stderr)
npm run build 2>&1 | ait --analyze
# Explain a command
ait --explain "find . -name '*.log' -mtime +30 -delete"
# Run a command with AI error analysis
ait --run "cargo build"
# Safety check
ait --safety "rm -rf node_modules"
# ⚠ Caution: Recursive force deletion
ait --safety "rm -rf /"
# ✕ BLOCKED: Recursive deletion from root
# Use a specific provider
ait --provider groq "optimize this SQL query"
# Interactive REPL
ait -i| Flag | Description |
|---|---|
-i, --interactive |
Interactive REPL with slash commands and shell execution |
-a, --analyze |
Analyze piped input as an error |
-e, --explain CMD |
Explain a command in detail |
-r, --run CMD |
Run a command with AI error analysis |
-s, --safety CMD |
Check if a command is safe before running |
-p, --provider NAME |
Use a specific provider (default: auto) |
--list-providers |
List all 23 providers and their status |
--config |
Interactive configuration wizard |
--memory |
Show stored error/solution memories |
--version |
Show version |
-h, --help |
Show help |
| Command | Description |
|---|---|
any text |
Ask the AI a question |
!command |
Run a shell command with AI error analysis |
/explain cmd |
Explain a command |
/run cmd |
Run with safety check + AI analysis |
/safety cmd |
Check command safety |
/providers |
List all AI providers |
/context |
Show detected project context |
/memory |
Show stored error memories |
/history |
Show command history |
/config |
Configure API keys |
/clear |
Clear screen |
exit |
Quit |
| Shortcut | Action |
|---|---|
⌘ T |
New session |
⌘ W |
Close session |
⌘ , |
Settings |
↑ / ↓ |
Navigate command history |
Tab |
Shell tab completion |
Esc |
Clear input |
^C |
Send interrupt (SIGINT) |
^D |
Send EOF |
Open Settings (⌘ ,) to configure providers. Every provider has:
- API Key field (SecureField with paste support)
- "Get API Key" link to the provider's dashboard
- Model and Endpoint override fields
- Test Connection button to verify your key works
- Env var badge when a key is detected from the environment
Local providers and Pollinations work out of the box — no keys needed.
API keys are automatically detected from environment variables. Set them in your shell profile (~/.zshrc):
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="AI..."
export GROQ_API_KEY="gsk_..."
export MISTRAL_API_KEY="..."
export COHERE_API_KEY="..."
export XAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."
export AI21_API_KEY="..."
export CEREBRAS_API_KEY="..."
export SAMBANOVA_API_KEY="..."
export FIREWORKS_API_KEY="..."
export TOGETHER_API_KEY="..."
export LEPTON_API_KEY="..."
export OPENROUTER_API_KEY="..."
export DEEPINFRA_API_KEY="..."
export PERPLEXITY_API_KEY="..."
export HF_TOKEN="hf_..."
export REPLICATE_API_TOKEN="r8_..."Priority: stored key (from Settings/config) → environment variable → empty.
# Interactive config wizard (shows env vars + dashboard links)
ait --config
# Config files
~/.config/ai-terminal/config.json # API keys, models, endpoints
~/.config/ai-terminal/memory.json # Error/solution memory
~/.config/ai-terminal/history.txt # Command historyThe CLI and GUI app share configuration via UserDefaults, so configuring one works for both.
Every command is evaluated before execution:
| Level | Examples | Behavior |
|---|---|---|
| ✕ Blocked | rm -rf /, :(){ :|:& };:, mkfs, dd if=... of=/dev/ |
Prevented from running |
| ⚠ Caution | sudo, git push --force, DROP TABLE, curl | sh, chmod 777 |
Warning shown, confirmation required |
| ✓ Safe | Everything else | Runs normally |
Secret leak detection scans commands, output, and AI responses for:
- API keys (
sk-...,api_key=...) - GitHub tokens (
ghp_...) - Slack tokens (
xoxb-...)
.
├── Package.swift # SPM manifest
├── package.json # npm package (npm i -g ai-terminal-app)
├── Makefile # Build targets (make app, make install)
├── bin/
│ └── ait # Node.js wrapper for npm bin
├── scripts/
│ └── postinstall.js # Builds native binary on npm install
├── Scripts/
│ ├── build-app.sh # Assembles AI Terminal.app bundle (+ bundles ait CLI)
│ └── generate-icon.swift # Generates app icon via CoreGraphics
├── Resources/
│ └── AITerminal.entitlements # App sandbox entitlements
├── Sources/
│ ├── CPty/ # C wrapper around forkpty()
│ │ ├── include/pty_wrapper.h
│ │ └── pty_wrapper.c
│ ├── AITerminal/ # SwiftUI macOS GUI app
│ │ ├── AITerminalApp.swift # @main entry point
│ │ ├── Resources/Info.plist # Bundle metadata
│ │ ├── Models/
│ │ │ ├── AIProvider.swift # 23 provider definitions
│ │ │ ├── AppState.swift # @Observable app state
│ │ │ └── Message.swift # Message, CommandSuggestion types
│ │ ├── Services/
│ │ │ ├── AIRouter.swift # Routes to correct AI client
│ │ │ ├── SafetyLayer.swift # Command safety evaluation
│ │ │ ├── MemoryStore.swift # Error/solution persistence
│ │ │ ├── ContextEngine.swift # Project type detection
│ │ │ ├── PTYService.swift # Pseudo-terminal management
│ │ │ ├── ANSIParser.swift # Full ANSI escape parser
│ │ │ ├── OllamaClient.swift # Ollama API client
│ │ │ ├── OpenAICompatibleClient.swift # 15+ providers
│ │ │ ├── AnthropicClient.swift # Claude API client
│ │ │ ├── GoogleGeminiClient.swift # Gemini API client
│ │ │ └── PollinationsClient.swift # Free fallback
│ │ ├── Views/
│ │ │ ├── ContentView.swift # Main split view
│ │ │ ├── TerminalView.swift # PTY terminal view
│ │ │ ├── AIResponsePanel.swift # Streaming AI panel
│ │ │ ├── AppTextField.swift # Custom NSTextField
│ │ │ ├── CommandCard.swift # Runnable command cards
│ │ │ ├── SidebarView.swift # Session sidebar
│ │ │ ├── SettingsView.swift # Provider configuration
│ │ │ └── ProviderSelector.swift # Provider picker
│ │ └── Theme/ # Colors, fonts
│ └── AITerminalCLI/ # Headless CLI (brew/choco)
│ └── CLI.swift # Full CLI with all features
└── docs/
└── index.html # GitHub Pages website
Running make app produces a proper macOS application bundle:
AI Terminal.app/
└── Contents/
├── Info.plist # Bundle metadata + LSApplicationCategoryType
├── PkgInfo # APPL????
├── MacOS/
│ ├── AITerminal # Compiled Mach-O executable (GUI)
│ └── ait # CLI binary (auto-installed to /usr/local/bin on first launch)
└── Resources/
└── AppIcon.icns # Generated app icon (10 sizes)
The app shows in Dock, Launchpad, and Spotlight. No terminal needed to launch it.
On first launch, the ait CLI is automatically installed to /usr/local/bin/ so you can use it in any terminal immediately.
- PTY Layer:
forkpty()spawns a realzsh --loginprocess. Raw I/O is piped throughPTYService. - ANSI Parser: Full SGR parser handles 256-color, RGB, bold/italic/underline, cursor movement.
- Error Detection: 26 regex patterns scan terminal output for errors (exit codes, tracebacks, compiler errors).
- AI Router: Routes queries through the correct client based on provider type (5 client kinds for 23 providers).
- Safety Layer: Evaluates commands against dangerous/caution patterns before execution.
- Memory Store: Persists error→solution pairs as JSON, recalls past fixes by keyword similarity scoring.
- Context Engine: Detects project type from manifest files, reads git state, and injects context into AI prompts.
It takes ~5 lines of code:
- Add a case to
AIProviderTypeinSources/AITerminal/Models/AIProvider.swift - Set
defaultEndpoint,defaultModel,icon,subtitle,category,clientKind - Done. The router, settings UI, and CLI all pick it up automatically.
If the new provider uses OpenAI-compatible API, set clientKind = .openaiCompatible and you're finished. For custom API formats, create a new client in Services/.
Contributions are welcome! Here's how to get started:
# Fork and clone
git clone https://github.com/3289david/ai-terminal.git
cd ai-terminal
# Build and run the .app
make run
# Or build and run the CLI
swift run ait -i- Keep PRs focused — one feature or fix per PR
- Follow existing code style (no SwiftLint enforced, just match the patterns)
- Test with at least one provider (Pollinations works without API keys)
- Update README if adding user-facing features
- 🐛 Bug fixes and stability improvements
- 🤖 New AI provider integrations
- 🎨 Terminal rendering improvements
- 📱 Linux / cross-platform support
- 🧪 Test coverage
- 📚 Documentation and examples
MIT License — see LICENSE for details.
---
Built with Swift, SwiftUI, and a love for the terminal.