Configuration

simse uses separate JSON configuration files, each controlling a specific aspect of behavior. Default files are created on first run with sensible defaults.

Config directory:

• macOS: ~/Library/Application Support/simse/
• Linux: ~/.config/simse/
• Windows: %APPDATA%\simse\

Edit the JSON files directly to update configuration values. simse validates configuration on startup and reports any errors.

---

acp.json — ACP servers

Defines ACP (LLM provider) server connections. simse launches each server as a subprocess and communicates over the ACP protocol.

{
  "servers": [
    {
      "name": "anthropic",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-code"],
      "cwd": "/home/user",
      "env": { "ANTHROPIC_API_KEY": "sk-..." },
      "defaultAgent": "claude-sonnet-4-6",
      "timeoutMs": 60000
    },
    {
      "name": "local",
      "command": "ollama",
      "args": ["serve"],
      "defaultAgent": "llama3",
      "timeoutMs": 120000
    }
  ],
  "defaultServer": "anthropic",
  "defaultAgent": "claude-sonnet-4-6"
}

Fields

Field	Type	Required	Default	Description
servers	array	yes	[]	List of ACP server entries
defaultServer	string	no	—	Name of the server to use when none is specified
defaultAgent	string	no	—	Global default agent/model name

Server entry fields

Field	Type	Required	Default	Description
name	string	yes	—	Unique identifier for this server
command	string	yes	—	Command to start the ACP server process
args	string[]	no	[]	Arguments passed to the command
cwd	string	no	—	Working directory for the server process. Defaults to the current directory.
env	object	no	{}	Environment variables injected into the server process
defaultAgent	string	no	—	Default agent/model name for this server. Overrides the top-level defaultAgent when this server is selected.
timeoutMs	integer	no	60000	Request timeout in milliseconds

---

mcp.json — MCP tool servers

Defines MCP tool servers that provide tools (filesystem, database, API, etc.) to the agent during a session.

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {},
      "requiredEnv": []
    },
    {
      "name": "database",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgres://localhost/mydb" },
      "requiredEnv": ["DATABASE_URL"]
    }
  ]
}

Server entry fields

Field	Type	Required	Default	Description
name	string	yes	—	Unique identifier for this tool server
transport	string	no	"stdio"	Transport type. "stdio" launches a subprocess; "http" connects to an HTTP endpoint.
command	string	yes (stdio)	—	Command to start the server process (stdio transport only)
args	string[]	no	[]	Arguments passed to the command
env	object	no	{}	Environment variables injected into the server process
requiredEnv	string[]	no	[]	Environment variables that must be set for the server to start. simse warns if any are missing.

---

config.json — General preferences

Controls global user preferences that apply across all sessions.

{
  "defaultAgent": "claude-sonnet-4-6",
  "logLevel": "warn"
}

Fields

Field	Type	Required	Default	Description
defaultAgent	string	no	—	Default agent/model. Overridden by server-level defaultAgent in acp.json and by workspace settings.json.
logLevel	string	no	"warn"	Log verbosity level. One of: "error", "warn", "info", "debug", "trace".

---

memory.json — Memory settings

Controls the memory/library system that stores and retrieves context across sessions.

{
  "enabled": true,
  "similarityThreshold": 0.7,
  "maxResults": 10
}

Fields

Field	Type	Required	Default	Description
enabled	boolean	no	true	Enable or disable the memory system
similarityThreshold	float	no	0.7	Minimum cosine similarity score for a memory entry to be returned in queries. Range: 0.0 to 1.0.
maxResults	integer	no	10	Maximum number of memory entries returned per query

---

embed.json — Embedding provider

Configures the embedding model used by the memory system. This file is optional; simse uses a built-in default if it is absent.

{
  "embeddingModel": "nomic-ai/nomic-embed-text-v1.5"
}

Fields

Field	Type	Required	Default	Description
embeddingModel	string	no	"nomic-ai/nomic-embed-text-v1.5"	HuggingFace model identifier for the embedding model
dtype	string	no	—	Data type for model weights (e.g., "float16", "float32")
teiUrl	string	no	—	URL of an external Text Embeddings Inference server. When set, simse sends embedding requests to this endpoint instead of running the model locally.

---

Workspace overrides — .simse/settings.json

Per-project settings override the global configuration. Create a .simse/settings.json file in any project directory:

{
  "defaultAgent": "claude-opus-4-7",
  "systemPrompt": "You are a Go expert.",
  "defaultServer": "local"
}

Fields

Field	Type	Required	Default	Description
defaultAgent	string	no	—	Override the global default agent for this project
systemPrompt	string	no	—	Additional system prompt text prepended to all requests in this project
defaultServer	string	no	—	Override the default ACP server for this project

Workspace settings take precedence over config.json and acp.json top-level defaults, but do not override server-level settings within acp.json entries.

---

Workspace system prompt — SIMSE.md

Place a SIMSE.md file in the project root to define a workspace system prompt. This is a plain-text file (not JSON) that is loaded automatically when simse starts in that directory. Its contents are prepended to the system prompt for all requests.

my-project/
  .simse/
    settings.json
  SIMSE.md
  src/
    ...