Requirements

Before installing Ultra, make sure you have the following:

πŸ“¦

Bun v1.0+

Ultra is built on Bun for maximum performance. Install from bun.sh

curl -fsSL https://bun.sh/install | bash
πŸ–₯️

Modern Terminal

256-color support minimum, true color (24-bit) recommended for best experience.

iTerm2 Kitty Alacritty Windows Terminal
πŸ’»

Operating System

macOS, Linux, or Windows with WSL. Native Windows support coming soon.

Proof of Concept

Ultra is a proof of concept exploring what a modern, AI-native terminal editor could look like. It is not currently available for download. If there's enough interest, we'll release it publicly.

First Steps

Open a Project

Launch Ultra in any directory to start editing:

# Open current directory
ultra .

# Open a specific folder
ultra ~/projects/my-app

# Open a specific file
ultra src/index.ts

Essential Commands

Ultra uses familiar keyboard shortcuts. Here are the essentials:

Ctrl+Shift+P Command Palette β€” search and run any command
Ctrl+P Quick Open β€” fuzzy find files in your project
Ctrl+B Toggle Sidebar β€” show/hide file explorer
Ctrl+` Integrated Terminal β€” open shell in editor
Ctrl+Shift+G Git Panel β€” stage, commit, view diffs
Ctrl+Shift+A AI Chat β€” open Claude/Codex assistant

Navigation

Ctrl+G Go to Line β€” jump to specific line number
Ctrl+R Go to Symbol β€” find functions/classes in file
Ctrl+Shift+R Workspace Symbols β€” find across project
Ctrl+\ Split Pane β€” divide editor vertically

Configuration

Ultra stores all configuration in ~/.ultra/. Settings use JSONC format (JSON with comments) for easy customization.

Settings

Edit ~/.ultra/settings.jsonc to customize behavior:

{
  // Editor settings
  "editor.tabSize": 2,
  "editor.wordWrap": "on",
  "editor.lineNumbers": "on",
  "editor.minimap": true,

  // Terminal settings
  "terminal.scrollback": 1000,

  // Theme
  "workbench.colorTheme": "Catppuccin FrappΓ©"
}

Keybindings

Customize shortcuts in ~/.ultra/keybindings.jsonc:

[
  {
    "key": "ctrl+s",
    "command": "file.save",
    "when": "editorFocus"
  },
  {
    "key": "ctrl+k ctrl+c",
    "command": "editor.toggleComment",
    "when": "editorFocus"
  }
]

Themes

Ultra supports VS Code-compatible themes. Place theme JSON files in ~/.ultra/themes/ or change the built-in theme in settings.

Built-in themes:

  • Catppuccin FrappΓ© (default)
  • Catppuccin Mocha
  • Catppuccin Macchiato
  • Catppuccin Latte
  • One Dark

Git Workflow

Ultra's built-in Git integration lets you stage, commit, and manage branches without leaving the editor.

Git Panel

Press Ctrl+Shift+G to open the Git panel:

  • Changed files β€” See all modified, added, and deleted files
  • Staging area β€” Stage individual files or hunks
  • Commit message β€” Write and submit commits
  • Branch info β€” Current branch and sync status

Common Operations

Ctrl+Shift+G Open Git panel
Ctrl+Shift+G S Stage current file
Ctrl+Shift+G U Unstage current file
Ctrl+Shift+G C Open commit message input
Ctrl+Shift+G D View diff for current file

Inline Diff Markers

Changes appear in the gutter as you edit:

  • Green bar β€” Added lines
  • Blue bar β€” Modified lines
  • Red triangle β€” Deleted lines

Integrated Terminal

Ultra includes a full PTY terminal with 24-bit color support, mouse input, and seamless integration with the editor.

Opening Terminals

Ctrl+` Toggle terminal panel
Ctrl+Shift+` Create new terminal
Ctrl+Shift+5 Split terminal

Terminal Features

  • 24-bit true color β€” Full color support for modern CLIs
  • Mouse support β€” Click, scroll, and select with your mouse
  • Configurable scrollback β€” Up to 10,000 lines of history
  • Multiple terminals β€” Run several shells in tabs
  • Session persistence β€” Terminal state saved across restarts

Working Directory

The terminal opens in your project root by default. The shell inherits your environment, so all your aliases, functions, and tools work normally.

# Your shell config is automatically sourced
# Example: run tests from the integrated terminal
npm test

# Or use any CLI tool
docker compose up -d

Troubleshooting

Common issues and their solutions.

Colors look wrong or washed out

Your terminal may not support true color. Check with echo $COLORTERM β€” it should show "truecolor" or "24bit". Try iTerm2, Kitty, or Alacritty for full color support.

LSP not working / No autocomplete

Make sure the language server is installed and in your PATH. For TypeScript, run npm i -g typescript-language-server typescript. Check the Problems panel (Ctrl+Shift+M) for errors.

High CPU usage

This can happen with very large projects. Try adding directories to .ultraignore (same format as .gitignore) to exclude node_modules, build outputs, etc.

Keyboard shortcuts not working

Some terminal emulators intercept shortcuts. Check your terminal's settings for conflicts. On macOS Terminal.app, Ctrl+Shift shortcuts often don't work β€” use iTerm2 instead.

Files not showing in sidebar

Ultra respects .gitignore by default. If a file is gitignored, it won't appear. Press Ctrl+Shift+P and run "Toggle Show Ignored Files" to see them.

Session not restoring

Sessions are saved to ~/.ultra/sessions/. Make sure this directory is writable. You can reset sessions by deleting this folder and restarting Ultra.

Language Support

LSP-powered intelligence for your favorite languages

πŸ“˜

TypeScript / JavaScript

Full support via typescript-language-server

npm i -g typescript-language-server typescript
🐍

Python

Intelligent analysis with Pyright

npm i -g pyright
πŸ¦€

Rust

rust-analyzer for comprehensive support

rustup component add rust-analyzer
🐹

Go

gopls provides IDE features

go install golang.org/x/tools/gopls@latest
⚑

C / C++

clangd for fast, accurate completions

brew install llvm
πŸ—„οΈ

SQL

Query completion and validation

npm i -g sql-language-server

LSP Features

With a language server installed, you get:

Autocomplete Hover Documentation Go to Definition Find References Rename Symbol Real-time Diagnostics Signature Help Code Actions

Interested in Ultra?

Ultra is a proof of concept. If there's enough interest, we'll release it publicly.