Skip to content

About

An AI agent that can read, write, and execute files

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

nusa

nusa is an interactive terminal coding agent. It runs its own LangGraph agent against any OpenAI-compatible endpoint, and it can hand the keyboard to other coding agents — Claude Code, Gemini CLI, Codex, OpenCode, Cursor, Copilot, goose — through the Agent Client Protocol (ACP).

Both backends speak one normalized event stream, so the Ink UI — streaming text, tool cards, diffs, plans, permission prompts — looks and behaves the same regardless of who is actually doing the work.

╭──────────────────────────────────────────────────────────────╮
│ ◆ nusa  v0.1.0 │ local · qwen2.5-coder:7b   ~/code/app        │
╰──────────────────────────────────────────────────────────────╯

Why

  • Bring your own model. Enter a base URL and a model name. No vendor lock-in, no hardcoded provider list.
  • Two kinds of agent, one interface. The built-in LangGraph agent for your own endpoint; ACP for external agents that already have their own tooling, auth and context.
  • Terminal-native. Ink + React 19 TUI: streaming answers, collapsible tool output, inline diffs, plans, permission modals, themes, command palette.
  • Honest about limits. The tools are real: files are read, diffs computed, commands run behind a permission gate. Every mutating action can ask first.
  • Small, strict codebase. Hexagonal layering enforced by dependency-cruiser; no barrels, no any soup, no native dependencies.

Requirements

  • Node.js 22 or newer
  • Linux or macOS
  • pnpm 12 for development

Install and run

git clone <repo> nusa
cd nusa
pnpm install
pnpm build
node dist/main.js        # or link it: pnpm link --global && nusa

Start the interactive UI:

nusa

The first launch opens the setup screen. Enter a base URL (http://localhost:11434/v1), pick a model from the list (or type one), optionally add an API key. Settings are written to $XDG_CONFIG_HOME/nusa/config.json with 0600 permissions. The same wizard is available later as nusa setup or /setup.

Headless one-shot:

nusa run "Explain src/main.tsx and list its imports"
nusa -p "What does package.json declare?"

Drive an external agent:

nusa -a opencode "Add a health endpoint and a test"
nusa   # then /agent claude

CLI

Command Description
nusa Interactive UI (default command)
nusa chat Same, explicitly
nusa run <prompt...> One prompt, streamed to stdout, exit code 0/1
nusa setup clack-based setup wizard (endpoint, model, key, probe)
nusa models List models exposed by the configured endpoint
nusa agents List the local backend and known ACP agents
nusa config Print resolved config, source files and which layer set each key

Global flags:

Flag Meaning
-C, --cwd <dir> Run as if started in <dir>
-b, --base-url <url> OpenAI-compatible endpoint
-m, --model <model> Local model name
-k, --api-key <key> API key (also NUSA_API_KEY, or llm.apiKeyEnv)
-a, --agent <id> Use an ACP agent (opencode, gemini, claude, codex, …)
--local Force the built-in LangGraph backend
--theme <name> tokyo-night, dracula, mono-light
--no-alt-screen Render inline instead of the alternate screen
-p, --prompt <text> Headless single prompt
--json JSON output for models, agents, config

nusa run is non-interactive: it forces permission mode to auto (unless the config says deny), so it can run in CI. The interactive UI needs a TTY and says so otherwise.

Inside the TUI

Key Action
⏎ Send
⇧⏎ / ctrl+j Newline
esc Cancel the running turn (or close a modal)
tab Complete the slash command under the cursor
ctrl+o Expand/collapse the last tool card
ctrl+t Cycle the theme
ctrl+l Clear the transcript
page up / page down Scroll the transcript
ctrl+c Quit

Slash commands:

Command Description
/help List commands
/setup Open the setup screen
/model [name] Model picker, or set a model directly
/agent [id or local] Agent picker, or switch directly
/mode [id] ACP session mode (plan, accept_edits, …)
/permissions [ask|auto|deny] Approval policy
/theme [name] Cycle or set the color theme
/clear Clear the transcript
/quit Exit

The UI merges its own commands with available_commands_update commands an ACP agent advertises.

Configuration

Resolution order (later wins):

  1. built-in defaults
  2. global config ($XDG_CONFIG_HOME/nusa/config.json)
  3. project config (.nusa.json in the working directory)
  4. environment variables (NUSA_*)
  5. CLI flags
{
  "llm": {
    "baseUrl": "http://localhost:11434/v1",
    "model": "qwen2.5-coder:7b",
    "apiKey": "optional; prefer apiKeyEnv or NUSA_API_KEY",
    "apiKeyEnv": "NUSA_API_KEY",
    "headers": {},
    "temperature": 0.2,
    "toolCalling": "auto",          // auto | native | json
    "requestTimeoutMs": 120000
  },
  "backend": "local",               // local | acp
  "acpAgent": "opencode",
  "acpAgents": {
    "mine": { "command": "my-agent", "args": ["--acp"], "env": {} }
  },
  "permissions": {
    "mode": "ask",                  // ask | auto | deny
    "autoApproveReadOnly": true,
    "allow": ["read_file", "list_dir", "glob", "grep", "todo_write"],
    "alwaysAllow": []
  },
  "terminal": { "enabled": true, "outputByteLimit": 512000 },
  "ui": { "theme": "tokyo-night", "animations": true, "maxToolOutputLines": 300 },
  "session": { "systemPromptExtra": "" }
}

Project config is merged, not replaced: a .nusa.json with only { "llm": { "model": "llama3.2" } } keeps the global URL and headers. nusa config shows the merged result and where each value came from, with secrets masked.

Environment variables: NUSA_BASE_URL, NUSA_MODEL, NUSA_API_KEY, NUSA_API_KEY_ENV, NUSA_TEMPERATURE, NUSA_TOOL_CALLING, NUSA_BACKEND, NUSA_ACP_AGENT, NUSA_THEME, NUSA_NO_ANIMATIONS, plus NUSA_NO_ALT_SCREEN, NUSA_LOG_LEVEL (debug|info|warn|error), NUSA_DEBUG, NUSA_LOG_FILE.

Logs go to $XDG_STATE_HOME/nusa/logs/nusa.log (never stdout — Ink owns it). Structural session events are appended as JSONL under $XDG_DATA_HOME/nusa/sessions/<project>/<session>.jsonl.

Repository layout

src/
  domain/        pure types, errors, ports (no I/O)
  shared/        logger, env, truncation, formatting, ids
  config/        zod schema, layered loading, paths, ACP presets
  application/   services: chat, agent, model, permissions, turns, events
  adapters/      fs, shell, terminal, storage, OpenAI provider, LangGraph, ACP
  ui/            Ink components, screens, hooks, reducer, commands, themes
  cli/           commander program and the setup wizard
  main.tsx       composition root (the only file that wires adapters)
tests/           vitest suites
docs/            architecture, ACP, providers, ADRs

Dependencies point inwards: ui → application → domain, adapters implement domain ports, and only main.tsx may import adapters. Offenses fail pnpm check.

Development

pnpm dev          # tsx src/main.tsx (TUI against the current tree)
pnpm check        # typecheck + dependency-cruiser + vitest
pnpm lint         # biome
pnpm format       # biome --write
pnpm knip         # dead code detection
pnpm build        # tsup → dist/main.js

There are no native modules: the terminal tool uses child_process, and conversation memory uses LangGraph's in-memory MemorySaver.

Documentation

About

An AI agent that can read, write, and execute files

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages