Configuration ​

SubFrame stores configuration at two levels: application settings that apply globally, and project configuration that lives inside each initialized project. This guide covers both.

Settings Panel ​

Open the Settings panel with Ctrl+, (or from the menu). It contains six tabs:

• General -- startup behavior, file tree visibility, default project directory
• AI Tool -- active AI tool selection, start command overrides, custom tools
• Terminal -- font size, scrollback buffer, tab auto-rename
• Editor -- minimap, word wrap, font size, theme selection
• Appearance -- theme presets, custom themes, color pickers, feature toggles
• Updater -- auto-update checks, update channels, check intervals
• About -- version info, license, links, changelog

Changes take effect immediately and are persisted to disk.

General Settings ​

Terminal Settings ​

Editor Settings ​

The Editor tab controls the built-in CodeMirror 6 editor:

Appearance Settings ​

The Appearance tab controls SubFrame's visual theme:

Theme Presets ​

SubFrame ships with 4 built-in theme presets:

Click any preset card in the gallery to apply it immediately.

Custom Themes ​

You can create custom themes by adjusting individual color tokens:

• Accent -- Primary accent color used for highlights, badges, and active elements
• Background -- Main background color
• Text -- Primary text color

Click Save as Custom to persist your custom theme. Saved custom themes appear alongside the built-in presets.

Feature Toggles ​

Updater Settings ​

The Updater tab controls automatic update behavior:

When an update is available, SubFrame shows a notification. You choose when to download and install — updates are never forced.

AI Tool Configuration ​

SubFrame supports Claude Code, Codex CLI, and Gemini CLI with custom start commands and tool additions.

→ Full AI Tool Setup guide

Workspace Configuration ​

SubFrame organizes projects into workspaces. Workspace data is stored globally at ~/.subframe/workspaces.json.

Each workspace contains:

• A name (e.g., "Default Workspace")
• A list of projects with their paths, names, SubFrame status, and timestamps

You can:

• Create new workspaces to group projects by team, client, or purpose
• Switch between workspaces from the workspace selector in the sidebar
• Rename or delete workspaces as needed

Projects are added to the active workspace either manually (via the Add Project button) or automatically by scanning the Default Project Directory set in General settings.

Project Configuration ​

When you initialize a project as a SubFrame project, a .subframe/ directory is created containing project-level configuration and metadata.

.subframe/config.json ​

This is the per-project configuration file created during initialization:

{
  "version": "1.0",
  "name": "my-project",
  "description": "",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "initializedBy": "SubFrame",
  "settings": {
    "autoUpdateStructure": true,
    "autoUpdateNotes": false,
    "taskRecognition": true
  },
  "backlink": {
    "customMessage": "",
    "additionalRefs": []
  },
  "files": {
    "agents": "AGENTS.md",
    "claude": "CLAUDE.md",
    "gemini": "GEMINI.md",
    "structure": ".subframe/STRUCTURE.json",
    "notes": ".subframe/PROJECT_NOTES.md",
    "tasks": ".subframe/tasks.json",
    "quickstart": ".subframe/QUICKSTART.md",
    "docsInternal": ".subframe/docs-internal"
  }
}

Project Settings ​

Backlink Configuration ​

.subframe/ Directory Structure ​

Data Locations ​

SubFrame stores data in several locations on your system:

Application Data (Global) ​

Electron's userData directory holds all global application state. The path depends on your OS:

Files in this directory:

Workspace Data (Global) ​

Project Data (Per-Project) ​

Resetting Configuration ​

To reset application settings to defaults, delete the frame-settings.json file from the application data directory. SubFrame will recreate it with default values on next launch.

To reset AI tool configuration, delete ai-tool-config.json from the same directory. The active tool will revert to Claude Code.

To remove SubFrame from a project entirely, use the Uninstall option in the SubFrame Health panel. It supports selective removal of hooks, backlinks, skills, and the .subframe/ directory, with a dry-run preview before making changes.