nrgrd

nrgrd is NeuroGrid's Terminal User Interface (TUI) for interacting with AI models from your terminal, Claude Code style. Built on rich and prompt-toolkit, it points at any OpenAI-compatible inference endpoint — including a NeuroGrid Marketplace deployment (the URL + API key of the host you rented) — to chat, manage sessions, and run MCP tools.

Features

• Coding agent — An iterative tool-use loop (nrgrd.agent) that reads, searches, edits, and runs commands in your repository until the task is done.
• Workspace aware — Detects git, language, package manager, and test framework at startup, so the agent doesn't waste turns rediscovering your project.
• Interruptible — Ctrl+C stops generation or a running tool without corrupting the conversation, keeping whatever was produced.
• Goals — /goal <objective> keeps the agent working, round after round, until it reports the goal achieved or blocked. No iteration limit; Ctrl+C stops it.
• Real context usage — A bar above the input shows how much of the model's context window the next request uses, counting the system prompt and tool definitions too. The window comes from the endpoint (max_model_len, context_length, …) when it reports one.
• Images and files — Attach them with /attach, Ctrl+V an image from the clipboard, or drag a file onto the terminal. Images go to vision models; text files are inlined.
• Conversation graph (beta) — /graph draws the session in the terminal: each turn, the tools it used, and the files they read or wrote. Also saved as JSON.
• Long replies keep scrolling — Output taller than the terminal scrolls as it streams, and the full reply stays in the scrollback.
• NeuroChat — /neurochat opens the same endpoint and key in NeuroChat in your browser.
• Update notices — nrgrd tells you when PyPI has a newer version; /update upgrades it.
• Named sessions — Several conversations per project: list, resume, rename, delete.
• CLI mode — nrgrd "fix the failing tests" runs headless on the same runtime, for scripts and CI.
• Native tools — list_files, read_file, write_file, edit_file, search, shell, git_status, git_diff.
• Permissions — Read-only tools run automatically; file writes, shell commands, and MCP tools ask for approval first (or "always allow" for the session).
• Immersive TUI — Rich-rendered panels, streaming output, and slash-command completion with each command's description shown under the input.
• Persistent sessions — Saves conversation context and history locally.
• Any compatible endpoint — Behind a ModelProvider abstraction: a NeuroGrid deployment, vLLM, Ollama, LM Studio, or anything else speaking the same API. All nrgrd needs is a URL, a key, and a model name.
• Keys kept out of the config file — The API key lives in your OS credential store, and never appears in errors or logs.
• Errors you can act on — Failures name the endpoint and model involved and say what to change.
• Built-in MCP — Run and connect MCP servers straight from the terminal; their tools go through the same permission system.
• CLI + TUI — Use nrgrd for the interactive interface or nrgrd-mcp for the MCP server.

Installation

nrgrd runs on macOS, Linux and Windows, with Python 3.11 or newer.

uv tool install nrgrd
nrgrd

uv tool install puts nrgrd on your PATH in its own environment, and downloads a suitable Python if you don't have one. If you prefer pipx: pipx install nrgrd.

Updating

nrgrd checks PyPI at startup (at most once a day) and tells you when a new version is out. Run /update inside nrgrd, or upgrade the way you installed it:

uv tool upgrade nrgrd          # uv
pipx upgrade nrgrd             # pipx
pip install --upgrade nrgrd    # pip

Don't have uv? See installing uv.

From source

git clone https://github.com/NeuroGrid-AI-exchange/neurogrid-tui.git
cd neurogrid-tui
uv sync
uv run nrgrd

Usage

nrgrd                              # interactive TUI
nrgrd "explain this repository"    # one prompt, then exit
nrgrd --model qwen3-coder "fix the failing tests"
nrgrd --yes "run the tests"        # approve gated tools automatically (CI)

Commands

While typing a command, the line under the input describes the one highlighted in the menu.

Images and files

/attach screenshot.png notes.md sends files with your next message; pasting or dragging a file's path does the same. Ctrl+V (or /paste) attaches an image from the clipboard — on Linux that needs xclip (X11) or wl-clipboard (Wayland); macOS and Windows need nothing extra. Images only work with models that accept them.

Configuration

The first time you run nrgrd it opens a Connect to a model screen and asks for the three things a NeuroGrid deployment hands you:

Endpoint   https://<your-deployment>/v1
API key    ••••••••••••
Model      qwen3-coder

It then queries the endpoint and lets you pick from the models it actually serves. Run /config edit to change any of this later.

The endpoint and model are saved to config.json in the application's config directory. The API key is not — it goes to your operating system's credential store (Keychain, Windows Credential Manager, or a Secret Service keyring). On machines with no usable keyring it falls back to an owner-only (0600) file, and /config tells you which is in use. A key left over in an older plaintext config.json is migrated out automatically on startup.

No environment variables are needed. NRGRD_NO_UPDATE_CHECK=1 turns off the startup check for new versions.

Project structure

nrgrd/
├── src/nrgrd/
│   ├── app.py         # TUI entry point (rendering only)
│   ├── agent/         # Agent runtime: loop, events, permissions — no TUI dependency
│   ├── tools/         # Tool registry: filesystem, search, shell, git, MCP adapter
│   ├── api/           # ModelProvider abstraction + the OpenAI-compatible one
│   ├── config/        # Configuration and credential storage
│   ├── context/       # Application state, models, token estimates
│   ├── screens/       # The connect / onboarding screen
│   ├── sessions/      # Session handling and storage
│   ├── system/        # System prompts
│   ├── theme/         # Color palette and styles
│   ├── widgets/       # Custom visual components
│   └── workspace/     # Filesystem tools, project discovery, MCP client
├── docs/              # Reports and documentation
├── tests/             # Agent/tool/permission tests (no TUI, no live endpoint needed)
└── pyproject.toml     # Dependencies and project metadata

The agent runtime never imports Rich or Textual — the TUI drives it by iterating agent.run(messages) and rendering the events it yields. That keeps the agent testable headlessly and reusable from a future CLI mode.

Releasing

Push a version tag. CI runs the tests, builds, checks the built version matches the tag, and publishes to PyPI and GitHub Releases:

git tag v0.2.1
git push origin v0.2.1

The version comes from the tag; there is no version number to edit in pyproject.toml.

Development

# Install in editable mode, including dev dependencies
uv sync --dev

# Run the test suite
uv run pytest tests/

# Run linters / checks (if applicable)
uv run ruff check src/
uv run mypy src/

License

MIT © NeuroGrid