nai - Nushell AI Agent CLI

nai is a Nushell plugin that lets you drive AI coding agents (Forge and Claude Code) directly from your shell prompt -- without dropping into their interactive TUIs. Send prompts, manage conversations, switch models, generate commits, and more, all as regular Nushell commands.

Your right prompt automatically shows the active agent, model, token usage, and cost so you always know where you are.

Prerequisites

Dependency	Required	Notes
Nushell >= 0.100	Yes
Forge	Yes	Primary backend (forge binary in PATH)
fzf	Yes	Powers interactive pickers
fd	No	Used for @[file] completion
Claude Code	No	Optional second backend (claude binary in PATH)

Installation

Clone the repo and run the installer from within the nu-plugin/ directory:

git clone https://github.com/<owner>/nai.git
nu nai/nu-plugin/install.nu

This will:

1. Copy the plugin files to ~/.local/share/nai/ (or $XDG_DATA_HOME/nai/).
2. Inject a use import block into your Nushell config.nu to load the plugin module and wire up the right prompt.

To install to a custom location:

nu nu-plugin/install.nu --path /my/custom/path

For development (symlinks instead of copies):

nu nu-plugin/install.nu --dev

Restart Nushell after installing.

Verify

Run the built-in diagnostics to confirm everything is wired up:

nai doctor

Usage

Every command lives under the nai namespace. Nushell gives you tab-completion for all subcommands for free.

Sending prompts

# Start a new conversation
nai new

# Start a new conversation with an initial prompt
nai new refactor the error handling in src/main.rs

# Send a prompt to the current conversation (auto-creates one if needed)
nai ask add unit tests for the parser module

# Send a planning prompt (uses muse agent for Forge, plan mode for Claude)
nai plan help me plan how to implementa new "nai plan" feature that prompts in planning mode

# Open your $EDITOR to compose a longer prompt
nai edit

Multi-line and special-character prompts

Bare-word arguments work for simple prompts, but Nushell's parser will interpret backticks, parentheses, and quotes as syntax. Two alternative input modes avoid this:

# Pipe a quoted string -- supports multi-line, backticks, parens, etc.
"Can you explain what `async fn` does?
Also, what about impl Trait (bounded)?" | nai ask

# Run with no arguments -- opens an interactive reedline prompt
# Use Alt+Enter or Ctrl+Enter to insert newlines, Enter to submit
nai ask

Both modes also work with nai new:

"Refactor the parser to use `nom` instead" | nai new
nai new   # opens interactive prompt

Conversations

# Pick a conversation with fzf
nai c

# Switch to a conversation by ID
nai c <conversation-id>

# Toggle between current and previous conversation (like cd -)
nai c -

# Clone, rename, copy last response, dump, or compact
nai clone
nai rename my feature branch work
nai copy          # copies last assistant message to clipboard
nai dump          # print conversation content (also: nai dump html)
nai compact       # compact the conversation to save tokens
nai retry         # retry the last message

Agents and models

# Pick an agent with fzf, or set one directly
nai agent
nai agent muse

# Pick a session model with fzf, or set one directly
nai model
nai model claude-sonnet-4-20250514

# Reset session model/provider/reasoning-effort back to defaults
nai model-reset

# Set reasoning effort for the session
nai reasoning-effort high

Git integration

# AI-generated commit message (stages + commits)
nai commit
nai commit fixing the off-by-one in pagination

# Preview the commit message and place it in the command buffer to edit
nai commit-preview

# Generate a shell command from natural language
nai suggest list all docker containers sorted by memory usage

Backend switching

nai defaults to the Forge backend. To switch to Claude Code:

nai backend claude

Switch back:

nai backend forge

Some features (conversation listing, clone, workspace sync, etc.) are Forge-specific and will print an informational message when used with the Claude backend. nai help automatically adapts to the active backend, showing only the commands that are supported.

Configuration (Forge backend)

nai config               # show current config
nai config-edit          # open forge config in $EDITOR
nai config-model         # set global model via fzf
nai config-commit-model  # set the model used for commits
nai config-suggest-model # set the model used for suggestions
nai config-reasoning-effort  # set global reasoning effort
nai provider             # select active provider via fzf
nai tools                # list available tools
nai skill                # list available skills

Authentication

nai login                # login to a provider (fzf picker)
nai login <provider-id>  # login to a specific provider
nai logout               # logout

Workspace sync (Forge backend)

nai sync          # sync workspace for semantic search
nai sync-init     # initialize workspace indexing
nai sync-status   # show sync status
nai sync-info     # show workspace info

Other

