@neocode-ai/web 1.1.1

package/src/content/docs/config.mdx

@@ -0,0 +1,683 @@
+---
+title: Config
+description: Using the NeoCode JSON config.
+---
+
+You can configure NeoCode using a JSON config file.
+
+---
+
+## Format
+
+NeoCode supports both **JSON** and **JSONC** (JSON with Comments) formats.
+
+```jsonc title="neocode.jsonc"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  // Theme configuration
+  "theme": "neocode",
+  "model": "anthropic/claude-sonnet-4-5",
+  "autoupdate": true,
+}
+```
+
+---
+
+## Locations
+
+You can place your config in a couple of different locations and they have a
+different order of precedence.
+
+:::note
+Configuration files are **merged together**, not replaced.
+:::
+
+Configuration files are merged together, not replaced. Settings from the following config locations are combined. Later configs override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.
+
+For example, if your global config sets `theme: "neocode"` and `autoupdate: true`, and your project config sets `model: "anthropic/claude-sonnet-4-5"`, the final configuration will include all three settings.
+
+---
+
+### Precedence order
+
+Config sources are loaded in this order (later sources override earlier ones):
+
+1. **Remote config** (from `.well-known/neocode`) - organizational defaults
+2. **Global config** (`~/.config/neocode/neocode.json`) - user preferences
+3. **Custom config** (`NEOCODE_CONFIG` env var) - custom overrides
+4. **Project config** (`neocode.json` in project) - project-specific settings
+5. **`.neocode` directories** - agents, commands, plugins
+6. **Inline config** (`NEOCODE_CONFIG_CONTENT` env var) - runtime overrides
+
+This means project configs can override global defaults, and global configs can override remote organizational defaults.
+
+:::note
+The `.neocode` and `~/.config/neocode` directories use **plural names** for subdirectories: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, and `themes/`. Singular names (e.g., `agent/`) are also supported for backwards compatibility.
+:::
+
+---
+
+### Remote
+
+Organizations can provide default configuration via the `.well-known/neocode` endpoint. This is fetched automatically when you authenticate with a provider that supports it.
+
+Remote config is loaded first, serving as the base layer. All other config sources (global, project) can override these defaults.
+
+For example, if your organization provides MCP servers that are disabled by default:
+
+```json title="Remote config from .well-known/neocode"
+{
+  "mcp": {
+    "jira": {
+      "type": "remote",
+      "url": "https://jira.example.com/mcp",
+      "enabled": false
+    }
+  }
+}
+```
+
+You can enable specific servers in your local config:
+
+```json title="neocode.json"
+{
+  "mcp": {
+    "jira": {
+      "type": "remote",
+      "url": "https://jira.example.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+---
+
+### Global
+
+Place your global NeoCode config in `~/.config/neocode/neocode.json`. Use global config for user-wide preferences like themes, providers, or keybinds.
+
+Global config overrides remote organizational defaults.
+
+---
+
+### Per project
+
+Add `neocode.json` in your project root. Project config has the highest precedence among standard config files - it overrides both global and remote configs.
+
+:::tip
+Place project specific config in the root of your project.
+:::
+
+When NeoCode starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.
+
+This is also safe to be checked into Git and uses the same schema as the global one.
+
+---
+
+### Custom path
+
+Specify a custom config file path using the `NEOCODE_CONFIG` environment variable.
+
+```bash
+export NEOCODE_CONFIG=/path/to/my/custom-config.json
+neocode run "Hello world"
+```
+
+Custom config is loaded between global and project configs in the precedence order.
+
+---
+
+### Custom directory
+
+Specify a custom config directory using the `NEOCODE_CONFIG_DIR`
+environment variable. This directory will be searched for agents, commands,
+modes, and plugins just like the standard `.neocode` directory, and should
+follow the same structure.
+
+```bash
+export NEOCODE_CONFIG_DIR=/path/to/my/config-directory
+neocode run "Hello world"
+```
+
+The custom directory is loaded after the global config and `.neocode` directories, so it **can override** their settings.
+
+---
+
+## Schema
+
+The config file has a schema that's defined in [**`neo.khulnasoft.com/config.json`**](https://neo.khulnasoft.com/config.json).
+
+Your editor should be able to validate and autocomplete based on the schema.
+
+---
+
+### TUI
+
+You can configure TUI-specific settings through the `tui` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "tui": {
+    "scroll_speed": 3,
+    "scroll_acceleration": {
+      "enabled": true
+    },
+    "diff_style": "auto"
+  }
+}
+```
+
+Available options:
+
+- `scroll_acceleration.enabled` - Enable macOS-style scroll acceleration. **Takes precedence over `scroll_speed`.**
+- `scroll_speed` - Custom scroll speed multiplier (default: `3`, minimum: `1`). Ignored if `scroll_acceleration.enabled` is `true`.
+- `diff_style` - Control diff rendering. `"auto"` adapts to terminal width, `"stacked"` always shows single column.
+
+[Learn more about using the TUI here](/docs/tui).
+
+---
+
+### Server
+
+You can configure server settings for the `neocode serve` and `neocode web` commands through the `server` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "server": {
+    "port": 4096,
+    "hostname": "0.0.0.0",
+    "mdns": true,
+    "cors": ["http://localhost:5173"]
+  }
+}
+```
+
+Available options:
+
+- `port` - Port to listen on.
+- `hostname` - Hostname to listen on. When `mdns` is enabled and no hostname is set, defaults to `0.0.0.0`.
+- `mdns` - Enable mDNS service discovery. This allows other devices on the network to discover your NeoCode server.
+- `cors` - Additional origins to allow for CORS when using the HTTP server from a browser-based client. Values must be full origins (scheme + host + optional port), eg `https://app.example.com`.
+
+[Learn more about the server here](/docs/server).
+
+---
+
+### Tools
+
+You can manage the tools an LLM can use through the `tools` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "tools": {
+    "write": false,
+    "bash": false
+  }
+}
+```
+
+[Learn more about tools here](/docs/tools).
+
+---
+
+### Models
+
+You can configure the providers and models you want to use in your NeoCode config through the `provider`, `model` and `small_model` options.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "provider": {},
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "anthropic/claude-haiku-4-5"
+}
+```
+
+The `small_model` option configures a separate model for lightweight tasks like title generation. By default, NeoCode tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.
+
+Provider options can include `timeout` and `setCacheKey`:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "timeout": 600000,
+        "setCacheKey": true
+      }
+    }
+  }
+}
+```
+
+- `timeout` - Request timeout in milliseconds (default: 300000). Set to `false` to disable.
+- `setCacheKey` - Ensure a cache key is always set for designated provider.
+
+You can also configure [local models](/docs/models#local). [Learn more](/docs/models).
+
+---
+
+#### Provider-Specific Options
+
+Some providers support additional configuration options beyond the generic `timeout` and `apiKey` settings.
+
+##### Amazon Bedrock
+
+Amazon Bedrock supports AWS-specific configuration:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "provider": {
+    "amazon-bedrock": {
+      "options": {
+        "region": "us-east-1",
+        "profile": "my-aws-profile",
+        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
+      }
+    }
+  }
+}
+```
+
+- `region` - AWS region for Bedrock (defaults to `AWS_REGION` env var or `us-east-1`)
+- `profile` - AWS named profile from `~/.aws/credentials` (defaults to `AWS_PROFILE` env var)
+- `endpoint` - Custom endpoint URL for VPC endpoints. This is an alias for the generic `baseURL` option using AWS-specific terminology. If both are specified, `endpoint` takes precedence.
+
+:::note
+Bearer tokens (`AWS_BEARER_TOKEN_BEDROCK` or `/connect`) take precedence over profile-based authentication. See [authentication precedence](/docs/providers#authentication-precedence) for details.
+:::
+
+[Learn more about Amazon Bedrock configuration](/docs/providers#amazon-bedrock).
+
+---
+
+### Themes
+
+You can configure the theme you want to use in your NeoCode config through the `theme` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "theme": ""
+}
+```
+
+[Learn more here](/docs/themes).
+
+---
+
+### Agents
+
+You can configure specialized agents for specific tasks through the `agent` option.
+
+```jsonc title="neocode.jsonc"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "model": "anthropic/claude-sonnet-4-5",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        // Disable file modification tools for review-only agent
+        "write": false,
+        "edit": false,
+      },
+    },
+  },
+}
+```
+
+You can also define agents using markdown files in `~/.config/neocode/agents/` or `.neocode/agents/`. [Learn more here](/docs/agents).
+
+---
+
+### Default agent
+
+You can set the default agent using the `default_agent` option. This determines which agent is used when none is explicitly specified.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "default_agent": "plan"
+}
+```
+
+The default agent must be a primary agent (not a subagent). This can be a built-in agent like `"build"` or `"plan"`, or a [custom agent](/docs/agents) you've defined. If the specified agent doesn't exist or is a subagent, NeoCode will fall back to `"build"` with a warning.
+
+This setting applies across all interfaces: TUI, CLI (`neocode run`), desktop app, and GitHub Action.
+
+---
+
+### Sharing
+
+You can configure the [share](/docs/share) feature through the `share` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "share": "manual"
+}
+```
+
+This takes:
+
+- `"manual"` - Allow manual sharing via commands (default)
+- `"auto"` - Automatically share new conversations
+- `"disabled"` - Disable sharing entirely
+
+By default, sharing is set to manual mode where you need to explicitly share conversations using the `/share` command.
+
+---
+
+### Commands
+
+You can configure custom commands for repetitive tasks through the `command` option.
+
+```jsonc title="neocode.jsonc"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "command": {
+    "test": {
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
+      "description": "Run tests with coverage",
+      "agent": "build",
+      "model": "anthropic/claude-haiku-4-5",
+    },
+    "component": {
+      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
+      "description": "Create a new component",
+    },
+  },
+}
+```
+
+You can also define commands using markdown files in `~/.config/neocode/commands/` or `.neocode/commands/`. [Learn more here](/docs/commands).
+
+---
+
+### Keybinds
+
+You can customize your keybinds through the `keybinds` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "keybinds": {}
+}
+```
+
+[Learn more here](/docs/keybinds).
+
+---
+
+### Autoupdate
+
+NeoCode will automatically download any new updates when it starts up. You can disable this with the `autoupdate` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "autoupdate": false
+}
+```
+
+If you don't want updates but want to be notified when a new version is available, set `autoupdate` to `"notify"`.
+Notice that this only works if it was not installed using a package manager such as Homebrew.
+
+---
+
+### Formatters
+
+You can configure code formatters through the `formatter` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "formatter": {
+    "prettier": {
+      "disabled": true
+    },
+    "custom-prettier": {
+      "command": ["npx", "prettier", "--write", "$FILE"],
+      "environment": {
+        "NODE_ENV": "development"
+      },
+      "extensions": [".js", ".ts", ".jsx", ".tsx"]
+    }
+  }
+}
+```
+
+[Learn more about formatters here](/docs/formatters).
+
+---
+
+### Permissions
+
+By default, neocode **allows all operations** without requiring explicit approval. You can change this using the `permission` option.
+
+For example, to ensure that the `edit` and `bash` tools require user approval:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+[Learn more about permissions here](/docs/permissions).
+
+---
+
+### Compaction
+
+You can control context compaction behavior through the `compaction` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "compaction": {
+    "auto": true,
+    "prune": true
+  }
+}
+```
+
+- `auto` - Automatically compact the session when context is full (default: `true`).
+- `prune` - Remove old tool outputs to save tokens (default: `true`).
+
+---
+
+### Watcher
+
+You can configure file watcher ignore patterns through the `watcher` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "watcher": {
+    "ignore": ["node_modules/**", "dist/**", ".git/**"]
+  }
+}
+```
+
+Patterns follow glob syntax. Use this to exclude noisy directories from file watching.
+
+---
+
+### MCP servers
+
+You can configure MCP servers you want to use through the `mcp` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {}
+}
+```
+
+[Learn more here](/docs/mcp-servers).
+
+---
+
+### Plugins
+
+[Plugins](/docs/plugins) extend NeoCode with custom tools, hooks, and integrations.
+
+Place plugin files in `.neocode/plugins/` or `~/.config/neocode/plugins/`. You can also load plugins from npm through the `plugin` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "plugin": ["neocode-helicone-session", "@my-org/custom-plugin"]
+}
+```
+
+[Learn more here](/docs/plugins).
+
+---
+
+### Instructions
+
+You can configure the instructions for the model you're using through the `instructions` option.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
+}
+```
+
+This takes an array of paths and glob patterns to instruction files. [Learn more
+about rules here](/docs/rules).
+
+---
+
+### Disabled providers
+
+You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "disabled_providers": ["openai", "gemini"]
+}
+```
+
+:::note
+The `disabled_providers` takes priority over `enabled_providers`.
+:::
+
+The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
+
+- It won't be loaded even if environment variables are set.
+- It won't be loaded even if API keys are configured through the `/connect` command.
+- The provider's models won't appear in the model selection list.
+
+---
+
+### Enabled providers
+
+You can specify an allowlist of providers through the `enabled_providers` option. When set, only the specified providers will be enabled and all others will be ignored.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "enabled_providers": ["anthropic", "openai"]
+}
+```
+
+This is useful when you want to restrict NeoCode to only use specific providers rather than disabling them one by one.
+
+:::note
+The `disabled_providers` takes priority over `enabled_providers`.
+:::
+
+If a provider appears in both `enabled_providers` and `disabled_providers`, the `disabled_providers` takes priority for backwards compatibility.
+
+---
+
+### Experimental
+
+The `experimental` key contains options that are under active development.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "experimental": {}
+}
+```
+
+:::caution
+Experimental options are not stable. They may change or be removed without notice.
+:::
+
+---
+
+## Variables
+
+You can use variable substitution in your config files to reference environment variables and file contents.
+
+---
+
+### Env vars
+
+Use `{env:VARIABLE_NAME}` to substitute environment variables:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "model": "{env:NEOCODE_MODEL}",
+  "provider": {
+    "anthropic": {
+      "models": {},
+      "options": {
+        "apiKey": "{env:ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+If the environment variable is not set, it will be replaced with an empty string.
+
+---
+
+### Files
+
+Use `{file:path/to/file}` to substitute the contents of a file:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "instructions": ["./custom-instructions.md"],
+  "provider": {
+    "openai": {
+      "options": {
+        "apiKey": "{file:~/.secrets/openai-key}"
+      }
+    }
+  }
+}
+```
+
+File paths can be:
+
+- Relative to the config file directory
+- Or absolute paths starting with `/` or `~`
+
+These are useful for:
+
+- Keeping sensitive data like API keys in separate files.
+- Including large instruction files without cluttering your config.
+- Sharing common configuration snippets across multiple config files.