Configuration

Neusis Code is configured with JSON files. Config sources are loaded in order of precedence (highest first), and merged:

Source	Path
Project	`neusiscode.json` (or `neusiscode.jsonc`), walking up from the working directory
Global	`~/.config/neusiscode/neusiscode.json`

Project config can also live in a .neusiscode/ directory. TUI-only settings (theme, keybinds, notifications, prompt sizing) live in a separate tui.json — see TUI settings below.

:::note Auto-config on first run On first run, if no global config exists, Neusis Code seeds ~/.config/neusiscode/config.json with just a $schema reference (for editor autocompletion). The installer separately writes a full neusiscode.json with your API key, default model, and registry. TUI keys (theme, keybinds, tui) placed in neusiscode.json are ignored with a warning — move them to tui.json. :::

Example

{
  "$schema": "https://neusis.ai/config.json",
  "model": "neusiscode/auto",
  "provider": {
    "neusiscode": {
      "options": { "headerTimeout": 10000 }
    }
  }
}

Model selection

The default model is neusiscode/auto. It is written into your config by the installer and is the launch default. With auto, the proxy picks a concrete model once per session and holds it for that session (session-sticky), which keeps prompt caching effective across turns.

You can also pin a concrete model. The models currently published by the neusiscode provider are:

Model id	Display name	Context
`neusiscode/auto`	Auto (default)	—
`neusiscode/gpt-5.5`	GPT-5.5	1.05M
`neusiscode/gpt-5.4`	GPT-5.4	1.05M
`neusiscode/gpt-5.3-codex-spark`	GPT-5.3 Codex Spark	128K

{
  "model": "neusiscode/gpt-5.5"
}

note

The model list tracks the live proxy and is refreshed via registry re-syncs, so the exact ids and context sizes can change over time. Run Neusis Code's model picker to see what is currently available.

Prompt caching

The neusiscode provider enables per-session prompt caching through the setCacheKey provider option (on by default in the bundled registry). When enabled, Neusis Code emits a snake_case prompt_cache_key (set to the session id) on outgoing requests.

The snake_case form matters: the neusiscode provider is built on @ai-sdk/openai-compatible, which forwards provider options verbatim with no camelCase-to-snake_case conversion, so the camelCase promptCacheKey would never reach the wire as a usable key.

:::caution Proxy strips the key today The LiteLLM proxy currently removes prompt_cache_key from the request before the upstream OpenAI call (it is not in the proxy's allowed-keys list). So today setCacheKey mainly aids proxy-side session routing — which the always-present session-affinity header already provides. Explicit upstream cache-affinity would require the proxy to widen its allow-list. :::

Provider timeouts

Provider requests support several timeout options under provider.<id>.options:

Option	Type	Meaning
`timeout`	ms, or `false` to disable	Timeout for the full request.
`headerTimeout`	ms, or `false` to disable	Timeout waiting for response headers. Defaults to `10000` (10s) for OpenAI.
`chunkTimeout`	ms	Max gap between streamed SSE chunks before the request is aborted.

{
  "provider": {
    "openai": {
      "options": { "headerTimeout": 10000 }
    }
  }
}

Registry

Neusis Code can sync skills, agents, and commands from remote Git repositories on startup. The installer points this at the public Neusis registry by default. Each repo is fetched over HTTPS (no git binary required) and surfaced as a config source, just like a project .neusiscode/ directory.

{
  "registry": {
    "repos": [
      {
        "url": "https://github.com/Neusis-AI-Org/neusiscode-registry",
        "branch": "main",
        "subdir": ".agents"
      }
    ]
  }
}

Field	Type	Notes
`url`	string	Git repository URL to clone (GitHub only).
`branch`	string	Branch to checkout. Defaults to `main`.
`subdir`	string	Optional subdirectory within the repo to load as the config root (e.g. `.agents`). Useful when a repo serves multiple purposes.
`auth`	object	Authentication for private repositories — see below.

Private repositories

To sync a private repo, point auth.envVar at the name of an environment variable that holds a bearer token (for example a GitHub PAT). The token is resolved from that env var at sync time and sent as Authorization: Bearer <token>.

{
  "registry": {
    "repos": [
      {
        "url": "https://github.com/your-org/private-registry",
        "auth": { "envVar": "REGISTRY_TOKEN" }
      }
    ]
  }
}

:::caution Never store a literal token auth.envVar is the name of the env var, not the token itself. Never paste a literal token into this config. If the named env var is missing, the sync falls through to the cached/bundled copy rather than crashing. :::

See Skills and Agents for what the registry provides.

Remote config discovery

When you authenticate against a provider that supports it, Neusis Code looks for a config document at the provider's well-known path (/.well-known/neusiscode). That document may inline a config object and/or a remote_config pointer to a further URL. The discovered config is merged in at global precedence. This lets a provider ship organization defaults without you editing your local config.

Shell tool

The built-in shell tool runs commands with a default timeout of 2 minutes (120000 ms); the model is told this advertised limit in its prompt and can request a larger per-command timeout when a command is expected to run longer.

TUI notifications, attention sounds, and prompt sizing

TUI-specific settings live in tui.json (global at ~/.config/neusiscode/tui.json, or per-project in a .neusiscode/ directory) — not in neusiscode.json.

Attention (notifications & sounds)

Desktop notifications and attention sounds are opt-in and disabled by default. Set attention.enabled to true to turn them on:

{
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

Key	Type	Default	Meaning
`enabled`	boolean	`false`	Master switch. Nothing fires unless this is `true`.
`notifications`	boolean	`true`	Show desktop notifications (when `enabled`).
`sound`	boolean	`true`	Play attention sounds (when `enabled`).
`volume`	number	`0.4`	Sound volume, `0`–`1`.
`sound_pack`	string	built-in default	Id of the sound pack to use.
`sounds`	object	—	Per-event sound file overrides (`default`, `question`, `permission`, `error`, `done`, `subagent_done`).

Notifications fire on session completion, errors, and when a question or permission prompt needs your input.

Prompt sizing

The home-screen prompt box can be sized via prompt. The width can scale with the terminal ("auto") or be capped at a fixed column count:

{
  "prompt": {
    "max_height": 12,
    "max_width": "auto"
  }
}

Key	Type	Meaning
`max_height`	positive integer	Maximum prompt textarea height.
`max_width`	positive integer, or `"auto"`	Fixed column cap, or `"auto"` to scale with terminal width.

Example​

Model selection​

Prompt caching​

Provider timeouts​

Registry​

Private repositories​

Remote config discovery​

Shell tool​

TUI notifications, attention sounds, and prompt sizing​

Attention (notifications & sounds)​

Prompt sizing​