ForkTTY Guide

ForkTTY is a multi-agent terminal tool designed specifically for Linux, providing solutions to pain points in AI coding workflows:

• Core Problems: Code conflicts during multi-AI agent collaboration, cumbersome context switching, and scattered attention
• Core Mechanisms: Git worktree isolation (to avoid conflicts), smart notifications (to keep track of agent status in time), split-screen management (for efficient layout)
• Value: Provides native support for AI coding collaboration and improves development efficiency

Terminal Dilemmas in the AI Coding Era

With the popularity of AI coding assistants like Claude Code and Codex CLI, developers need to collaborate with multiple agents (code generation, testing, refactoring, etc.), but traditional tools (tmux/screen) have shortcomings:

1. Code Conflicts: Multiple agents working on the same codebase easily lead to file conflicts
2. Context Switching: Need to switch between multiple terminal windows to check agent status
3. Scattered Attention: Cannot timely know if an agent needs intervention

Core Design: One Window, Zero Conflicts

ForkTTY achieves its goals through three key mechanisms:

1. Git Worktree Isolation: Each agent gets an independent Git worktree/branch; after work is done, merge via Git to avoid conflicts
2. Smart Notifications: Detects agent waiting states (e.g., OSC sequences, prompt modes), reminds users via sidebar badges and desktop notifications, with shortcut Ctrl+Shift+U to jump
3. Split-Screen Management: Supports horizontal/vertical splitting (Ctrl+D/Ctrl+Shift+D), drag adjustment, Alt+arrow key navigation—more user-friendly with graphical operations

Technical Architecture: Rust + Tauri + React

• Frontend: React19 + TypeScript + Vite, using xterm.js for terminal rendering and react-resizable-panels for split-screen
• Backend: Rust + Tauri v2, managing PTY via portable-pty, handling worktrees via git2, sending notifications via notify-rust
• Unix Socket API: Exposes JSON-RPC interface ($XDG_RUNTIME_DIR/forktty.sock), supports external tools to create workspaces, with strict security restrictions (0600 permissions, request size limits)

Detailed Feature Explanation

• Workspace Management: Named workspaces, independent layouts, session persistence, shortcut switching (Ctrl+1-9)
• Git Integration: Automatic worktree creation, support for nested/sibling/outer nested layouts, branch management
• Other Features: Terminal search (Ctrl+F), Ghostty theme compatibility, command palette (Ctrl+Shift+P), system tray integration (unread count)

Installation and Usage Guide

System Requirements: Rust1.88+, Node.js20+, Linux Dependencies: Debian/Ubuntu need to install libwebkit2gtk-4.1-dev, etc.; Fedora needs to install webkit2gtk4.1-devel, etc. Building: Clone from source, run npm install, then use tauri:dev (development) or tauri:build (production) Pre-built Packages: GitHub Releases provides .deb (Debian-based) and AppImage (portable) Common Shortcuts: New workspace (Ctrl+N), horizontal split (Ctrl+D), navigate panes (Alt+arrow keys), etc.

Security and Privacy Protection

• Zero Telemetry: No usage data collection, no network connection, data retained locally
• Security Design: Unix socket permission 0600, shell commands use absolute paths, worktree path validation, CSP restrictions for WebView accessing local content

Comparison and Conclusion

Comparison with Similar Tools:

Feature	ForkTTY	tmux	cmux
Platform	Linux only	Cross-platform	macOS only
Git Worktree	Native support	Manual configuration required	Not supported
Smart Notifications	Built-in	None	None

Conclusion: ForkTTY is a new member of the AI coding toolchain, optimized for AI collaboration scenarios. Although it is in the v0.1.0 stage, its core design provides a valuable solution for developers and represents the professionalization trend of AI coding tools.