Open Source Terminal GUI
ShellFrame
An AI terminal anyone can pick up.
Born from a designer's need. Now the whole team uses it.
Origin Story
My collaborator is a designer. She watched me fly through tasks with Claude Code and Codex in the terminal and wanted to try it herself. But she immediately hit a wall: you can't paste images in a terminal.
IDEs like Windsurf and Cursor let you paste screenshots directly to ask AI questions, but the raw terminal can't do that. Having to save an image, type out the file path, then reference it — that single extra step killed the motivation.
So I built a ultra-lightweight GUI wrapper — not Electron-heavy, but Python + native OS WebView. Fast startup, tiny memory footprint. Cmd+V to paste images, multi-tab to manage different projects, and a Telegram bridge for remote access from your phone.
After completing it, I introduced ShellFrame to my colleagues. Designers and PMs benefited just as much. They no longer had to face the intimidating black-and-white terminal — ShellFrame lowered the barrier to AI CLI tools down to "if you can use a chat app, you can use this."
Problem & Solution
The Problem
- x Terminals can't paste images
- x Non-engineers fear command lines
- x Can't use AI tools away from desk
- x Electron is bloated, VS Code is overkill
The Solution
- > Cmd+V to paste screenshots instantly
- > Clean GUI with one-click presets
- > Telegram bridge for mobile access
- > Native WebView — lightweight & fast
Key Features
📋
Smart Paste
Cmd+V to paste screenshots or multiple files. Since v0.11.9, file paths are wrapped in bracketed-paste escapes so Claude Code / Codex recognize them as attachments and collapse them into [image #N] — not typed characters.
📑
Multi-Tab + tmux Persistence
Each tab runs inside a tmux session (Unix) or uses soft persistence (Windows). Close the window, reopen — conversations resume where you left off. Window geometry also persists across restarts.
🎛
Master / Worker Orchestration
A master Claude uses sfctl delegate to split tasks, spin up workers, poll results, and wrap up. #tab tags which tab to interact with, tab lifecycle auto-writes handoff notes back to the master, and an idle reaper sediments unused tabs — parallel-agent orchestration native to ShellFrame, no tmux fiddling.
📱
Telegram Bridge
One bot manages all sessions. Text, images, files, voice (STT) flow both ways — plus remote /break to send ESC and interrupt the AI. Commands: /list /new /fetch /usage /break /pause /resume /reload /restart /update /close and /1 /2… to switch tabs. Destructive ones require inline confirm.
🚦
Four-State Status Lights
Each session shows one light: blue = working, green = done, red = needs your decision, amber = warning. Mirrored to the TG banner and native macOS notifications, and clickable to toggle manually. A glance tells you who's busy and who's blocked on you.
📜
Clean Scroll History
Scrollback now reads from the CLI transcript as source of truth, rendered via xterm.js — browse deep history seamlessly, with markdown rendered to ANSI, consecutive tool calls folded into a one-line summary, and harness noise hidden. Scrollback matches the live view, ANSI colors preserved.
🎙
Voice STT + AI Cleanup
Voice messages from TG are transcribed and sent into the session; local voice input can also be polished into clean prose by AI (Typeless-style). Plugin-first architecture: local whisper.cpp, custom HTTP server, or your own Python plugin — never tied to a single cloud provider.
🧠
AI Context + Editable Prompts
Claude / Codex sessions start with environment context auto-injected (active sessions, bridge state, sfctl command reference). Since v0.11.8, the init prompt and per-turn TG preamble are both editable from Settings.
🛡
sfctl permissions
v0.11.8 adds a one-shot subcommand. macOS: opens Privacy panes (Files & Folders, Accessibility, Automation, etc.) + whitelists python/bun in ALF. Windows: adds Defender inbound allow rules for the bundled Python. Run once post-install.
🔄
Two-Tier Reload + Merged /update
UI changes hot-reload; Python changes trigger a restart with session preservation. v0.10.12 folded /update_now into /update with an inline-keyboard "⬇️ Update Now / Cancel" when a new release is detected.
⌨️
Input Ergonomics
Shift+Enter for newlines without send, right-click CMD-style copy/paste, Esc to clear input (plain terminals), Ctrl+Click to open file paths (even hard-wrapped URLs), and S / M / L UI scale.
⚡
Global Hotkey ⌃⌥Space
Since v0.11.27. Press Ctrl+Option+Space from any app to summon ShellFrame; press again to hide. Spaces-aware: the window moves to your current virtual desktop instead of pulling you away. Toggle in Settings. macOS only for now.
🧹
Auto /compact
Since v0.11.26. Bridge monitors Claude Code's token gauge in real time. When remaining context drops below the threshold (default 15%), it auto-sends /compact to summarize context and free tokens. Threshold configurable in Settings. Claude-only — never fires on Codex / bash.
🔔
Completion Notifications
Since v0.11.29. When ShellFrame is in the background, a native macOS notification pops up the moment an AI session finishes its reply. Click the banner to jump straight back. 30s per-session cooldown to avoid spam. Toggle in Settings.
🤖
Automatic Agent Detection
Status lights are now event-driven via Claude Code hooks — the AI no longer has to self-report [[SF:]] markers. The right panel becomes a live agent activity feed: busy / waiting / done at a glance.
📊
AI Usage Gauge
A persistent capsule in the top-right shows the current tab's Claude / Codex usage level in real time — see it before you run out. Query it remotely from TG with /usage.
🔌
Plugin System + LINE Bridge
Bridges and STT providers are fully pluggable, so third parties can add their own channels. Ships with a LINE bridge (company webhook forward + poll, its own per-turn wrapper prompt); the sidebar shows separate TG / LINE routing badges.
🌐
Local HTTP API
An opt-in loopback API lets external programs (e.g. a voice assistant) drive ShellFrame remotely — open sessions, send input, receive event callbacks. Three layers of protection: loopback + token + IP allowlist. Off by default.
⏰
Loops Scheduler
Experimental: re-run a prompt or command on a timer (e.g. check deploy status every 5 minutes). Managed from a panel, off by default.
💻
Cross-Platform + i18n
macOS (WKWebView + tmux persistence), Windows (Edge WebView2 + ConPTY + soft persistence), Linux (GTK WebView). Auto-detects OS language (en / zh-TW), switchable in Settings.
Tech Stack
Frontend
xterm.js terminal
Native OS WebView
Zero Electron dependency
Backend
Python + pywebview
PTY / ConPTY
WebSocket communication
Bridge
Telegram / LINE + voice STT
Plugin provider chain
Local HTTP API + Claude hooks
Deploy
One-line install script
Git-based auto-update
macOS .app bundle
Making AI Tools Belong to Everyone
Claude Code and Codex are powerful AI tools, but they live inside the terminal — for non-engineers, that's an invisible wall.
ShellFrame tears that wall down.
When a designer can paste a screenshot to ask AI about layout.
When a PM can use Telegram to ask AI to organize data remotely.
When a new hire doesn't need to learn the command line to start using AI.
That's what tools should be: serving people, not the other way around.
v0.29.9
Open Source MIT — macOS / Windows / Linux
17 stars · 4 forks
What's in v0.29.9