Where Are Workspace-Specific Configurations and Themes Stored in Craft Agents OSS

Workspace-specific configurations reside in config.json files inside individual workspace directories under ~/.craft-agent/workspaces/, while theme definitions are static JSON files shipped in apps/electron/resources/themes/.

The craft-ai-agents/craft-agents-oss repository uses a file-based persistence layer for workspace settings and UI customization. Each workspace maintains its own isolated configuration directory, allowing granular control over permissions, default behaviors, and visual themes on a per-workspace basis.

Workspace Configuration Storage Location

The Root Directory Structure

All workspace data lives under the user's home directory in a dedicated dot-folder. According to the source code in packages/shared/src/workspaces/storage.ts, the system computes the default location using getDefaultWorkspacesDir(), which resolves to ~/.craft-agent/workspaces/.

Each workspace occupies a subdirectory identified by its UUID or slug (for example, ~/.craft-agent/workspaces/my-workspace). When a workspace is initialized, the system creates this folder alongside several metadata files including status, label, and permission files.

The config.json File

The primary workspace configuration is stored in a file named config.json at the root of the workspace directory. This JSON file contains UI-related preferences, default session settings, and the permission mode. The loadWorkspaceConfig() function in packages/shared/src/workspaces/storage.ts handles reading this file, while saveWorkspaceConfig() persists changes.

// packages/shared/src/workspaces/storage.ts
const CONFIG_DIR = join(homedir(), '.craft-agent');
const DEFAULT_WORKSPACES_DIR = join(CONFIG_DIR, 'workspaces');

/** Load workspace config.json from a workspace folder */
export function loadWorkspaceConfig(rootPath: string): WorkspaceConfig | null {
  const configPath = join(rootPath, 'config.json');
  // ... implementation details
}

Theme Storage and Resolution

Static Theme Definitions

Theme definitions are not stored per-workspace but are instead shipped as static assets with the Electron application. All built-in themes reside in apps/electron/resources/themes/, with each theme represented by a single JSON file (e.g., default.json, dracula.json, nord.json).

These files define color palettes including background, foreground, and accent colors. The build process copies these files into the application resources at build time via scripts/electron-build-resources.ts, though the source files remain in the repository path above.

// apps/electron/resources/themes/dracula.json
{
  "name": "dracula",
  "type": "dark",
  "colors": { "background": "#282a36", "foreground": "#f8f8f2" }
}

Theme Selection in Workspace Config

The connection between a workspace and its visual theme is established through the workspace configuration. The config.json stores the selected theme name under the theme field (or nested under defaults.theme). When the UI initializes, it reads this value and loads the corresponding theme file from the static resources directory.

Programmatic Access to Workspace Configurations

The @craft-agent/shared package exports utilities for interacting with these storage locations programmatically. This enables CLI tools and automation scripts to read or modify workspace settings without manual file manipulation.

import {
  getWorkspacePath,
  loadWorkspaceConfig,
  saveWorkspaceConfig,
} from '@craft-agent/shared/workspaces';

// Assume we have a workspace id (e.g. from `craft-cli workspaces`)
const workspaceId = 'my-workspace';

// 1️⃣ Resolve the absolute path on disk
const workspaceRoot = getWorkspacePath(workspaceId);
// → ~/.craft-agent/workspaces/my-workspace

// 2️⃣ Load the existing config (or null if none)
const cfg = loadWorkspaceConfig(workspaceRoot);
console.log('Current config:', cfg);

// 3️⃣ Change the theme (e.g. to "dracula")
const newCfg = {
  ...cfg,
  defaults: {
    ...cfg?.defaults,
    theme: 'dracula',            // ← theme name stored in config.json
  },
};

// 4️⃣ Persist the changes
saveWorkspaceConfig(workspaceRoot, newCfg);

Summary

• Workspace directories are stored under ~/.craft-agent/workspaces/ with each workspace having its own subdirectory identified by UUID or slug.
• Configuration files named config.json in each workspace root contain preferences including the selected theme, managed by packages/shared/src/workspaces/storage.ts.
• Theme definitions are static JSON files located in apps/electron/resources/themes/ and are referenced by name in the workspace configuration.
• Programmatic access is available through the shared workspace utilities to resolve paths, load configurations, and persist changes.

Frequently Asked Questions

Can I manually edit the config.json file for a workspace?

Yes, you can manually edit config.json located in ~/.craft-agent/workspaces/<workspace-id>/. The JSON structure follows the WorkspaceConfig type defined in packages/shared/src/workspaces/types.ts. Changes take effect the next time the workspace loads, though manual editing carries the risk of JSON syntax errors that could prevent the workspace from loading properly.

How do I add a custom theme to my Craft Agents installation?

Custom themes require adding a new JSON file to the apps/electron/resources/themes/ directory with a valid theme structure (name, type, colors object), then rebuilding the application. Alternatively, you can modify an existing theme file, as the UI loads themes by filename. The theme name referenced in your workspace's config.json must match the filename (without the .json extension).

Where does the application store workspace-specific API keys or secrets?

The config.json file stores workspace-specific settings including permission modes and default configurations, but sensitive credentials should be referenced through environment variables or secure credential stores rather than plain text in this file. The permission mode field in the configuration determines the security context for the workspace session.

What happens if the config.json file is corrupted or deleted?

If config.json is missing or corrupted, loadWorkspaceConfig() returns null as indicated in the storage implementation. The application typically regenerates a default configuration upon the next save operation or workspace initialization, though you may lose customized settings such as theme preferences or default session parameters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}