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 │
╰──────────────────────────────────────────────────────────────╯
- 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, noanysoup, no native dependencies.
- Node.js 22 or newer
- Linux or macOS
- pnpm 12 for development
git clone <repo> nusa
cd nusa
pnpm install
pnpm build
node dist/main.js # or link it: pnpm link --global && nusaStart the interactive UI:
nusaThe 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| 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.
| 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.
Resolution order (later wins):
- built-in defaults
- global config (
$XDG_CONFIG_HOME/nusa/config.json) - project config (
.nusa.jsonin the working directory) - environment variables (
NUSA_*) - CLI flags
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.
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.
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.jsThere are no native modules: the terminal tool uses child_process, and conversation memory uses LangGraph's in-memory MemorySaver.
- Architecture — layers, ports, event contract, request flow
- ACP — connect external agents, presets, custom agents, troubleshooting
- Providers — endpoints, tool calling, JSON fallback, local models
- ADRs: layering · normalized events · tool-calling fallback · ACP integration
{ "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": "" } }