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
• Hooks -- Claude Code event hooks, script generation, templates
• Integrations -- Local API Server, DTSP, SubFrame Server (web/remote)
• Updates -- auto-update checks, update channels, check intervals
• About -- version info, license, links, changelog

Changes take effect immediately and are persisted to disk.

SubFrame Server Settings ​

SubFrame Server can expose the full SubFrame UI in a browser for remote desktop, tablet, and phone access.

When Allow LAN access is off, SubFrame stays on 127.0.0.1 and you should connect through an SSH tunnel. This is the recommended mode for anything beyond a trusted local network.

When Allow LAN access is on, SubFrame binds to 0.0.0.0 and becomes reachable from other devices on the same network. Use this only on trusted home or office Wi-Fi. Android access works directly in Chrome or via a QR code; no SSH tunnel app is required.

SubFrame exposes both a plain Base URL and a tokenized Connection URL in Settings. The base URL is intended for pairing-code or token-entry login from the browser access screen. The connection URL includes the current auth token and is the fastest direct-connect path.

Pairing codes are generated from the desktop app, expire after 5 minutes, and are useful when you do not want to expose the full tokenized URL. QR codes are especially convenient for phone and tablet access on LAN.

When Preferred Port is left in auto mode, SubFrame tries to reuse the last successful port when it is still available. This helps bookmarks, mobile shortcuts, and repeat remote access stay more stable without forcing a permanently fixed port.

-> For the full setup flow, see Remote Access.

General Settings ​

Terminal Settings ​

Terminal Persistence ​

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.