nexus-tui 0.1.16

A TUI orchestrator to manage your installed terminal tools—access everything through a single command

Nexus

Nexus is a terminal dashboard that lets you launch your favorite CLI and TUI tools (like Neovim, Git UIs, or custom scripts) from a single interactive menu. No memorizing commands or directories required.

Think of Nexus as a launcher for terminal tools, similar to how Raycast or Alfred launch GUI apps.

Source Code: https://github.com/jdluu/Nexus

Caption: Main dashboard showing projects and tools.

Prerequisites

• Python 3.12 or newer.
• The uv package manager.
• Recommended: A modern terminal emulator with TrueColor support (e.g., Windows Terminal, ghostty, Kitty, or WezTerm).
• Recommended: A Nerd Font for optimal icon rendering.

Installation

It is recommended to use uv, a fast Python package and tool manager (similar to pipx), for a clean, isolated global installation.

# Install globally so you can run 'nexus' from anywhere
uv tool install nexus-tui

Alternative (Standard pip): You can also install via pip, though it is recommended uv or pipx to keep dependencies isolated.

pip install nexus-tui

Upgrade

To update to the latest version:

uv tool upgrade nexus-tui

Local Development

For contributors who want to modify the source code:

git clone https://github.com/jdluu/Nexus
cd Nexus
uv tool install --editable .

Cross Platform Support

Nexus supports Linux, MacOS, and Windows.

• Linux: Fully supported on standard terminals.
• MacOS: Fully supported.
• Windows: Recommended to use PowerShell 7 or Git Bash within Windows Terminal.

Note: Some tools you launch may behave differently depending on your shell and operating system.

Configuration

Nexus utilizes standard configuration paths. You can find your config file at the location listed in the First Run section above.

Minimal Starter Config

Copy this into your tools.toml to get started immediately:

# Define where your code projects live
project_root = "~/Projects"

# Add a simple tool to open a shell in the selected project
[[tool]]
label = "Shell"
category = "UTIL"
description = "Open a shell in the project"
command = "$SHELL"
requires_project = true

Understanding "Projects"

A Project is any directory found inside your project_root. Nexus scans this folder and lets you select a specific project before launching a tool.

For example, if you select the "Shell" tool above, Nexus will ask you to pick a project (e.g., ~/Projects/MyApp). It then launches $SHELL inside that directory.

Tool Definitions

Tools are defined using the [[tool]] table.

[[tool]]
label = "Neovim"
category = "DEV"
description = "Text editor"
command = "nvim"
requires_project = true

• label: The display name.
• category: The grouping identifier (e.g., DEV, UTIL).
• description: A short explanation of the function.
• command: The executable command line instruction.
• requires_project: If true, Nexus prompts for a project before running. If false, it runs immediately in the current directory.

Keybindings

Nexus comes with default keybindings (see Controls below). You can override them in the [keybindings] section of your config.

[keybindings]
# Override default quit to Alt+Q
quit = "alt+q"
# Override favorite toggle
toggle_favorite = "ctrl+f"

First Run Experience

1. Run nexus from your terminal.
2. Nexus creates a default configuration file at:
   • Linux: ~/.config/nexus/tools.toml
   • MacOS: ~/Library/Application Support/Nexus/tools.toml
   • Windows: %LOCALAPPDATA%\Nexus\tools.toml
3. On first launch, you will see an empty dashboard.
4. Edit the configuration file (see below) to add your tools and project roots.
5. Restart Nexus to see your changes.

Features

• Smart Search: Instantly find what you need with fuzzy matching, so you don't have to remember exact names.
• Persistence: Nexus remembers your recent projects and favorite tools, so common workflows are always one keystroke away.
• Favorites: Pin your most-used tools to the top of the list for quick access.

Controls

• Arrow Keys: Navigate through lists.
• Enter: Confirm selection or launch tool.
• Ctrl+F: Toggle the favorite status of a tool.
• TypeAnywhere: Instantly filter lists by typing in the search bar.
• Esc: Reset the search filter.
• Ctrl+B: Go back (on picker screens).
• Ctrl+C: Exit the application.
• Ctrl+H: Show Help / Controls.

FAQ & Troubleshooting

Does Nexus discover tools automatically?

No. You must define your tools in tools.toml so you have full control over what appears in your dashboard.

Is this a replacement for my shell?

No. Nexus is a dashboard. When you launch a tool, it temporarily suspends itself to let the tool take over your terminal found. When the tool exits, Nexus returns.

My icons look broken (rectangles or question marks).

This usually means you aren't using a Nerd Font.

1. Download a font from Nerd Fonts.
2. Install it on your system.
3. Configure your terminal emulator to use that font.

I see a blank screen on launch.

Check that your tools.toml file exists and has at least one valid [[tool]] entry. See the Configuration section for a minimal example.

Development (For Contributors)

To configure the development environment:

1. Synchronize dependencies:

   uv sync
   

2. Run the application locally:

   uv run nexus
   

3. Execute the comprehensive test suite:

   uv run pytest --cov=nexus
   

4. Perform static analysis and type checking:

   uv run ruff check .
   uv run mypy .