Installation & Setup

Atlas Terminal is distributed as both an automated Windows installer and a standalone portable archive.

Method 1: Windows Installer (.exe)

The standard installer integrates Atlas into your Windows Start Menu, configures desktop shortcuts, registers the atlas CLI companion tool, and enables background auto-updates.

# Download the latest installer from GitHub Releases:
https://github.com/akrram0/atlas-terminal/releases/latest

Method 2: Portable Zero-Install Archive

Extract atlas-terminal-windows-x64.zip into any folder (e.g. C:\Tools\Atlas) and run atlas-terminal.exe directly. Your configuration is stored in ~/.config/atlas/settings.json (or right next to the executable if portable.txt is present).

Atlas Satellites: Subterminal Companion Tools

Atlas includes a built-in suite of zero-overhead developer companions executed directly via atlas <command>. These tools run synchronously in your console or powershell without launching the full GUI terminal:

Keyboard Shortcuts Reference

Every pane, tab, search action, and setting is reachable via home-row hotkeys:

Developer Superpowers

Atlas Terminal is built specifically for software engineers with integrated workflows that eliminate context switching:

1. Find in Terminal (Ctrl+F)

A floating, non-intrusive macOS-style search bar that hovers cleanly over the active pane. Features live buffer highlighting across both the active screen and scrollback history, instant match navigation (Enter / Shift+Enter), a real-time match counter badge (3 of 18), and kinetic auto-scrolling to matching lines.

2. Click-to-Code: Smart File Jumps (Ctrl+Click)

Hover any compiler error, panic stack trace, or source path (e.g. src/main.rs:42:15, server.ts:108) with Ctrl held to reveal an accent highlight. Clicking it automatically resolves relative paths against the active pane's working directory and launches your preferred editor directly at the exact line and column coordinates:

• Auto-Detect: Automatically probes for VS Code (code --goto), Cursor, or Zed on your %PATH%.
• Configurable: Select your preferred editor (VS Code, Cursor, Zed, or System Default) in the Settings drawer under Developer & Editor.

3. Native Background Task Notifications

Never wait idly on a terminal prompt again. When a long-running build or command (such as cargo build, npm install, or docker build) finishes while Atlas Terminal is unfocused or minimized, Atlas sends a native Windows Action Center notification alert with the job duration.

The duration threshold can be configured to 5s, 10s, 30s, or 60s in Settings under Background Notifications.

Dynamic Island Topbar HUD

When running in borderless mode or executing background tasks, Atlas Terminal renders an organic Dynamic Island capsule at the top center of the screen.

The island animates with fluid spring physics to present:

• Theme Switching Feedback: Displays the active color preset when cycling with Alt+T.
• Update Available Pulses: Discreetly informs you when an in-place delta update is ready to install.
• Shell Script Triggers (OSC 1338): Any script, CI runner, or shell function can trigger the Dynamic Island with custom titles and messages:

# Trigger Dynamic Island notification from bash or powershell:
atlas hud notify "Build Success" "All 83 tests passed in 2.7s"

Tabs & Split Panes

Atlas supports nested horizontal and vertical split layouts. Each pane maintains its own independent PTY process, working directory, and mouse capture state.

When working in a split layout, press Alt+Z to temporarily maximize your active pane to fill the entire window without losing your multi-pane layout. Pressing it again restores your split geometry. Press Alt+Enter to split vertically, Alt+D to split horizontally, and Alt+Space to toggle orientation.

Fastfetch Inline Images Setup

Atlas Terminal features native support for the iTerm2 OSC 1337 image protocol without requiring Sixel or WebViews. Fastfetch can render your high-resolution distro or custom avatar graphic directly beside system specs.

Add this to your ~/.config/fastfetch/config.jsonc:

{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": {
    "type": "iterm",
    "source": "/path/to/your/avatar.png",
    "width": 18,
    "height": 9,
    "padding": {
      "top": 1,
      "left": 2,
      "right": 3
    }
  },
  "modules": [
    "title",
    "separator",
    "os",
    "host",
    "kernel",
    "uptime",
    "terminal",
    "display",
    "cpu",
    "gpu",
    "memory"
  ]
}

Modern Mouse Reporting & Hyperlinks

Atlas Terminal features full SGR mouse tracking (?1000h / ?1006h) support. Interactive TUI applications such as Lazygit, OpenCode, Neovim, and Midnight Commander respond seamlessly to mouse clicks, dragging, and wheel scrolling.

• Selection Bypass: Hold Shift while dragging to bypass application mouse capture and select terminal text normally.
• Interactive Hyperlinks: Press Ctrl + Click on any highlighted URL to open it immediately in your default browser.
• Keyboard URL Picker: Press Ctrl + Shift + O to extract all visible URLs into the Command Palette and open them without touching the mouse.

