Configuration File

Reference for ~/.craft-agent/config.json

The main configuration file stores your workspace list, LLM connections, and app-wide defaults.

Location

~/.craft-agent/config.json

Structure

{
  "llmConnections": [
    {
      "slug": "anthropic-api",
      "name": "Anthropic (API Key)",
      "providerType": "anthropic",
      "authType": "api_key",
      "defaultModel": "claude-sonnet-4-6",
      "createdAt": 1737451800000
    }
  ],
  "defaultLlmConnection": "anthropic-api",
  "workspaces": [
    {
      "id": "ws-abc123",
      "name": "Personal Notes",
      "rootPath": "/path/to/workspace",
      "createdAt": 1737451800000
    }
  ],
  "activeWorkspaceId": "ws-abc123",
  "activeSessionId": "260121-swift-falcon",
  "notificationsEnabled": true,
  "colorTheme": "default"
}

Fields

llmConnections

Array of LLM connection configurations. Each connection represents a provider setup (Anthropic, Codex/OpenAI, OpenRouter, etc.).

See LLM Connections for schema details and examples.

defaultLlmConnection

Slug of the default LLM connection used for new sessions (unless overridden by a workspace). If omitted, the first connection in llmConnections is used.

workspaces

Array of configured workspaces. Each workspace represents a directory or project context.

{
  "id": "ws-abc123",
  "name": "Personal Notes",
  "rootPath": "/Users/alex/projects/notes",
  "createdAt": 1737451800000,
  "lastAccessedAt": 1737538200000
}

Field	Required	Description
id	Yes	Unique identifier for the workspace
name	Yes	Display name you assigned
rootPath	Yes	Filesystem path to the workspace directory
createdAt	Yes	Unix timestamp (ms) when the workspace was created
lastAccessedAt	No	Unix timestamp (ms) of last access, used for sorting
iconUrl	No	Custom icon URL for the workspace
mcpUrl	No	Primary MCP server URL for the workspace
mcpAuthType	No	Auth type for MCP: "workspace_oauth", "workspace_bearer", or "public"

activeWorkspaceId

The ID of the currently active workspace, or null if no workspace is selected. This determines which workspace context is used when Craft Agents starts.

activeSessionId

The ID of the currently active session within the active workspace, or null if no session is selected.

notificationsEnabled

Enable or disable desktop notifications for task completion events. Default: true.

colorTheme

ID of the selected preset theme (e.g., "dracula", "nord"). Default: "default".

For per‑workspace defaults, use defaults.colorTheme in each workspace config. See Workspaces.

dismissedUpdateVersion

Version string of an update the user has dismissed. The app won’t prompt to update to this specific version again.

pendingUpdate

Object containing information about an update ready for auto-install on next launch:

{
  "version": "0.3.0",
  "installerPath": "/path/to/installer",
  "sha256": "abc123..."
}

Example Configuration

For the modern multi-provider setup, use llmConnections plus defaultLlmConnection. Example:

{
  "llmConnections": [
    {
      "slug": "anthropic-api",
      "name": "Anthropic (API Key)",
      "providerType": "anthropic",
      "authType": "api_key",
      "defaultModel": "claude-sonnet-4-6",
      "createdAt": 1737451800000
    },
    {
      "slug": "codex",
      "name": "OpenAI (Codex)",
      "providerType": "openai",
      "authType": "oauth",
      "defaultModel": "codex-mini-latest",
      "createdAt": 1737451800000
    }
  ],
  "defaultLlmConnection": "anthropic-api",
  "workspaces": [...],
  "activeWorkspaceId": "ws-personal"
}

Modifying Configuration

Most settings can be changed through the app:

Setting	How to change
API Connection	Settings → API Connection
Model	Click the model name in the status bar
Workspace	Use the workspace dropdown in the sidebar

For advanced changes, edit the file directly while Craft Agents is not running.

Back up your config file before manual edits. Invalid JSON will prevent Craft Agents from starting.