Noah Code

A durable, repository-aware terminal coding agent built on NVIDIA's NOOA framework

_{The real Textual interface with deterministic sample data: a build team hands pagination changes to a read-only reviewer.}

Noah keeps the conversation central while the sidebar tracks the current action, changed files, active plan, and agent handoffs. Tool execution stays visible, completed work compacts into readable records, and every session remains scoped to its repository.

Built on the NVIDIA OO Agents (NOOA) runtime.

Install

Install Noah Code and its managed Python runtime with one command:

curl -LsSf https://raw.githubusercontent.com/skundu42/noah-code/main/install.sh | sh

Open a new terminal, move into a repository, and start Noah:

cd your-project
noah .

Noah is compatible with macOS on Apple Silicon and Intel, plus Linux on arm64 and x86_64.

On the first launch, the TUI walks through provider, API key, model, and reasoning setup. Keys are stored in Noah's private auth file with owner-only permissions; they are never written to project configuration or session history.

Why Noah

• Repository-aware exploration. Search with ripgrep, inspect Git history and diffs, navigate symbols through language servers, and use an mtime-cached repository map.
• Controlled edits. Apply anchored replacements or atomic multi-file patches with exact preimages, concurrent-change detection, immediate diagnostics, and rollback.
• Visible execution. Stream bounded shell output while commands run, keep servers and watchers as managed background jobs, and revisit activity details with F2.
• Crash-safe work. Durable file intents roll back interrupted workspace-tool writes, Git checkpoints protect shell-driven changes, and interrupted model runs resume after restart.
• Persistent sessions. Resume repository-scoped conversations, steering, todos, model choices, budgets, background-job logs, and compacted context without losing full tool results.
• Token-efficient by construction. Lean tool-output bounds with disk-backed recall, condensed subagent results, isolated low-token helper calls, cache-stable request prefixes (volatile status arrives as appended events), route-aware cache telemetry, selective memory distillation, and pointer-eviction compaction with a practical context ceiling — measured live with /tokens.
• Explicit control. Switch between implementation-focused build mode and read-only plan mode, with ordered allow, ask, and deny permission rules.
• Extensible workflows. Add slash commands, opt-in skills, MCP servers, or markdown subagents; attach @files and images when the task needs more context.
• Coordinated agent teams. Launch a build, review, or investigation workflow from F9 or /team. Specialists hand off findings between phases, and the live work ledger shows progress. Teams share session budgets and approvals; read-only work can run concurrently while edits use one serialized mutation lane.
• Long-running by design. Provider retries and configurable fallback models handle transient failures, while workspace leases, bounded artifacts, durable process ownership, and /health keep unattended sessions observable.

Noah follows repository instructions from AGENTS.md, CLAUDE.md, and .noah-code/instructions.md.

Quick start

Describe the outcome you want rather than prescribing every edit:

Find the cause of the failing parser tests, implement the smallest safe fix, and run the
focused test file.

For work that benefits from several perspectives, give a team one clear objective:

/team build Add pagination to the search endpoint and cover its edge cases
/team review Find regressions in the current changes
/team investigate Trace why login fails after a session expires

Build teams analyze, implement, then review. Review and investigation teams stay read-only, including in plan mode. Press F9 to choose a workflow and edit its objective before sending; use F4 to inspect live team progress. In the console, /team lists the workflows.

Useful launch modes:

# Open another workspace
noah /path/to/repository

# Inspect and plan without editing
noah --mode plan .

# Run one task and exit
noah run "Explain how authentication is wired" .

# Emit one structured result on stdout (progress goes to stderr)
noah run --json "Fix the failing unit test" .

# Allow actions that would normally ask; explicit deny rules still apply
noah run --auto "Fix the failing unit test" .

# Resume previous work
noah --continue .
noah --session SESSION_ID .

# Use the line-oriented interface
noah --console .

run --json reports status (completed, needs_input, failed, or cancelled), exit_code, explanation, session_id, run_id, session usage, and recorded checks. Check status when automating: a request for input keeps the existing exit code 0, but its status is needs_input. Check results are separate from task completion; an empty list means no checks were recorded. Errors keep nonzero exit codes and Ctrl+C returns 130. Delegated agents also retain needs_input in the work ledger.

