Open-source terminal agent

Get from zero to ncode fast

Noumena Code is an AI coding assistant that runs in your terminal. It can inspect a codebase, edit files, run commands, and carry multi-step development work while staying inside the repository you start it from.

The public repository is noumena-network/code. Inside Noumena workstations, the same OSS export is commonly available at /mlstore/src/noumena-network/code. It is the standalone public source export of internal code/, not the full monorepo.

Fastest path

Install dependencies, build the native binary, sign in, and run it from the repository you want help with.

bun install
bun run build
.tmp/packages/ncode-0.1.0-linux-x64/ncode auth login
cd /path/to/your/project
/path/to/code/.tmp/packages/ncode-0.1.0-linux-x64/ncode

The build prints JSON with the exact binaryPath. Trust that path when the version or platform differs.

Public clone

Use this path when you are starting from GitHub.

git clone https://github.com/noumena-network/code.git
cd code
bun install
bun run build

Noumena workstation

Use this path when the OSS export already exists on the local machine.

cd /mlstore/src/noumena-network/code
bun install
bun run build

What you just built

A native single-file CLI

bun run build packages the default public-safe external build and writes artifacts under .tmp/packages/. On Linux x64, the default executable path is:

.tmp/packages/ncode-0.1.0-linux-x64/ncode

binaryPath

The executable you run.

manifestPath

Package metadata and checksums.

zipPath

The distributable archive.

Requirements

Bring only the public toolchain

You do not need the internal Noumena monorepo, Buck2, Sapling, staging launchers, or generated monorepo artifacts to build the OSS CLI.

Node.js 18 or newer

Bun 1.3.10 or newer

Rust and Cargo for native packaging

tmux only if you plan to run the full PTY/tmux test suite

Install helpers

curl -fsSL https://bun.sh/install | bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Open a new shell after installing, or make sure bun, cargo, and optional tmux are on PATH.

Connect a model account

Noumena-managed account

OAuth is the canonical login path. The command opens your browser, completes the authorization flow, and stores the local session for future CLI runs.

.tmp/packages/ncode-0.1.0-linux-x64/ncode auth login

You can also start the app and type /login inside the REPL. If the browser does not open automatically, the CLI prints a URL to paste manually.

API key or BYOK automation

For automation or direct-provider workflows, pass a Noumena API key or a supported provider key when launching the binary.

NOUMENA_API_KEY=... .tmp/packages/ncode-0.1.0-linux-x64/ncode
ANTHROPIC_API_KEY=... .tmp/packages/ncode-0.1.0-linux-x64/ncode

The launcher also reads ~/.config/noumena/ncode/api_keyby default.

Inspect

Read the repository, summarize unfamiliar code, and find the files that matter.

Edit

Apply focused changes directly to your working tree after you approve tool use.

Run

Execute shell commands, tests, and project checks from the terminal session.

Review

Explain diffs, catch risky changes, and help prepare a clean handoff.

Daily use

Start in the repo you want to change

cd /path/to/your/project
/path/to/code/.tmp/packages/ncode-0.1.0-linux-x64/ncode

The current working directory is the project context. Start from the repository root when you want Noumena Code to inspect, edit, and run commands against that repo.

Install into PATH

.tmp/packages/ncode-0.1.0-linux-x64/ncode install
cd /path/to/your/project
ncode

Source-level development

bun run build:source
./ncode --help

Build modes

Pick the mode before you build

The build mode is baked into the binary. Setting NCODE_USER_TYPE only when running an already-built binary does not switch modes.

Mode	Command	Use it for
external	bun run build:external	Default OSS/public-safe build with Noumena OAuth, Noumena API keys, and BYOK.
noumena	bun run build:noumena	Noumena first-party/product build with Noumena compatibility features enabled.
dev	bun run build:dev	Contributor build for source debugging and development gates.
internal	bun run build:internal	Internal compatibility spin for Noumena-controlled environments.

Runtime feature switches

Tune behavior without rebuilding

Some capabilities are gated at runtime so a single build can expose different behavior without recompiling.

# Enables all Noumena first-party/hidden product features that are safe for
# external users but left off by default (e.g. managed model aliases,
# first-party UI surfaces, experimental Noumena integrations).
NCODE_USER_MODE=noumena

# Uses the native OpenAI-compatible WebSocket v2 transport. This is the fastest
# and most reliable inference path for Noumena-managed models.
NCODE_OPENAI_COMPAT_WS_V2=1

These can be combined depending on your account type and preferred inference transport. Runtime switches do not change the compile-time build mode baked into an existing binary.

Verify changes

Run the right checks

The full test suite runs each test file in an isolated Bun process so global auth state and caches do not leak across files. PTY, tmux, native-package, and rendering tests can take longer because they may build the native binary.

bun run test
bun test src/path/to/file.test.ts

If tmux is missing, install it before running the full suite or stick to focused tests that do not require terminal integration.

Build path changed?

Use the binaryPath printed by bun run build. The example path includes the current package version and Linux x64 target.

Cargo missing?

Install Rust/Cargo and rebuild. The native package build is not complete without Cargo.

Different endpoints?

Override NOUMENA_BASE_URL, NOUMENA_PLATFORM_BASE_URL, or NOUMENA_OAUTH_WEB_BASE_URL only when you are intentionally targeting non-default infrastructure.

Back to Noumena Code