airos

A terminal multiplexer built for working with multiple Claude Code agent sessions in a single window.

┌────────────────────────┬──────────────┐
│ [claude ●][tests][+]   │  FILES       │
├────────────────────────┤              │
│                        │  v airos     │
│  Active Agent Terminal │    v src/    │
│  (full color/TUI)      │      main.rs│
│                        │    Cargo.toml│
├────────────────────────┤  README.md   │
│  Shell: $ _            │              │
├────────────────────────┴──────────────┤
│ INSERT  Agent    Esc:normal  n:new    │
└───────────────────────────────────────┘

Prerequisites

• Rust toolchain — if you don't have it:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  Then restart your terminal.

• Claude Code — airos launches claude by default. Install it via:

  npm install -g @anthropic-ai/claude-code

  Or use any other command with --agent-cmd.

• Git (optional) — enables diff highlighting in the file viewer. Works fine without it.

Install

cargo install --git https://github.com/pezkins/airos

That's it. Now type airos from anywhere.

From source

git clone https://github.com/pezkins/airos
cd airos
cargo install --path .

Quick Start

# Browse for a project directory (interactive picker)
airos

# Or pass the directory directly
airos ~/myproject

# Use a different agent command
airos ~/myproject --agent-cmd "claude --model sonnet"

When you run airos without arguments, an interactive directory picker opens:

• Up/Down — navigate the file list
• Right / Tab — open a directory
• Left / Backspace — go back to parent
• Type — filter directories by name
• Enter — select the highlighted directory as your project
• . — use the current directory
• Esc — quit

Layout

When airos starts, it auto-launches a Claude Code agent and shows three areas:

• Agent pane (top, 70%) — the active Claude Code session with full terminal emulation
• Shell pane (bottom, 30%) — a persistent shell for running commands
• Files sidebar (right) — your project's file tree, highlights modified files in orange

Modes

airos uses vim-style modal input. The current mode is always shown in the status bar at the bottom.

INSERT mode (green, default)

All keystrokes go to the focused pane. This is where you spend most of your time.

Key	Action
Esc	Switch to NORMAL mode
Ctrl+Q	Quit airos
Everything else	Sent to the focused terminal

NORMAL mode (cyan)

Keyboard shortcuts for navigation. No keystrokes reach the terminals.

Key	Action
i	Back to INSERT mode
Enter	Open file viewer / toggle dir (Files) or INSERT mode (other panes)
Tab	Cycle focus: Agent → Shell → Files
Shift+Tab	Cycle focus backwards
h / l	Previous / next agent tab
1-9	Jump to agent tab by number
n	New agent (opens creation wizard)
x	Close active agent tab
j / k	Navigate file tree (when Files focused)
r	Refresh file tree
q / Ctrl+C	Quit

PROMPT mode (yellow)

Appears when creating a new agent (n in NORMAL mode). A 4-step wizard:

1. Name — type a name for the agent
2. Scope — choose "Current project" or "Different project"
   • Current project: directory picker stays within your project, tab dot is green
   • Different project: full filesystem access, tab dot turns magenta
3. Directory — pick the working directory for the agent
4. Description — describe the agent's task (auto-sent as first message)

Key	Action
Type	Enter text (name/description steps)
Up/Down or 1/2	Select option (scope step)
Arrow keys	Navigate directories (directory step)
Right/Tab	Open directory
Left/Backspace	Go back / delete character
.	Use current directory
Enter	Confirm and advance to next step
Esc	Cancel wizard

On completion, a context file is saved to .airos/agents/<name>.md and the description is auto-sent to the agent.

VIEWER mode (magenta)

Opens when you press Enter on a file in the Files sidebar. Shows file contents with git diff highlighting and word wrap enabled by default.

• Added lines — green background with + prefix
• Deleted lines — red background with - prefix
• Untracked files — all lines shown as added (green)
• No git repo — plain file contents (no diff)

Key	Action
Mouse scroll	Scroll up/down/left/right
j / k	Scroll down / up
Ctrl+D / PageDown	Scroll down fast
Ctrl+U / PageUp	Scroll up fast
g	Jump to top
G	Jump to bottom
h / l	Scroll left / right (when wrap is off)
w	Toggle word wrap on/off
Esc / q	Close viewer

Typical Workflow

1. Run airos ~/myproject (or just airos and pick a directory)
2. Claude launches automatically — start typing your request
3. Press Esc then Tab then i to switch to the Shell pane and run commands
4. Press Esc then n to create a second agent — pick scope, directory, and describe its task
5. Press Esc then h/l to switch between agent tabs
6. Watch the Files sidebar — modified files turn orange
7. Navigate to a changed file and press Enter to review the diff
8. Press Ctrl+Q to quit from any mode

Visual Guide

Visual	Meaning
Green border	Focused pane, INSERT mode
Cyan border	Focused pane, NORMAL mode
Dark gray border	Unfocused pane
Green ● in tab	Agent is running (current project)
Magenta ● in tab	Agent is running (external project)
○ in tab	Agent has exited
Orange file name	File was recently modified
Green + line in viewer	Line was added
Red - line in viewer	Line was deleted

CLI Reference

airos [DIR] [OPTIONS]

Arguments:
  [DIR]  Project directory. Opens interactive picker if omitted.

Options:
  --agent-cmd <CMD>  Agent command [default: claude]
  -h, --help         Show help
  -V, --version      Show version

Architecture

• Rust — single binary, no runtime dependencies beyond the OS
• ratatui + crossterm — TUI rendering with mouse support
• portable-pty — real pseudo-terminals per session
• vt100 — ANSI escape sequence parsing (vim, htop, claude render correctly)
• notify — filesystem change detection
• tokio — async event handling
• git — diff highlighting via git diff (optional, graceful degradation)