Check the installation and resolved configuration with:

noah --version
noah doctor .
noah config show .
noah update --check

The package also installs noah-code and nc as equivalent entry points. Because nc commonly means netcat, noah or noah-code is recommended.

Inside the TUI

The interface keeps frequent actions within reach:

• Readable commands. Aligned descriptions, muted argument hints, and a subtle selection row make slash commands easier to scan. Use arrows, Enter, Tab, or the mouse.
• Compact approvals. See the command and session scope together; expand the reason and rule with D. Long targets scroll, and approval buttons stay visible in small terminals.
• Inspectable teams. Use F9 to launch a workflow and F4 to search assignments, filter work needing attention, and read agent results.

Type / to search the full command and configuration reference. The most common controls are:

On wide terminals, the side rail prioritizes the active operation, delegated agents, named terminals, Git branch and change counts, session, model usage, update state, and plan. Git status is refreshed in the background at turn boundaries, so the animated working state stays responsive. The main pane remains centered on the large Noah wordmark until the first prompt, then becomes the conversation and execution timeline. The composer footer keeps contextual keys and compact token, cache, and cost telemetry visible at every terminal width where they fit.

Sessions and crash recovery

Start a new session with noah ., resume the latest repository session with noah --continue ., or reopen an exact session with noah --session SESSION_ID .. Inside the TUI, use Ctrl+O, /sessions, or /continue.

Noah stores conversational history and host runtime state separately. If the process stops during an active run, the next launch restores pending steering, usage and budget counters, durable job logs, and the original request. Incomplete workspace-tool writes are rolled back, verified orphan process groups are cleaned up, and non-interactive runs continue automatically. A request that was waiting for user input remains paused for the next user message.

By default, only one Noah process may own a checkout at a time. Use /worktree create when independent agents need to work concurrently. See Reliability and long-running sessions for the recovery model, provider retry controls, quotas, and operational limits.

Models and providers

Noah supports OpenAI, Anthropic, OpenRouter, NVIDIA, and custom OpenAI-compatible providers. It also works with vLLM, LM Studio, Ollama, Azure OpenAI, Bedrock, Gemini, Groq, Mistral, xAI, DeepSeek, Together AI, and Perplexity.

The guided /model flow is the easiest way to configure a provider. Environment variables and the CLI remain available for scripts and headless environments:

export OPENAI_API_KEY="..."  # or ANTHROPIC_API_KEY / OPENROUTER_API_KEY
noah providers list
noah providers add openai --model MODEL_NAME
noah .

/model MODEL changes only the current session and remembers that choice when resumed. Use /model --global MODEL to set the default for future sessions in every repository.

For compatible reasoning models, choose default, none, minimal, low, medium, high, or xhigh. default omits the provider parameter:

noah --model openai/MODEL --reasoning-effort high .

See the provider configuration guide for gateway-specific setup. Provider request deadlines, exponential retry, and ordered fallback models are configured under [reliability.retries].

Updates

Noah checks PyPI for new versions at most once every 24 hours. New TUI sessions show a temporary banner when an update is available, with F6 opening its details. Installation remains explicit by default:

noah update --check
noah update

Documentation

• Interactive interface and sessions
• Configuration, modes, permissions, and updates
• Reliability and long-running sessions
• Generated-code security
• Custom commands, skills, MCP, and tracing
• Development, CI, and releases
• Release notes

Development

uv sync --extra dev --extra mcp --extra tracing
uv run ruff check src tests
uv run pytest tests
uv build

Regenerate the README screenshots from deterministic sample data with uv run python scripts/capture_readme.py. This renders the real Textual widgets without making provider calls or changing a workspace.

See the development guide for platform checks and the release process.

License

Apache-2.0. NOOA remains separately licensed by its upstream project.

Credits

Built on NVIDIA OO Agents (NOOA). Thanks to the NVIDIA NeMo team and NOOA contributors for the agent runtime that powers Noah Code.