WSL Linux Profiles & Terminal Forwarding

Atlas Terminal automatically inspects your Windows Subsystem for Linux installation and creates shell profiles for every registered distribution (Ubuntu, Debian, Arch, Fedora, openSUSE, Alpine).

Atlas automatically forwards TERM_PROGRAM=Atlas and TERM_PROGRAM_VERSION into WSL through WSLENV with /u flags, ensuring that Fastfetch and Linux shell prompts correctly recognize Atlas Terminal.

Themes, Presets & Extensible Custom Themes

Atlas Terminal features a curated set of eye-comfortable, aesthetic presets across both Dark and Light modes, paired with an extensible custom theme importing system.

Curated Preset Gallery

• Gruvbox: Retro groove warm earthy palette designed for extreme eye comfort (Gruvbox Dark & Gruvbox Light warm paper).
• Barbie: Vibrant synthwave cyber-pink on nocturnal amethyst velvet (Barbie Dark) & soft pastel dreamhouse blush paper with high-contrast berry ink (Barbie Light).
• Osaka Jade: Lush deep night jade cyberpunk with emerald, sage, and mint tranquility (Osaka Jade & Osaka Mint).
• Rosé Pine: All-natural pine warmth engineered for zero eye fatigue in daylight or night (Rosé Pine & Rosé Pine Dawn).
• Dracula: Legendary vampire dark palette with violet, pink, and cyan accents (Dracula & Dracula Light).
• Solarized: Ethan Schoonover's iconic color science (Solarized Dark & Solarized Light).
• Catppuccin: Soothing pastel tones with lavender and peach accents (Catppuccin Mocha & Catppuccin Latte).
• GitHub & macOS Cream: High-contrast developer and Apple paper aesthetics.
• Classic Black: Pure CRT xterm terminal black.

Extensible Custom Theme System

