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 three 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

Changes take effect immediately and are persisted to disk.

General Settings ​

Terminal Settings ​

Editor Settings ​

Editor settings are stored in the settings file but are not currently exposed in the Settings panel UI. You can edit them manually in the settings file (see Data Locations below).

AI Tool Configuration ​

SubFrame supports multiple AI coding tools. The AI Tool tab in Settings lets you choose which tool to use and customize its start command.

Built-in Tools ​

The Active Tool dropdown selects which tool new terminal sessions start with. Claude Code is the default.

Custom Start Command ​

Each tool's start command can be overridden. For example, if your claude binary is installed at a non-standard path, enter the full path in the Start Command field and click Save. Click Reset to Default to revert.

Custom commands are stored per-tool at the key path aiTools.<toolId>.customCommand in the settings file.

Custom Tools ​

You can register additional AI tools that appear in the sidebar tool selector and session dropdowns:

1. In the AI Tool tab, scroll to Custom Tools
2. Enter a Name (e.g., "Aider"), a Command (e.g., aider), and an optional Description
3. Click Add

Custom tools are saved to ai-tool-config.json in the application data directory. Use the trash icon to remove a custom tool.

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.