Using the TUI

The TUI (terminal interface) brings the full agent into your terminal, running locally with access to your files. This page covers day-to-day use. To install, see Install TUI; for the dry reference of every command, see TUI commands.

Start

Open the TUI with:

imaginne

imaginne chat is equivalent. On the first run, with no setup wizard, the login opens in your browser automatically — complete it and return to the terminal. The TUI requires a terminal with a TTY; if you see requires a TTY-capable terminal, use a real terminal emulator.

DEV channel

The DEV channel uses the imaginne-dev binary and the ~/.imaginne-dev folder (it does not share config with PROD). Use the build your organization points you to.

The layout and the status bar

The screen has a header (TUI — [N]umbers), the conversation viewport, the > prompt with the text box, and, at the bottom, the status bar:

EXECUTE · nnumbers · 1.2k tokens · ctx:▓▓▓░░ 38%

The bar shows the current mode (EXECUTE / PLAN / ASK), the model, token usage, and the context bar (used/limit). See Sessions to understand context and compaction.

Send and write multiple lines

• Send — Enter.
• Multi-line — paste text with multiple lines to send it all at once.

Working modes: Exec, Plan, Ask

The agent operates in one of three modes, switched with Shift+Tab (or with the commands below):

Mode	Behavior
EXECUTE	Plans and acts (edits files, runs commands and skills).
PLAN	Plans only; does not run actions with effects.
ASK	Talks/answers, without changing anything.

Equivalent commands: /exe (/execute), /plan, /ask.

Slash commands

Type / to open the menu. Full list:

Command (aliases)	What it does
/help (/h, /?)	Lists the commands.
/quit (/q, /exit)	Exits the TUI.
/clear (/cls)	Clears the conversation.
/context clear	Clears the context (restarts the model's reasoning).
/model (/m)	Opens the model picker.
/autonomy (/a)	Adjusts the autonomy level.
/verbose (/v)	Adjusts the output verbosity level.
/version	Shows the version.
/update	Updates the binary.
/diagnostics	Collects diagnostic information.
/status	Shows the session state.
/project (/p)	Project operations.
/skill (/skills)	Manages skills (see subcommands).
/sessions	Manages sessions (see subcommands).
/plan · /exe (/execute) · /ask	Switches the working mode.
/lang (/language, /idioma)	Changes the language.
/remote	Remote session pairing (see below).
/init	Initializes the project.
/iterate (/iter)	Iterates on the last output.
/agent	Subagents (see subcommands).
/login · /logout · /whoami	Identity.
/policy	Shows the effective policy.
/memory	Opens memory.
/feedback (/fb)	Sends feedback.
/todo	Session task list.

/skill subcommands

Subcommand	What it does
list	Lists the available skills.
info <name>	Details of a skill.
validate [path|key]	Validates a skill's manifest.
groups [--search q]	Lists skill groups.
publish <key|--skill-path p> --group <slug|id> [--mode]	Publishes a skill.
status	Skill sync state.

/sessions subcommands

Subcommand	What it does
list	Lists the sessions.
new <title>	Creates a session.
switch <id>	Switches sessions.
archive <id>	Archives a session.
rename <id> <title>	Renames a session.

You can't switch sessions while the agent is responding, and you can't archive the active session. See Sessions.

/agent subcommands

The TUI can delegate tasks to specialized subagents:

Subcommand	What it does
list	Lists the subagents.
spawn <type> <task>	Spawns a subagent for a task.
status	Subagent state.
cancel <id>	Cancels a subagent.
metrics · cost	Metrics and cost.

Available types: explorer, analyzer, reviewer, implementer, tester, refactorer, documenter.

Mentioning files: @

Point to a file with @ and the TUI reads its contents and injects them inline into your message:

summarize @report.md and produce an executive version

Accepted syntaxes:

• @path — relative path;
• @"path with spaces" — quoted;
• @/abs — absolute path;
• @~/home — from your user directory.

Directories, binaries, and files larger than 100 KB are ignored. Use Tab to complete (path mode and fuzzy mode) and ↑/↓ to navigate the suggestions. See Files & artifacts.

Model

/model (/m) opens the picker, filtered by the organization's policy. The default is nnumbers. The TUI always auto-routes per turn — selecting a model works as a hint/override. See Models.

Autonomy

Adjust it with /autonomy (/a) or Ctrl+A:

• low — asks about everything;
• medium — balanced;
• high — full auto.

The preference is saved in ~/.imaginne/prefs.json. The workspace vault stays active at any level. See Autonomy & permissions.

Verbosity level

/verbose (/v) or Ctrl+X cycles between silent, medium, and debug (default debug). Use lower levels for cleaner output.

Voice

Voice is speech→text: Ctrl+G or F2 starts capture (depends on a build with the voice tag; today, the darwin-arm64 release). The transcription is appended to the prompt and is not sent on its own; Esc cancels. Configurable via IMAGINNE_VOICE_* variables. See Voice.

Remote session

/remote shows a pairing code valid for 30s. On the other end, open <host>/remote in the browser, sign in, and paste the code — the prompts run on your computer and the stream comes back to both screens. Use /remote status and /remote stop to manage it. Requires login. See Remote session.

Keyboard shortcuts

Shortcut	Action
Enter	Send
Esc	Cancel (double Esc clears)
Ctrl+C	Quit
Ctrl+G / F2	Voice
Ctrl+A	Autonomy
Ctrl+T	Task panel
Ctrl+X	Verbose
Ctrl+K	Clear screen
Ctrl+O	Clear context
Ctrl+Y / F1	Help
Shift+Tab	Cycle mode (Exec/Plan/Ask)
Tab	Complete
PgUp / PgDn	Scroll the conversation

Configuration

The TUI reads ~/.imaginne/config.yaml (YAML, 0600 permissions). The main keys:

llm:
  model: nnumbers         # default model
  max_tokens: 16384
  temperature: 0.7
memory:
  storage_path: ~/.imaginne/memory

You normally don't edit this file by hand — login fills in the identity. Use imaginne config init to generate a base file.

Environment variables

Variable	Effect
IMAGINNE_DANGEROUS_BYPASS	Enables dangerous execution mode (equivalent to starting with --dangerous-bypass).
IMAGINNE_DEBUG	Turns on debug logs.
IMAGINNE_LEGACY	Legacy compatibility mode.
IMAGINNE_TUI_LOCAL_STORE=off	Disables local session storage.
IMAGINNE_GLOBAL_SKILLS_DIR	Overrides the global skills folder.
IMAGINNE_VOICE_*	Voice configuration.

The full list of client variables is in Environment variables.

See also

📖TUI commands

The full reference of commands, subcommands, and shortcuts.

Open →🛡️Autonomy & permissions

The autonomy levels and the workspace vault.

Open →🔗Remote session

Drive your local session from another screen.

Open →🎤Voice

Dictate requests by speech→text.

Open →🧰Skills

What the agent can do and how to publish new skills.

Open →⚙️Environment variables

The client variables that affect the TUI.

Open →