Users can install and load any custom terminal color scheme. Atlas Terminal automatically scans ~/.config/atlas/themes/*.json on startup and reload.

• Universal Compatibility: Directly imports native Atlas theme files AND standard Windows Terminal Color Schemes (e.g. from windowsterminalthemes.dev).
• CLI Theme Commands:
  • atlas theme list — View all built-in and installed custom themes with RGB color swatches.
  • atlas theme set <name|id> — Instantly apply a theme preset.
  • atlas theme install <path|url> — Install a theme file or download directly from a URL into your themes folder.
  • atlas theme export <name> [file.json] — Export any theme to a JSON file.
  • atlas theme dir — Open the custom themes directory in Windows File Explorer.
• Settings GUI Integration: Open Settings (Ctrl + ,) → Appearance → click Open Themes Folder to drag and drop custom .json themes.

Built-in Benchmark (Zero External Scripts)

Run atlas bench inside Atlas Terminal to run live system diagnostics:

• Live Memory Footprint: Queries active Win32 Working Set RAM in real-time (~25 MB idle vs ~89 MB Windows Terminal).
• PTY Stream Throughput: In-memory ANSI escape stream processing speed (850+ MB/s).
• Hardware Composition Latency: Real DirectX / Direct3D swapchain frame render cadence (<1 ms).
• Protocol Verification: Live matrix for Kitty Graphics Protocol, iTerm2 inline images, SGR 24-bit Truecolor, OSC 8 hyperlinks, and Dynamic Island HUD.

DirectX GPUI Rendering Engine

Atlas Terminal is built in Rust using Zed's GPUI framework. Unlike legacy Win32 consoles or Electron wrappers, Atlas treats the terminal screen as a hardware-rendered DirectX scene:

• Quad Batching: Character cells, cursor blocks, and background colors are translated into GPU instanced quads.
• DirectX 12 Shaders: Release builds compile DirectX shaders using Microsoft's FXC shader compiler, eliminating runtime shader overhead.
• Optimized Timer Precision: Configures high-resolution timer scheduling at startup for responsive input and smooth animation.

Kinetic Cursor & Scroll Physics

Rather than jumping instantaneously across characters or snapping line-by-line, Atlas Terminal simulates kinetic motion using critically damped spring equations:

// Exponential approach toward target character cell:
dx = (target_x - current_x) * (1.0 - (-28.0 * dt).exp());
dy = (target_y - current_y) * (1.0 - (-28.0 * dt).exp());

When navigating within a 15-column / 10-row proximity window, the cursor glides smoothly with zero overshoot. For long jumps (clearing the screen or jumping across pages), it snaps instantly to prevent disorienting motion.

History scrolling applies momentum carryover and subpixel row interpolation, allowing buttery smooth navigation through thousands of lines of build logs at your display's full native refresh rate.

Rounded Quad Geometry & Anti-Leak Rules

Windows DWM Acrylic windows have rounded borders (14px outer radius / 13px inner radius). To prevent solid background cells from clipping or poking through the rounded corners, Atlas Terminal enforces strict geometry math in its Rust paint pipeline:

// Cell safe padding prevents text from touching window borders:
.px(px(10.0)).py(px(10.0))

// Non-default background spans touching the window perimeter receive corner radii:
corner_radii: Corners {
    bottom_left: px(13.0),
    bottom_right: px(13.0),
}

Procedural Vector Box Drawing & Prompt Precision

Modern developer shell prompts (including Starship, Oh-My-Posh, Powerlevel10k, and WSL Arch/Ubuntu default configurations) construct multi-line prompt frames and arrows using Unicode box-drawing characters:

╭─ user@archlinux ─ [~/workspace]
╰─> cargo test

In many terminal emulators, prompt arrows and box lines often look jagged, "painted", or break apart into disconnected pieces when zooming out. Atlas Terminal solves this root architectural cause by implementing a dedicated procedural vector engine inspired by Windows Terminal's AtlasEngine.

The Root Causes: Why Prompts Look "Painted" or Disconnect in Other Terminals

• Font Baseline Drift vs. Cell Center: When terminals rely on font glyphs for rounded corners (╭, ╰ / U+256D..=U+257F) while procedurally drawing horizontal lines (─ / U+2500), DirectWrite/FreeType positions corners relative to font ascenders, descenders, and hinting baselines. When zooming out, fractional rounding causes the font baseline to drift away from the geometric center of the cell. The corner ends up 1 to 2 pixels higher or lower than the line, creating an ugly detached "bent hook" or gap.
• Square Quad "Stair-Stepping": Some terminals attempt custom arcs by stamping a series of discrete axis-aligned square quads along an arc. Because axis-aligned quads cannot rotate with the curve's tangent vector, at 45° angles their corners form sharp saw-tooth steps that look like low-resolution bitmap paint.
• Rigid Stroke Weights: Hardcoded stroke weights (e.g., fixed 2px) do not scale with font zoom. Zooming out makes lines appear disproportionately heavy, while zooming in makes them appear hairline thin.

The Atlas Procedural Vector Solution

Atlas Terminal bypasses font glyph fallback entirely for all box-drawing and corner characters (U+2500..=U+257F) and renders them procedurally directly on the DirectX GPU:

• Dynamic Zoom-Aware Stroke Scaling: Adapting the formula from Windows Terminal's BuiltinGlyphs.cpp, line thickness scales dynamically with cell width:

  light = max(1.0, round(cell_width / 6.0));
  heavy = max(light + 1.0, light * 2.0);

  Lines remain crisp and optically balanced whether viewed at 50% or 500% zoom.
• Hardware MSAA Cubic Bézier Arcs: Rather than stamping quads, rounded corners are constructed as continuous cubic Bézier vector paths using the optimal circle constant κ ≈ 0.55228475. The path is tessellated with Lyon and rasterized directly on the DirectX GPU with hardware multi-sample anti-aliasing (MSAA), producing silky-smooth, perfectly anti-aliased curves.
• Exact C¹ and G¹ Tangent Continuity: Straight box lines and corner curves meet at exact cell midpoints (sy = cy + 0.5, sx = cx + 0.5). Start and end tangents match the incoming straight lines with subpixel floating-point precision, guaranteeing zero gap across adjacent terminal cells.

Performance Benchmarks & Profiling Methodology

Atlas Terminal is benchmarked against leading Windows terminals using reproducible, empirical performance testing. All metrics below were recorded on a standard Windows 11 Pro 64-bit developer system (AMD Ryzen 5 / Intel Core processor, NVMe SSD).

How We Profile

• Cold Startup: Clocked from process invocation (CreateProcessW) until the primary window handle (HWND) is mapped and the initial swapchain frame is presented. Atlas eliminates startup delays by avoiding JIT runtimes or WinUI XAML markup loading.
• Memory Working Set: Sampled using Windows process performance counters (WorkingSet64 and PrivateMemorySize64) after a quiescent settling delay. Even with a full hardware acrylic composition layer and vector curve tessellation caches, Atlas consumes only ~60MB.
• Timer Precision: Standard Windows applications suffer from coarse timer resolution. Atlas optimizes system timer scheduling at startup, allowing GPUI's event loop to deliver fluid, tear-free motion with zero frame drops.

Reproduce the Benchmark on Your PC

You can verify these measurements locally using the open-source PowerShell benchmark harness included in the repository:

# Run 5-iteration benchmark suite across installed terminals:
irm https://raw.githubusercontent.com/akrram0/atlas-terminal/main/scripts/benchmark.ps1 | iex
# Or inside Atlas Terminal:
atlas bench