FRACTAL Documentation

Home Cheat Sheet

Quick Start

# Clone and run
git clone https://github.com/TizTech/Fractal.git
cd Fractal
swift run FRACTAL

# Landing page development
cd landing-page
npm install
npm run dev

Requires macOS 14+ and Xcode Command Line Tools. The app runs as a native SwiftUI application with no Electron or web wrappers.

Terminal Workspace

The default workspace. A spatial canvas of terminal panes that you split, resize, and navigate without ever touching a mouse.

Pane Management

Recursive splitting — Split any pane vertically, horizontally, or alternating. Panes nest infinitely, forming a tree layout.
Spatial focus navigation — Move focus between panes using Opt+Arrow keys. Focus jumps to the nearest pane in that direction.
Split ratio nudging — Resize splits with Cmd+Opt+Arrow in 3% increments.
Quarter layout — Instantly create a 2x2 grid with Shift+Cmd+4.
Equalize layout — Reset all split ratios to 50/50 with Shift+Cmd+E.
Close pane — Cmd+W closes the focused pane and auto-focuses the nearest neighbor.

Terminal Sessions

Full PTY emulation — Each pane runs a real pseudo-terminal via forkpty. Supports zsh, bash, fish, and any POSIX shell.
Renamable panes — Double-click a pane's label to name it (e.g., "server", "logs", "build").
Directory tracking — FRACTAL tracks each pane's working directory via OSC 7 escape sequences. Works automatically with zsh and bash.
xterm.js rendering — Full 256-color and truecolor support with a custom FRACTAL dark theme. 10,000 lines of scrollback.
Terminal search — Find text in terminal history with the built-in xterm search addon.
Batched rendering — Terminal output is batched on an 8ms timer to maintain 60 FPS even with high-volume output (e.g., build logs).

Visual Design

Focus indicator — Focused pane shows a glowing cyan border with accent shadow. Unfocused panes dim subtly.
Animated split dividers — Hover-reactive dividers with glow effects for easy grabbing.
ASCII launch banner — The FRACTAL logo displays in the first terminal pane on app launch.

IDE Workspace

A full code editor environment with file management, syntax highlighting, LSP completions, and integrated terminal. Open with Shift+Cmd+O.

Code Editor

Monaco Editor — Full VS Code editor engine via Monaco, with syntax highlighting for 20+ languages, find/replace, multi-cursor, minimap, and more.
Tab bar — Open files appear as tabs. Click to switch, X to close. Right-click for "Close Others", "Copy Path", "Reveal in Finder".
Dirty indicators — Unsaved files show a white dot on their tab and in the file list.
Smart editing — Auto-closing brackets and quotes, smart indentation on Enter, indent-aware block creation for {}.
Status bar — Shows file type, cursor line/column, LSP completion count, and current status at the bottom of the editor.
Custom FRACTAL theme — Dark theme with cyan accents matching the rest of the app.

LSP Auto-Completion

Language Server Protocol — Semantic completions powered by real LSP servers for Swift (sourcekit-lsp), TypeScript/JavaScript (typescript-language-server), and Python (pyright).
Keyword completions — Language-aware keyword suggestions for Swift, Python, JavaScript, TypeScript, Go, Rust, Java, HTML, CSS, Markdown, and more.
Token completions — Suggestions from all identifiers in the current file, combined with LSP results for comprehensive autocompletion.
Debounced requests — Completion requests are debounced at 180ms to avoid overloading the LSP server during rapid typing.

File Management

File browser — Left panel shows the current directory's contents sorted by type (folders first) then name.
File filter — Filter bar at the top of the file list for instant substring matching.
Fuzzy file search — Cmd+P opens a project-wide fuzzy finder that recursively indexes up to 5,000 files (skipping node_modules, .git, .build, etc.).
Create / rename / delete — Inline creation of files and folders, rename via dialog, delete with confirmation.
Context menus — Right-click any file for Open, Copy Path, Reveal in Finder, Rename, Delete.
Color-coded icons — Files are color-coded by language/type: blue for compiled languages, green for scripting, yellow for JS/TS, orange for web, purple for text, teal for config.

Workspace Sessions

Multi-session support — Open multiple project folders as sessions. Switch between them to change the working context.
Session persistence — Sessions and the last-selected session are saved to UserDefaults and restored on relaunch.
Git branch display — Each session shows its current git branch.
Editable path bar — Click the path in the top bar to type a path directly and navigate there.

Panels & Layout

Collapsible sidebar — Cmd+B or the HIDE/SHOW button toggles the left panel to reclaim horizontal space.
Collapsible bottom panel — Toggle the stats/terminal/git panel to reclaim vertical space.
Integrated terminal — Bottom panel includes a terminal pane that auto-syncs its working directory to the editor's current folder.
Network stats — Live TCP in/out throughput and ping RTT displayed in the bottom panel.
Git log — Last 3 commits shown in the bottom panel's git section.

Command Palette

Open with Shift+Cmd+P from any workspace. Type to filter commands, press Enter to execute.

Available commands: Switch to Terminal, Switch to IDE, Split Pane, Split Vertical, Split Horizontal, Close Pane, Equalize Layout, Quarter Layout, Toggle Sidebar, Toggle Bottom Panel, Sync Editor, Save File, Open Folder, Search Files.

Architecture

Language: Swift 5.10, SwiftPM, no Xcode project required.

UI: SwiftUI with AppKit bridging for NSTextView, WKWebView (terminal + Monaco editor).

Terminal: Real PTY via forkpty (C bridge), rendered with xterm.js in WKWebView.

Editor: Monaco Editor loaded from CDN in a WKWebView, with native Swift <-> JS messaging.

LSP: Native LSP client over stdio, supporting sourcekit-lsp, typescript-language-server, and pyright.

State: @Observable pattern with AppModel as root, PaneTreeStore for the pane tree, EditorWorkspaceModel for the IDE.

Pane tree: Recursive PaneNode enum (leaf or split) with functional transformations for split, close, resize, and balance operations.