How to Access and Modify Orca Configuration Files: Paths, Patterns, and APIs

Orca stores user-level settings in plain JSON files located in ~/.copilot/config.json for global preferences and <repo>/.superset/config.json for project-specific UI customizations, which you can edit manually or modify programmatically via the IFilesystemProvider API.

Orca, the AI-assisted development environment from Stably AI (stablyai/orca), persists all mutable user settings in human-readable JSON files rather than opaque databases. Understanding how to access and modify Orca configuration files allows you to automate workspace setup, customize external app integrations, and manage trust settings across local and remote worktrees.

Configuration File Locations

Orca organizes settings into three distinct scopes. According to the source code in stablyai/orca, the runtime resolves these paths using Node’s os.homedir() for global configs and repository roots for project-local settings.

Copilot Configuration (~/.copilot/config.json)

The primary user config file resides at ~/.copilot/config.json. As implemented in [src/main/runtime/orca-runtime.ts](https://github.com/stablyai/orca/blob/main/src/main/runtime/orca-runtime.ts#L6800), this file stores:

• Trusted worktree folders – Absolute paths the user has marked as safe
• Telemetry preferences – Opt-in/out flags for analytics
• UI state – Persistent interface customizations

When working with remote worktrees over SSH, Orca resolves the remote $HOME directory and creates an identical ~/.copilot folder structure on the remote host using the markRemoteCopilotFolderTrusted helper (lines 6800–6905).

Claude Configuration (~/.claude/)

Credential caching for Claude agents uses ~/.claude/.claude.json or ~/.claude/.config.json. The claude-accounts/service.ts module (line 365) handles OAuth tokens and session data in these files.

Superset Configuration (Project-Local)

Repository-specific UI customizations live in <repo>/.superset/config.json. Defined in [src/shared/setup-script-imports.ts](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.ts#L15), this file controls the "open-in" menu mapping file extensions to external applications.

How Orca Reads and Writes Configuration Files

Orca abstracts filesystem access through the IFilesystemProvider interface rather than using raw Node.js fs calls directly. This pattern ensures compatibility with both local and remote (SSH) filesystems.

The read-modify-write cycle follows this structure, as seen in orca-runtime.ts:

const configDir = `${remoteHome}/.copilot`;
const configPath = `${configDir}/config.json`;
const raw = await this.readRemoteTextFile(fsProvider, configPath);
let config: Record<string, unknown> = {};

if (raw.trim()) {
  try {
    const parsed = JSON.parse(raw);
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
      config = parsed as Record<string, unknown>;
    }
  } catch {
    // malformed JSON → ignore, keep empty config
  }
}

// … mutate config …
await fsProvider.createDir(configDir);
await fsProvider.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);

The runtime validates JSON structure before mutation and uses fsProvider.createDir to ensure directory existence before writing.

Modifying Configuration Manually

Because these are plain JSON files, you can edit them with any text editor. Common modifications include:

Adding Trusted Worktrees

To bypass trust prompts for a specific folder, add its absolute path to the trustedFolders array:

{
  "trustedFolders": [
    "/home/user/projects/worktree-1",
    "/home/user/projects/worktree-2"
  ]
}

Customizing the "Open-In" Menu

Edit <repo>/.superset/config.json to map file extensions to applications:

{
  "openIn": {
    ".png": ["Preview", "ImageEditor"],
    ".js": ["VS Code", "Node REPL"]
  }
}

Disabling Telemetry

Set the telemetry flag in ~/.copilot/config.json:

{
  "telemetry": { "enabled": false }
}

Programmatic Modification via the Orca API

When building plugins or scripts that run inside Orca, use the provided helper functions rather than direct file manipulation.

Using markRemoteCopilotFolderTrusted

This function (lines 6800–6905 of orca-runtime.ts) atomically updates the trusted folders list on both local and remote hosts.

Generic File Operations with IFilesystemProvider

For Superset or custom configs, use the filesystem provider methods:

import { IFilesystemProvider } from '@/main/ipc/filesystem-provider';
import { join } from 'path';

export async function addSupersetEntry(
  fs: IFilesystemProvider,
  repoRoot: string,
  extension: string,
  apps: string[]
) {
  const cfgPath = join(repoRoot, '.superset', 'config.json');
  
  let cfg: Record<string, unknown> = {};
  try {
    const raw = await fs.readFile(cfgPath, 'utf-8');
    cfg = JSON.parse(raw);
  } catch {
    // File missing or malformed – start fresh
  }
  
  (cfg as any).openIn = (cfg as any).openIn || {};
  (cfg as any).openIn[extension] = apps;
  
  await fs.createDir(join(repoRoot, '.superset'));
  await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
}

This pattern mirrors the test implementation in [src/shared/setup-script-imports.test.ts](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.test.ts#L12-L35).

Summary

• Orca uses JSON configs: Global settings live in ~/.copilot/config.json, while project-specific UI rules reside in <repo>/.superset/config.json.
• Remote support: The markRemoteCopilotFolderTrusted function in orca-runtime.ts ensures configs sync to remote SSH worktrees.
• Abstraction layer: Always use IFilesystemProvider for programmatic access to support both local and remote filesystems transparently.
• Safe editing: Validate JSON before parsing, use createDir before writing, and pretty-print with 2-space indentation to match Orca's formatting.

Frequently Asked Questions

Where does Orca store its global configuration files?

Orca stores global user preferences in ~/.copilot/config.json inside your home directory. For remote worktrees accessed via SSH, it creates a parallel .copilot folder in the remote user's home directory to maintain consistent trust and telemetry settings across environments.

Can I edit Orca's configuration files while the application is running?

Yes. Orca reads these JSON files on-demand rather than holding persistent locks. However, programmatic modifications should use the IFilesystemProvider interface to ensure atomic writes and proper directory creation, as demonstrated in src/main/runtime/orca-runtime.ts.

How do I programmatically mark a folder as trusted in Orca?

Use the markRemoteCopilotFolderTrusted method available in the Orca runtime, which handles the read-modify-write cycle safely. Alternatively, manually append the absolute path to the trustedFolders array in ~/.copilot/config.json and ensure valid JSON syntax.

What is the difference between Copilot config and Superset config?

The Copilot config (~/.copilot/config.json) contains global user settings like telemetry preferences and trusted worktrees. The Superset config (<repo>/.superset/config.json) is project-local and defines repository-specific UI behaviors, such as which external applications appear in the "open-in" context menu for specific file extensions.

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