Skip to main content
Noah Code terminal wordmark

Noah Code

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

PyPI CI Python

Noah Code showing a sample build team, conversation, changed files, and review progress

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, choose Normal, Auto, or YOLO permissions, then a provider, model, and reasoning level. Choose Codex / ChatGPT account to sign in through your browser, or enter a provider API key. 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 (including .claude/skills, .claude/commands, and .claude/agents), 1-click MCP presets (noah mcp / /mcp), or markdown subagents; attach @files and images when the task needs more context.
  • Coordinated agent teams & parallel orchestration. Launch a build, review, or investigation workflow from F9 or /team, or fan out parallel subagents (task.orchestrate, including isolated Git worktree writers) with live step telemetry in the TUI subagent strip and work ledger.
  • 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:

First-time interactive setup asks you to choose a permission mode, with Normal selected by default. Your choice is saved for future launches:

  • Normal (recommended): Ask before commands that need approval; keep protective blocks enabled.
  • Auto: Approve routine actions automatically; block interpreters and keep risky-action approvals.
  • YOLO: Skip permission checks and approval prompts; use only in isolated, trusted workspaces.

This choice is separate from the AI model and build/plan mode. Use --permissions normal, --permissions auto, or --permissions yolo to override it for one launch.

# 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" .

# Use Normal permissions even if you previously saved YOLO
noah --permissions normal .

# Auto-approve routine actions; interpreter commands remain blocked
noah --auto .

# Resume previous work (picker for last 3 repo chats, latest chat, or exact ID)
noah --resume .
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 alongside noah as an equivalent entry point.

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:

Control Action
Enter Send the current prompt or accept a selected suggestion
Shift+Enter / Ctrl+J Insert a newline
Alt+Enter Expand or collapse the composer
Alt+Z Restore a displaced draft
Click / arrows in the prompt Position the editing cursor
Ctrl+A / Ctrl+X / Ctrl+V Select all / cut / paste prompt text
Ctrl+Z / Ctrl+Y Undo / redo prompt edits
Ctrl+Home / Ctrl+End Jump to the beginning / end of the prompt; Shift selects
Drag, then Cmd+C / Ctrl+Shift+C Select and copy TUI text
Ctrl+Shift+C with no selection Copy the latest Noah reply
Ctrl+G Open the searchable skills picker
Ctrl+P Search and run slash commands
Ctrl+L Open the model picker
Ctrl+R Search and recall a prior prompt
Ctrl+T Expand or collapse live tool output
Alt+E Open the reasoning-effort picker
Alt+Up Recall the newest queued prompt for editing
Ctrl+] Return to live transcript output
Tab / Shift+Tab Navigate focus; Tab completes suggestions
Enter or click a command Run the selected slash command or open its picker; required arguments stay editable
Ctrl+B Switch between build and plan mode
Ctrl+D Review changes while working or idle
Ctrl+C Stop the current run and pause queued follow-ups
F2 Open execution activity
F3 Open paginated conversation history
F4 Open the live agent, terminal, and job ledger
F5 Edit, reorder, resume, or discard queued follow-ups
F8 Show or hide the sidebar
F9 Choose a build, review, or investigation team workflow
Shift+F7 Focus or leave the scrollable context rail
Ctrl+E Edit the current prompt in $EDITOR
Ctrl+F Search messages in the active transcript
Alt+C Copy the latest fenced code block
F7 Inspect active context sources and token budget
/resume Choose from the last 3 chats in this repository
/mcp Connect 1-click MCP presets, import Claude/Cursor MCPs, or add a server
/model Configure a provider or quick-pick mainstream coding & OpenRouter models
/theme Choose Atom One Dark, Noah Ocean, Graphite, High Contrast, or Daylight
/diff Review staged and unstaged changes
/undo / /redo Traverse the persistent edit journal
/checkpoints List rolling Git worktree checkpoints
/health Inspect durable run, job, inbox, event, and artifact state
/tokens Inspect tokens, cache usage, prefix stability, model wait, and tool output
/efficiency Switch between fast, balanced, and deep budgets
/team WORKFLOW OBJECTIVE Run a coordinated team, or queue it while another turn is active

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.

See the command menu and compact approval dialog

Noah Code command menu with aligned descriptions and a subtle selection highlight

The real command menu, captured with deterministic sample conversation data.

Noah Code compact permission dialog showing a shell command, session scope, and approval choices

The real approval dialog with a sample request. Screenshots illustrate UI behavior, not a live provider run or test result.

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.

Child agents also retain their own conversation snapshots and task IDs. Noah can start, inspect, cancel, wait for, and follow up with a child independently. Background writers use an optional Git worktree created from committed HEAD; local uncommitted changes stay in the parent checkout. See persistent child tasks.

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.

You can also connect your Codex / ChatGPT account directly in /model, without an API key. Install the Codex CLI (0.153.4 or newer), then select that option or run noah providers login codex. On a headless machine, add --device-code. Noah uses the official Codex app server and a separate Codex-managed login store; account usage counts toward your Codex limits. See account setup.

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 .

Setup offers a searchable model picker, live model discovery for compatible endpoints, and manual model entry. Catalog entries whose account access has not been checked are labeled. Supported completion clients show incremental generation in a temporary terminal preview; the parsed answer is saved when generation completes. Responses clients retain their existing completed-response behavior.

/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].

Integrations

noah serve exposes authenticated loopback HTTP and resumable event streams; set NOAH_CODE_SERVER_TOKEN to a random token of at least 32 characters before starting it. noah acp exposes the same agent host through ACP v1 for compatible editors. See service and ACP for endpoints and supported capabilities.

noah browser setup configures the pinned Playwright MCP browser preset. It uses an isolated browser profile and Noah's tool permissions; Node.js and a supported browser are required. See browser tools. Trusted user configuration can also run lifecycle hooks for session, turn, and worktree events.

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

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.

Metadata

Release files for noah-code 2.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for noah-code 2.2.0
File Size Uploaded Provenance Actions
noah_code-2.2.0.tar.gz 1.0 MB With provenance Details for noah_code-2.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for noah-code 2.2.0
File Interpreter ABI Platform Actions
noah_code-2.2.0-py3-none-any.whl Python 3 none any Details for noah_code-2.2.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / noah_code-2.2.0.tar.gz

Download URL noah_code-2.2.0.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
9550216551b1fbd3afc83f528c1e14ad041fefd970a1542abf071051d001c0a1
BLAKE2b-256 checksum
How to use checksums
466c738164c5538364cecd3ced85be3760744bd95897505e5bc1c66ffd4e03a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / noah_code-2.2.0-py3-none-any.whl

Download URL noah_code-2.2.0-py3-none-any.whl
Size 487.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
afdaf7a8c7f2a07a0484aae0f5d8fea82fba865d08ddb3910389731b819e943c
BLAKE2b-256 checksum
How to use checksums
9959f839a76828dc8266986a88792c043167353b2a3ae1f9341e5bc4d6acb928
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for noah-code 2.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for noah_code-2.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page