Ghost Utilities
Relevant source files
The following files were used as context for generating this wiki page:
Ghost Utilities represent a temporary command group within the OCX CLI designed to facilitate the migration of legacy "ghost mode" configurations to the unified profile system. This module serves as a bridge for users transitioning from the older ghost.jsonc format to the modern ocx.jsonc configuration structure used by global profiles.
The utility is strictly scoped to profile management and is intended for removal in subsequent minor versions once the transition period is complete. It ensures that user settings, such as custom binary paths and registry configurations, are preserved during the shift to the new architecture.
Sources: AGENTS.md:329-335, packages/cli/tests/ghost-migrate.test.ts:4-7
Architecture and Migration Logic
The core functionality of Ghost Utilities is centered around the ghost migrate command. This command scans the global profiles directory for legacy configuration files and transforms them into the current standard.
Migration Flow
The migration process follows a "Safety First" approach, utilizing backups and conflict checks to prevent data loss. The logic identifies the profiles directory (typically located in ~/.config/opencode/profiles/) and iterates through each subdirectory representing a profile.
The migration logic ensures that if an ocx.jsonc file already exists, the profile is skipped to avoid overwriting existing modern configurations.
Sources: packages/cli/tests/ghost-migrate.test.ts:133-145, AGENTS.md:331-333
Ghost Mode vs. Profile System
The migration specifically targets the transition from a single "ghost" configuration to a multi-profile environment where each profile resides in its own directory.
| Feature | Legacy (Ghost Mode) | Modern (Profile System) |
|---|---|---|
| Config File | ghost.jsonc | ocx.jsonc |
| Location | Profile root directory | Profile root directory |
| Discovery | Single context | Multi-profile resolution priority |
| Command Group | ghost | profile |
Sources: AGENTS.md:215-225, packages/cli/tests/ghost-migrate.test.ts:74-85
Command Reference
The ghost command group contains utilities specifically for the migration phase.
CLI Commands
| Command | Options | Description |
|---|---|---|
ocx ghost migrate | None | Executes the migration of ghost.jsonc to ocx.jsonc across all profiles. |
ocx ghost migrate | --dry-run | Previews the migration actions (scanning and conflict detection) without modifying the filesystem. |
Dry-Run Execution
The --dry-run flag is a critical safety feature. It simulates the migration by identifying which profiles contain ghost.jsonc, checking for existing ocx.jsonc conflicts, and reporting what would happen. No files are renamed, and no backup files (.bak) are created during a dry run.
Sources: packages/cli/tests/ghost-migrate.test.ts:109-120, AGENTS.md:331-332
Profile Sanitization
Beyond file renaming, the Ghost Utilities handle the cleanup of legacy structural artifacts.
Symlink Management
In older versions of the CLI, a symlink named current was used within the profiles directory to point to the active profile. The migration utility automatically detects and removes this symlink to align with the new resolution strategy (flag > environment variable > default profile).
Idempotency and Safety
The utility is designed to be idempotent. Running ocx ghost migrate multiple times will not cause issues:
- Second Run: If all files have been migrated, the tool reports "Nothing to migrate".
- Backup Persistence: If a migration was interrupted and a
.bakfile remains, the tool will skip that profile to prevent overwriting potentially corrupted data. - Content Preservation: The content of the JSONC files is preserved exactly; only the filename changes.
Sources: packages/cli/tests/ghost-migrate.test.ts:266-278, packages/cli/tests/ghost-migrate.test.ts:340-350
Conclusion
Ghost Utilities provide a narrow but essential bridge for the OCX ecosystem's evolution. By automating the transition from ghost.jsonc to the profile-based ocx.jsonc, it ensures that users can move to the newer, more flexible configuration cascade without losing their established settings. This module is temporary and serves primarily as a maintenance tool for existing installations.