Skip to content

TUI Usage

Hypercontext now ships a dedicated terminal UI backed by curses.

Launch it with:

python -m hypercontext tui --workdir .

This is the terminal-native companion to the browser dashboard started by python -m hypercontext ui --port 3000 --workdir ., which launches the web UI in the background with a local MCP backend and returns to the shell. The two commands serve different purposes:

  • ui opens the web dashboard entry point
  • tui opens the interactive terminal dashboard

If you want to stay in the shell, tui is the command to use.

What The TUI Shows

The terminal dashboard is built around a simple command browser:

  • a command list on the left
  • a details pane on the right
  • a footer with key hints, the currently selected command, and the active workdir

The command browser includes the major CLI entry points:

  • version
  • providers
  • run
  • compress
  • validate
  • evaluate
  • archive
  • benchmark
  • mcp
  • serve
  • ui
  • tui
  • docker

Each entry shows:

  • the command summary
  • a usage example
  • practical notes about when to use it
  • one or more example invocations
  • for filesystem-facing commands, practical --workdir usage so you can run Hypercontext against a project root or working directory

That makes the TUI useful as a live reference when you are learning the CLI or working through a run from the terminal.

Launching The TUI

The most common invocation is:

python -m hypercontext tui --workdir .

If you want to confirm that the command exists before launching the UI, use:

python -m hypercontext --help
python -m hypercontext tui --help

The command itself does not require a browser. It is designed for interactive terminal sessions, SSH sessions, and local shells where you prefer a full-screen text interface.

Keyboard Controls

The current terminal dashboard uses a small, memorable keymap:

  • ↑ and ↓ move through the command list
  • j and k do the same thing for users who prefer Vim-style navigation
  • Enter pins the current command, or runs it again if it is already pinned
  • if the cursor moves to another command while one is pinned, pressing Enter pins the new highlight instead of rerunning the old one
  • r runs the highlighted command immediately without pinning it
  • p pins the highlighted command explicitly
  • u unpins the current command and leaves the last run output visible
  • --workdir launches the TUI against a chosen repo or project root
  • ? or h toggles the help overlay
  • q or Esc quits the dashboard

If the terminal window is too small, the dashboard will display a resize message instead of trying to render a broken layout.

Suggested TUI Workflow

The TUI is most useful when you want to move quickly between the same few commands:

  1. Open python -m hypercontext tui --workdir /path/to/project
  2. Browse the command list
  3. Read the usage block for the command you care about
  4. Check the example invocations
  5. Quit and run the command directly in the shell

This works especially well for:

  • checking which subcommand handles a task
  • recalling the difference between ui and tui
  • comparing run, archive, validate, and compress
  • reviewing the standard invocation for mcp, serve, or docker

When a command is pinned, the details pane stays locked to that command even if you move the cursor elsewhere. Pressing Enter again executes the pinned command, clears the pin, and keeps the last run output visible in a separate section of the right pane. If you move to a different command before pressing Enter, the new highlight becomes the active pin. If you want to execute the highlighted command immediately without pinning, press r.

Practical Examples

Inspect provider support

Open the TUI and move to providers to confirm what is available in the current environment. Then run:

python -m hypercontext providers

Prepare an evolution run

Use the TUI to remind yourself of the run and archive flags, then start a small run:

python -m hypercontext run --generations 3 --output-dir ./runs/quick-check
python -m hypercontext archive list

Compare compression and validation

Use the TUI entries for compress and validate to keep the workflow in mind:

python -m hypercontext compress notes.txt --intensity adaptive --output notes.compressed.txt
python -m hypercontext validate notes.txt notes.compressed.txt

Compare the two UIs

The TUI is terminal-first:

python -m hypercontext tui --workdir .

The web dashboard is browser-first and launches background servers:

python -m hypercontext ui --port 3000 --workdir .

The repository keeps both entry points because they solve different workflows.

Troubleshooting

The terminal looks blank or broken

Resize the terminal window. The dashboard expects at least a modest terminal size and will show a resize warning if the area is too small.

The command exits immediately

Make sure you are running it from an interactive terminal. The TUI requires stdin and stdout to be connected to a real terminal.

Curses is unavailable

The TUI uses the Python standard library curses module. On Unix-like systems it is normally available. If your platform does not provide curses, the command will print a clear error message instead of crashing.

Where To Go Next

After using the TUI, the most natural next pages are:

The docs site keeps the terminal UI and the browser UI side by side so you can choose the interaction style that fits your workflow.