Config

You can configure SlopCode using a JSON config file.

Format

SlopCode supports both JSON and JSONC (JSON with Comments) formats.

{
  "$schema": "https://slopcode.dev/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

Backward compatibility

SlopCode supports both new and legacy config names.

Preferred file names: slopcode.json and slopcode.jsonc
Legacy file names still supported: opencode.json and opencode.jsonc
Preferred config directories: .slopcode/ and ~/.config/slopcode/
Legacy directories still supported: .opencode/ and ~/.config/opencode/

If your setup already uses opencode names, you can keep using them. Migrate to slopcode names whenever it is convenient.

Locations

You can place your config in a couple of different locations and they have a different order of precedence.

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 autoupdate: true and your project config sets model: "anthropic/claude-sonnet-4-5", the final configuration will include both settings.

Precedence order

Config sources are loaded in this order (later sources override earlier ones):

Remote config (from .well-known/opencode) - organizational defaults
Global config (~/.config/slopcode/slopcode.json) - user preferences
Custom config (OPENCODE_CONFIG env var) - custom overrides
Project config (slopcode.json in project) - project-specific settings
.slopcode/.opencode directories - agents, commands, plugins
Inline config (OPENCODE_CONFIG_CONTENT env var) - runtime overrides

This means project configs can override global defaults, and global configs can override remote organizational defaults.

Remote

Organizations can provide default configuration via the .well-known/slopcode 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:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

You can enable specific servers in your local config:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Place your global SlopCode config in ~/.config/slopcode/slopcode.json. Legacy configs in ~/.config/opencode/opencode.json are still loaded for backwards compatibility.

For TUI-specific settings, use ~/.config/slopcode/tui.json (legacy ~/.config/opencode/tui.json is still supported).

Global config overrides remote organizational defaults.

Per project

Add slopcode.json in your project root. Legacy opencode.json files are still supported. Project config has the highest precedence among standard config files - it overrides both global and remote configs.

For project-specific TUI settings, add tui.json alongside it.

When SlopCode 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 SLOPCODE_CONFIG environment variable.

export SLOPCODE_CONFIG=/path/to/my/custom-config.json
slopcode 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 SLOPCODE_CONFIG_DIR environment variable. This directory will be searched for agents, commands, modes, and plugins just like the standard .slopcode (or legacy .opencode) directory, and should follow the same structure.

export SLOPCODE_CONFIG_DIR=/path/to/my/config-directory
slopcode run "Hello world"

The custom directory is loaded after the global config and .slopcode/.opencode directories, so it can override their settings.

Schema

The server/runtime config schema is defined in slopcode.dev/config.json.

TUI config uses slopcode.dev/tui.json.

Your editor should be able to validate and autocomplete based on the schema.

TUI

Use a dedicated tui.json (or tui.jsonc) file for TUI-specific settings.

{
  "$schema": "https://slopcode.dev/tui.json",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto"
}

Use SLOPCODE_TUI_CONFIG to point to a custom TUI config file.

Legacy theme, keybinds, and tui keys in slopcode.json are deprecated and automatically migrated when possible.

Learn more about TUI configuration here.

Server

You can configure server settings for the slopcode serve and slopcode web commands through the server option.

{
  "$schema": "https://slopcode.dev/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "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 SlopCode server.
mdnsDomain - Custom domain name for mDNS service. Defaults to slopcode.local. Useful for running multiple instances on the same network.
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.

Tools

You can manage the tools an LLM can use through the tools option.

{
  "$schema": "https://slopcode.dev/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Learn more about tools here.

Models

You can configure the providers and models you want to use in your SlopCode config through the provider, model and small_model options.

{
  "$schema": "https://slopcode.dev/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, SlopCode 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:

{
  "$schema": "https://slopcode.dev/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. Learn more.

Provider-Specific Options

Some providers support additional configuration options beyond the generic timeout and apiKey settings.

Amazon Bedrock

Amazon Bedrock supports AWS-specific configuration:

{
  "$schema": "https://slopcode.dev/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.

Learn more about Amazon Bedrock configuration.

Themes

Set your UI theme in tui.json.

{
  "$schema": "https://slopcode.dev/tui.json",
  "theme": "tokyonight"
}

Learn more here.

Agents

You can configure specialized agents for specific tasks through the agent option.

{
  "$schema": "https://slopcode.dev/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/slopcode/agents/ or .slopcode/agents/. Learn more here.

Default agent

You can set the default agent using the default_agent option. This determines which agent is used when none is explicitly specified.

{
  "$schema": "https://slopcode.dev/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 you’ve defined. If the specified agent doesn’t exist or is a subagent, SlopCode will fall back to "build" with a warning.

This setting applies across all interfaces: TUI, CLI (slopcode run), desktop app, and GitHub Action.

You can configure the share feature through the share option.

{
  "$schema": "https://slopcode.dev/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.

{
  "$schema": "https://slopcode.dev/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/slopcode/commands/ or .slopcode/commands/. Learn more here.

Keybinds

Customize keybinds in tui.json.

{
  "$schema": "https://slopcode.dev/tui.json",
  "keybinds": {}
}

Learn more here.

Autoupdate

SlopCode will automatically download any new updates when it starts up. You can disable this with the autoupdate option.

{
  "$schema": "https://slopcode.dev/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.

{
  "$schema": "https://slopcode.dev/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.

Permissions

By default, slopcode 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:

{
  "$schema": "https://slopcode.dev/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Learn more about permissions here.

Compaction

You can control context compaction behavior through the compaction option.

{
  "$schema": "https://slopcode.dev/config.json",
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

auto - Automatically compact the session when context is full (default: true).
prune - Remove old tool outputs to save tokens (default: true).
reserved - Token buffer for compaction. Leaves enough window to avoid overflow during compaction

Watcher

You can configure file watcher ignore patterns through the watcher option.

{
  "$schema": "https://slopcode.dev/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.

{
  "$schema": "https://slopcode.dev/config.json",
  "mcp": {}
}

Learn more here.

Plugins

Plugins extend SlopCode with custom tools, hooks, and integrations.

Place plugin files in .slopcode/plugins/ or ~/.config/slopcode/plugins/. You can also load plugins from npm through the plugin option.

{
  "$schema": "https://slopcode.dev/config.json",
  "plugin": ["slopcode-helicone-session", "@my-org/custom-plugin"]
}

Learn more here.

Instructions

You can configure the instructions for the model you’re using through the instructions option.

{
  "$schema": "https://slopcode.dev/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.

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.

{
  "$schema": "https://slopcode.dev/config.json",
  "disabled_providers": ["openai", "gemini"]
}

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.

{
  "$schema": "https://slopcode.dev/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

This is useful when you want to restrict SlopCode to only use specific providers rather than disabling them one by one.

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.

{
  "$schema": "https://slopcode.dev/config.json",
  "experimental": {}
}

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:

{
  "$schema": "https://slopcode.dev/config.json",
  "model": "{env:SLOPCODE_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:

{
  "$schema": "https://slopcode.dev/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.