Interface and commands

SOBA gives you an interactive console UI with slash commands, hotkeys, direct shell access, and a small task queue.

1. Starting the TUI

# Interactive mode, used by default when no prompt is passed
soba

# Explicit interactive mode
soba -i

# Start with a theme
soba --theme forest

# Continue a specific session
soba -s abc123

# Continue the latest session in the TUI
soba -c

# Open the session picker
soba -r

TUI shape

┌──────────────────────────────────────────────────────┐
│  SOBA  Agent  [-][_][×]    Budget: 12K/64K    EN │
│──────────────────────────────────────────────────────│
│  ● Active    soba-agent                               │
│──────────────────────────────────────────────────────│
│  You: Fix all TypeScript errors in src/              │
│                                                      │
│  Agent: Analyzing...                                 │
│  ┌────────────────────────────────────────────────┐   │
│  │ 🔧 read: src/utils/parser.ts                   │   │
│  │    ...                                         │   │
│  └────────────────────────────────────────────────┘   │
│  ┌────────────────────────────────────────────────┐   │
│  │ ✅ edit: Fixed 3 type errors                   │   │
│  └────────────────────────────────────────────────┘   │
│  Agent: Done. Fixed 3 errors in parser.ts.          │
│──────────────────────────────────────────────────────│
│  > _                                                  │
└──────────────────────────────────────────────────────┘

2. Hotkeys

Model selector

F2 or /model opens a dense two-column selector. Providers are on the left, models for the highlighted provider are on the right, and the search box filters both provider and model names/ids. Ctrl+M is still accepted as a legacy alias when the terminal sends it, but many terminals encode it as Enter, so do not rely on it.

Use ↑ / ↓ to move through models, ← / → or Tab / Shift+Tab to change provider, and Enter to select the highlighted model. The header shows the current provider/model, and each model row shows context window, max output, streaming, and thinking support when that metadata is available. Opening the selector refreshes built-in provider discovery, so newly available provider models can appear without restarting the whole session.

Reasoning control

F4 cycles only controls declared by the active model. Effort models cycle through provider default and their advertised effort levels; toggle models cycle through provider default, on, and off. Numeric-budget models require an explicit /reasoning budget <tokens> first, so the hotkey never invents an expensive budget.

The sidebar keeps Reasoning visible next to the model and flashes it after a change. A fallback is rendered as effective ← requested, for example provider default ← max, and the command output explains why the request was not applied. The setting affects the next model request immediately. Changing models recomputes the effective value without discarding the requested preference.

3. Slash commands

All slash commands start with /. Command names are case-insensitive.

3.1. Session

3.2. Compaction and budget

3.3. Reasoning

3.4. Skills

3.5. Interface settings

3.6. Other commands

4. Direct shell

Use ! to run shell commands directly, without asking the AI to execute them.

4.1. Basic syntax

# Run one command
!ls -la src/

# Repeat the previous shell command
!!

# Check Node version
!node --version

# Inspect git status
!git status

# Run tests
!bun test

4.2. Details

• The agent does not see the output of ! commands. It is a quick way to do something without spending tokens.
• If the agent should read the output, send a normal prompt and let the agent call the bash tool.
• Agent-started bash is visible while it runs: its block opens immediately and streams redacted output. Ctrl+C stops the active tool, keeps the output received so far, and lets the agent turn continue.
• Trust still applies: dangerous commands such as rm -rf or sudo are blocked in safe trust mode and require confirmation in normal mode. See Security.

5. Task queue

You can send more tasks while the agent is working. SOBA runs them one after another.

# The agent is working on the first request
> Fix all TS errors                                  # → Task 1, running

# Add more work while it is still busy
> Add tests for utils                                # → Queue, position 1
> Update README with new features                    # → Queue, position 2

# Inspect the queue
/queue
# Output: Queue (2 tasks)
#   1. Add tests for utils
#   2. Update README with new features

# Clear the queue
/queue clear

6. Token budget

SOBA tracks token usage in real time and compacts context when it needs to.

# Show budget
/budget

# Output:
#   Used:      28,450 tokens
#   Limit:     64,000 tokens (context window)
#   Available: 35,550 tokens
#   Messages:  42
#   Turns:     8
#   Capsules:  2

# More context details
/budget
/session

# Output:
#   Effective tokens:   32,100
#   Hard limit:         47,616
#   Safety reserve:     8,192
#   Max output:         8,192
#   Reclaimable:        12,100
#   Auto-compact:       ON

7. Scrolling history

The full message and tool history can be scrolled with:

• Page Up / Page Down — page-by-page scrolling
• Home — jump to the beginning of the session history
• End — jump to the end, where the current state is

The input line stays visible while you scroll, so you can read old context and write a new message at the same time.

8. Autocomplete

8.1. Slash commands

Press Tab after / to see available commands:

/             # Tab →
help         session      compact      budget
auto-compact capsule      config       lang
theme         skill       project-trust exit
quit          clear       search       notifications
permissions   queue

8.2. Subcommands

After a command that supports subcommands:

/skill        # Tab →
/skill list    /skill new     /skill edit
/skill eval    /skill bench   /skill trace
/skill remove  /skill:

9. Themes

SOBA includes 10 built-in color themes and lets you create your own.

# Switch theme
/theme forest

# Show the current theme
/theme

# Available themes:
# graphite, vscode, github, aurora, synthwave, paper,
# forest, highContrast, clay, operator, ink

Each theme defines semantic tokens such as accent, text, muted, success, error, and border, with support for dark and light modes. See the theme guide for details.

10. Languages

SOBA supports English, Russian, and Chinese.

# Switch language in the TUI
/lang en

# At startup
soba --lang en

# In config
{
  "lang": "en"
}

Translations live in locales/. To add a language, create its JSON file and add one entry to src/shared/i18n/locale-catalog.ts; locale types, validation, config loading, and command usage derive from that catalog.