Documentation

What Neumann is

The code editor where agents work across your entire codebase. Local by default, any agent you like, and nothing lands without your review.

Any agent, driven the same way

Neumann starts agents as processes and normalizes their output into one event stream. Claude Code, Codex, Amp, and anything else that speaks the Agent Client Protocol behave the same once they are running — see Agents overview.

Local by default

Opening a project uploads nothing. Indexing is scoped by an ignore list and deletes what it uploads, and Privacy Mode keeps plaintext out of requests entirely — see Privacy and data.

Work that outlives your attention

Cloud agents run the same turns on hosted machines, so a long refactor does not need your laptop open. Progress and approvals reach you in the dashboard or the mobile app — see Cloud agents.

Quickstart

Install Neumann, connect an agent, and run your first task.

Install

1. 1
   Download the app

   Grab the build for your platform from useneumann.com/downloads. Native builds are available for macOS, Windows, and Linux.

2. 2
   Open a repository

   Point Neumann at a local git repository. Nothing is uploaded when you open a project — the working tree stays on your machine.

3. 3
   Make an agent available

   Neumann drives agents you already have installed. Install at least one CLI agent and make sure it is on your PATH, or set its binary path in Settings. See Connecting agents.

Run your first task

1. 1
   Start a thread

   Open a new thread and describe the change in plain language. A thread keeps the whole task — the conversation, the tool calls, and the resulting diff — in one place.

2. 2
   Watch the turn

   The agent's reasoning, file reads, and edits stream in as they happen. You can keep working elsewhere in the editor while a turn runs.

3. 3
   Review the diff

   When the turn finishes, open the diff panel and read the change hunk by hunk. Accept what you want and send the rest back for another pass.

Editor tour

Threads, the file tree, and the diff review panel.

The window splits into three regions that stay in sync with each other.

Threads

The left rail lists your projects and their threads. Each thread is one task: the messages, the agent's tool calls, and the changes it produced. Threads persist across restarts, so you can leave one half-finished and come back to it.

The change list

The middle column shows what the current turn touched, split into tracked and untracked files with the usual git status markers. Selecting a file opens it in the diff view.

Diff review

The right pane is a side-by-side diff with per-hunk staging. Additions and deletions are summarized at the bottom of the panel, so you can see the size of a change before reading it.

The composer

The bottom of a thread is where you write the next instruction. The agent picker lets you choose the runner — and for runners that support modes, the mode — for a single message without changing your default.

Agents overview

How Neumann drives agents, and what it expects from them.

An agent in Neumann is a process the editor starts, streams events from, and stops. Neumann normalizes each runner's output into one internal event stream, which is why threads look the same no matter which agent produced them.

Supported runners

Because the integration is protocol-level rather than vendor-level, adding a new agent does not change the editor's behaviour — a thread, a turn, and a diff mean the same thing throughout.

Turns and continuity

A turn is one instruction and everything the agent does in response. Neumann stores the runner's own session identifier alongside the thread and passes it back on the next turn, so a conversation keeps its context instead of restarting.

Cancelling

A running turn can be cancelled at any point. Neumann stops the process, keeps whatever the agent already produced in the thread, and leaves your working tree untouched.

Connecting agents

Point Neumann at the agent binaries you already have.

Neumann does not bundle agents. It runs the ones already installed on your machine, which keeps your existing configuration, credentials, and model choices in place.

Discovery

Each runner is found on your PATH by default — claude, codex, amp, and so on. When a binary lives somewhere unusual, override its path in Settings or with the matching environment variable.

export NEUMANN_CLAUDE_BIN=/opt/homebrew/bin/claude

$env:NEUMANN_CLAUDE_BIN = "C:\tools\claude.exe"

Config roots

Runners that keep their own config directory are editable from inside Neumann. Claude Code, for example, is rooted at $HOME/.claude by default and can be pointed elsewhere with NEUMANN_CLAUDE_ROOT. The Settings panel edits those files in place rather than keeping a second copy of your configuration.

Choosing a runner per message

The agent picker in the composer sets the runner for the next message only. Your default is marked with a badge and stays put, so trying another agent on one turn does not change your setup.

Reviewing changes

Nothing lands until you accept it.

Agent edits arrive as a diff, not as a fait accompli. The review flow is the same whether the work happened locally or on a cloud machine.

Reading a diff

The change list groups files into tracked and untracked, with git status markers. The diff itself is side-by-side, with per-hunk controls and a summary of files, additions, and deletions.

Accepting and rejecting

Accept the hunks you want and leave the rest. Anything you reject stays in the thread as context, so the follow-up instruction can reference it without you re-explaining the change.

Going another round

If a change is close but not right, reply in the same thread. The agent keeps the conversation's context — including the diff you just rejected — and produces a new turn.

Cloud agents

Hand a task to a hosted machine and review the diff when it lands.

Cloud agents run the same turns as local ones, on infrastructure Neumann operates. They are useful when a task outlives your attention: a long refactor, a batch of mechanical edits, or work you want to kick off before closing the laptop.

How a run works

1. 1
   Describe the task

   Pick a repository and write the instruction, the same way you would in a local thread.

2. 2
   The run is queued

   Neumann provisions a machine, clones the repository, and starts the agent.

3. 3
   Progress streams back

   Tool calls and output appear as they happen, in the dashboard or on your phone.

4. 4
   You review the result

   The run produces a diff. Nothing merges until you approve it.

Watching runs

The dashboard shows a board of runs by state — queued, running, needs attention, completed — instead of a wall of terminal tabs. Runs that need a decision from you surface separately.

Automations

Recurring work can be handed to an agent on a schedule or triggered by a webhook, with the result waiting for you afterwards.

Mobile app

Start, follow, and approve runs from your phone.

The mobile app is a client for cloud runs. It is not a code editor — it exists so a review does not have to wait until you are back at your desk.

What you can do

Signing in

The app signs in against the same account as the dashboard. Once signed in, your runs appear on both without any further setup.

Privacy and data

What stays on your machine, and what does not.

Local-first storage

Your repository lives on your machine. Opening a project, running a local agent, and reviewing a diff involve no upload.

Indexing

For features that need embeddings, files may be uploaded temporarily for processing and are deleted afterwards. Indexing is scoped by an ignore list, so you can exclude paths that should never leave the machine.

Privacy Mode

Privacy Mode keeps plaintext out of requests. Combined with the ignore list, it lets you decide exactly how much of a repository any hosted feature can see.

Cloud runs

A cloud run necessarily has a copy of the repository on the machine executing it. Access is restricted and transmission is encrypted, and the machine is torn down when the run ends.

Regional deployment

Cloud infrastructure and data are pinned to your account's region — United States, Singapore, or Malaysia — so data residency follows the account rather than the request.

Settings reference

Where Neumann keeps configuration, and the environment variables that override it.

Agent binaries and config roots

Each runner has an optional binary override and, where the runner keeps its own configuration directory, a config root override.

Values set in the environment win over the Settings panel, which in turn wins over auto-detection.

Editing runner config

The Settings panel edits runner config files in place, rooted at the directory above. There is no second copy of your configuration to keep in sync.

Per-turn overrides

Anything selected in the composer's agent picker applies to one message only and never rewrites your defaults.