nai help    # show formatted command reference
nai info    # show session info for the current conversation
nai env     # show environment info
nai doctor  # run plugin diagnostics

Running nai with no subcommand also displays the help text.

The help output is filtered based on the active backend -- commands that are not supported by the current backend are hidden, and sections where all commands are unsupported are omitted entirely.

Interactive prompt context

When nai ask or nai new is run without arguments (interactive mode), a context line is displayed above the input prompt showing the active backend, model, and agent:

⏺ [14:32:01] forge | model: claude-sonnet-4-20250514 | agent: forge
⏺ [14:32:01] Enter prompt (Alt+Enter or Ctrl+Enter for newline, Enter to submit):
  >

When no session model override is set, default is shown for the model.

Interactive prompts support persistent history -- press the up/down arrow keys to scroll through previous inputs entered in any session. History is shared across all nai ask and nai new invocations and is stored at ~/.local/share/nai/prompt_history.txt (or $XDG_DATA_HOME/nai/prompt_history.txt if set). The history file is capped at 1000 entries.

Right prompt

After installation, your Nushell right prompt automatically displays the active agent, model, token count, and session cost. This is powered by forge zsh rprompt --format ansi for the Forge backend, and shows agent + model for the Claude backend.

If your forge binary does not yet support --format ansi, the installer automatically detects this and enables a ZSH-to-ANSI color conversion shim. The forge_needs_color_convert flag in $env.NAI controls this behavior. Run nai doctor to check the current status. Once you upgrade forge, re-run the installer or set the flag manually:

$env.NAI = ($env.NAI | merge { forge_needs_color_convert: false })

Managing the right prompt

The right prompt is on by default. Use nai rprompt to toggle it or set it explicitly for the current session:

# Toggle off (then on again)
nai rprompt

# Set explicitly
nai rprompt false   # disable
nai rprompt true    # re-enable

Persisting the setting across shell restarts

Session state resets each time you open a new shell. To permanently disable the right prompt, add the following to your config.nu:

# Disable nai right prompt
$env.NAI = ($env.NAI | merge { rprompt_enabled: false })

This must appear after the use import that loads the nai plugin module (added by the installer to config.nu).

Project structure

nu-plugin/
  mod.nu                      # entry point -- module API manifest
  install.nu                  # installer script
  nai.setup.nu                # config.nu template reference
  lib/
    core/
      state.nu                # $env.NAI session state
      parsing.nu              # pure parsing utilities (find-index)
      helpers.nu              # fzf, logging, clipboard, prompt collection
      prompt.nu               # right prompt rendering
      colors.nu               # ZSH-to-ANSI color conversion shim
      completions.nu          # @[file] completion via fd+fzf
      dispatch.nu             # backend dispatch logic
    backends/
      forge.nu                # Forge Code adapter
      claude.nu               # Claude Code adapter
    actions/
      core.nu                 # new, ask, info, env, dump, compact, retry, edit, doctor
      backend.nu              # backend switching
      config.nu               # agent, model, provider, reasoning-effort, config-*
      conversation.nu         # c, clone, copy, rename
      git.nu                  # commit, commit-preview, suggest
      auth.nu                 # login, logout
      workspace.nu            # sync, sync-init, sync-status, sync-info
      help.nu                 # help command and bare nai entrypoint
tests/
  run.nu                      # test entry point
  vendor/testing.nu           # vendored test runner (nu-std 0.111)
  test_parsing.nu             # find-index tests
  test_state.nu               # init-state / update-state tests
  test_helpers.nu             # format-log / collect-prompt tests
  test_claude_backend.nu      # claude backend pure-function tests
  test_forge_backend.nu       # forge-supports tests
  test_dispatch_errors.nu     # backend-dispatch error path tests
  test_backend_switching.nu   # nai backend switching tests
  test_doctor_checks.nu       # nai doctor helper function tests
  test_colors.nu              # ZSH-to-ANSI conversion tests
  test_help.nu                # help text tests
  test_forge_ansi_check.nu    # forge ANSI detection helper tests

Development

Running the unit tests

The test suite covers all pure, side-effect-free logic in the codebase. It requires Nushell >= 0.100 with std/assert available (standard in all releases since 0.100).

Run the full suite from the repository root:

nu tests/run.nu

Run a single test by name:

nu tests/run.nu --test "find-index-returns-1-when-not-found"

Run all tests in a single module:

nu tests/run.nu --module test_parsing

List all tests without running them:

nu tests/run.nu --list

Test scope

These are unit tests for pure logic only. They do not invoke any external binaries (forge, claude, fzf, git, etc.). Integration-testing those code paths requires a full environment with those binaries present and is out of scope for this suite.