Global Profiles

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• CONTRIBUTING.md
• packages/cli/src/commands/profile/index.ts
• packages/cli/src/profile/manager.ts
• packages/cli/src/profile/paths.ts
• packages/cli/src/profile/schema.ts

The Global Profile system in OCX is a specialized configuration management framework that allows users to maintain portable, isolated OpenCode environments. It enables developers to work across multiple repositories without modifying project-specific files, keeping configurations for different contexts (e.g., work, personal, specific clients) entirely separate. This system provides a way to inject custom instructions, MCP servers, and plugins into any project directory through a global configuration overlay.

Sources: AGENTS.md:275-278, README.md:14-15, README.md:103-106

Architecture and Configuration Storage

Profiles are stored globally within the user's config directory, typically located at ~/.config/opencode/. This centralized storage ensures that profiles are accessible regardless of the current working directory.

Directory Structure

~/.config/opencode/
├── ocx.jsonc                 # Global base config
└── profiles/
    ├── default/              # Default fallback profile
    │   ├── ocx.jsonc         # Profile-specific OCX settings
    │   ├── opencode.jsonc    # Profile-specific OpenCode config
    │   └── AGENTS.md         # Profile-specific instructions
    └── [profile-name]/       # Named custom profiles
        ├── ocx.jsonc
        ├── opencode.jsonc
        └── AGENTS.md

Sources: AGENTS.md:290-302, README.md:120-132

Configuration Components

Each profile directory contains three primary files that define the environment:

File	Purpose
ocx.jsonc	Defines registries, component installation paths, and include/exclude glob patterns for project files.
opencode.jsonc	Contains the actual OpenCode configuration (model settings, agents, MCP servers).
AGENTS.md	Provides the system instructions that the AI agent will follow when the profile is active.

Sources: AGENTS.md:290-302, README.md:162-166

Profile Resolution and Merging

OCX employs a specific priority order to determine which profile is active and how configurations are merged before launching an OpenCode session.

Resolution Priority

When a command is executed, OCX resolves the active profile using the following hierarchy:

1. Explicit Flag: --profile <name> or -p <name> passed to the CLI.
2. Environment Variable: The OCX_PROFILE variable.
3. Default Profile: The profile named default if it exists in the global config directory.
4. No Profile: Fallback to base global configs only.

Sources: AGENTS.md:304-309, README.md:134-139

Configuration Cascade

The final configuration is built by merging multiple sources in a specific sequence, where later sources override earlier ones:

The diagram shows the sequence of configuration merging, where project-local files are only merged if they are not explicitly excluded by the profile's patterns.
Sources: AGENTS.md:311-318, README.md:154-156

Instruction File Discovery and Visibility

A key feature of the profile system is its ability to control which instruction files (like AGENTS.md or CLAUDE.md) are visible to the AI. By default, profiles isolate the environment by excluding project-level instructions.

Include/Exclude Logic

Profiles use a TypeScript/Vite-style glob pattern system. Include patterns override exclude patterns, allowing for granular control over which project files the AI can "see."

{
  "exclude": [
    "**/CLAUDE.md",
    "**/CONTEXT.md",
    "**/.opencode/**",
    "**/opencode.jsonc"
  ],
  "include": [
    "**/AGENTS.md"
  ]
}

Sources: AGENTS.md:337-347, README.md:200-217

CLI Management Commands

The ocx CLI provides a dedicated suite of commands for managing the lifecycle of global profiles.

Profile Lifecycle Commands

Command	Alias	Description
ocx profile list	ocx p ls	Lists all discovered global profiles.
ocx profile add <name>	ocx p add	Creates a new profile directory and boilerplate.
ocx profile remove <name>	ocx p rm	Deletes a profile and its associated files.
ocx profile show <name>	ocx p show	Displays the current content of a profile's config.
ocx profile config <name>	ocx p config	Opens the profile's ocx.jsonc in the default editor.

Sources: AGENTS.md:364-372, README.md:143-149

Execution Flow

The following sequence diagram illustrates how OCX initializes a session using the profile system:

This diagram depicts the internal logic for resolving, merging, and launching an OpenCode environment via the profile system.
Sources: AGENTS.md:320-329, README.md:154-156

Developer and Testing Integration

For developers contributing to OCX or testing new features, the profile system provides a safe, non-destructive testing environment.

Isolated Testing

Developers are encouraged to use an ocx-dev profile for manual and AI-driven testing. This prevents the development process from polluting the user's primary configuration or the project's source code.
Sources: CONTRIBUTING.md:104-110

Custom Binaries

Profiles can be configured to use specific OpenCode binaries, which is useful for testing forks or unreleased versions. This is configured via the bin field in ocx.jsonc or the OPENCODE_BIN environment variable.
Sources: AGENTS.md:349-357, CONTRIBUTING.md:142-146

Summary

Global Profiles transform OCX from a simple project-level manager into a portable development environment. By leveraging global storage, hierarchical resolution, and glob-based file visibility, the system ensures that developers can maintain consistent AI behaviors and toolsets across diverse repositories while keeping project-specific modifications to a minimum.