NCNOIRCODE
Open workspaceDocumentation

ResourcesArticles

Article

NoirCode Under the Hood

NoirCode is a local server with several clients. The terminal UI, mini mode, desktop app, and the web app from noircode pair all talk to that server. The server holds sessions, resolves configuration, checks permissions, and runs tools. The model is called only when a step needs one.

The background server

On a normal launch, NoirCode finds or starts one shared server for your user account. Later clients attach to it, so a session survives closing the terminal. --standalone starts a private server for that process. --server connects to a URL you already have, such as http://localhost:4096. Disabling the service with noircode service set disabled true stops the shared process and makes private servers the default. Pairing requires the shared service.

Session state is stored locally. noircode debug paths prints the database, home, data, config, cache, state, tmp, bin, log, and repos locations. The database path follows the release channel and NOIRCODE_DB.

A session records the project, the selected agent, the selected model, messages, tool calls, and usage. You can leave and come back to the same session. Compaction summarizes older conversation when the context window fills, and it keeps roughly the most recent 15,000 tokens beside that summary. Snapshots taken around each model step are what /undo and /redo restore.

How the agent sees the repository

NoirCode does not upload the repository as a unit, and it does not build a dependency graph to decide relevance. The agent uses tools, and those tools run on the machine:

Permission rules run before a tool proceeds. The effect is allow, deny, or ask. Unmatched rules ask. Policies can deny a tool, a provider, or an integration outright, with no prompt. Build asks before reading sensitive environment files such as .env.

Context is whatever the agent read or received in the conversation. When that grows too large, compaction replaces the older portion with a summary. That is the context control the product ships, not a separate retrieval index.

Configuration

Settings merge from lowest to highest precedence: user config, project noircode.jsonc files from the directory root downward, then .noircode configs, then managed system config and managed preferences. Managed values cannot be overridden by a project. The same tree loads agents, commands, skills, and plugins.

A model is a provider/model id, optionally with a #variant for reasoning settings that model defines. The session model wins over the config default. If the configured default is missing, NoirCode uses the newest available supported model.

Providers are adapters over a catalog from models.dev plus anything you declare. A custom provider can be OpenAI-compatible and point baseURL at a host you run. Switching models does not change the agent or the tools.

Events

The server publishes a stream on /api/event as server-sent events. Session activity uses typed events, including:

Other streams cover permissions, files, shell processes, providers, plugins, and MCP status. Clients render this stream. They do not run the tools themselves.

What this architecture is not

There is no complexity classifier, no budget router, and no automatic hop from one provider to another when a model is slow. A retry repeats the step. A fallback model is the catalog default when your configured model is unavailable. Plugins extend the server; they are not a hook list that commits code when a file changes.

The useful boundary is simple. The server on your machine owns the session and the tools. The provider receives one assembled request at a time.