Plugins & System Hooks
Relevant source files
The following files were used as context for generating this wiki page:
CCS implements a robust plugin and hook architecture designed to synchronize and manage extensions, skills, and environment configurations across multiple provider runtimes. The system ensures that shared resources—such as custom commands, agents, and marketplace plugins—are consistently available in both global and instance-local contexts through advanced symlink management and metadata normalization.
The architecture relies on a SharedManager to handle the lifecycle of these extensions, maintaining a "Shared" directory structure that acts as a single source of truth for Claude Code, Codex, and other compatible CLIs.
Plugin Architecture & Lifecycle
The plugin system is centered around the management of installed plugins and their associated marketplaces. CCS manages these through physical file synchronization and registry reconciliation.
Plugin Management Flow
The SharedManager handles the discovery of marketplace entries and ensures that instance-local registries (known_marketplaces.json) point to the correct authoritative install locations.
The diagram shows the logical flow for reconciling plugin marketplaces and ensuring registry integrity during instance initialization.
Sources: src/management/shared-manager.ts:315-370, tests/unit/shared-manager.test.ts:250-320
Metadata Normalization
A critical component of the plugin system is the plugin-path-normalizer. This utility ensures that when plugins are shared between different environments (e.g., from a global .ccs/shared to an instance-local .ccs/instances/work), all internal file paths in JSON metadata are rewritten to match the target environment.
| Component | Responsibility |
|---|---|
normalizePluginMetadataPathString | Rewrites a single absolute path string to be relative to the target config directory. |
normalizePluginMetadataContent | Scans entire JSON strings to find and replace all path-like strings associated with plugin cache or marketplaces. |
SharedManager.normalizeMarketplaceRegistryPaths | Self-heals missing installLocation fields and prunes registry entries lacking a physical directory. |
Sources: src/management/plugin-path-normalizer.ts:5-40, src/management/shared-manager.ts:340-360
System Hooks & Shared Resources
CCS utilizes "System Hooks" primarily through symlinks and configuration injections that allow shared resources to be "hooked" into active provider sessions.
Shared Resource Categories
The system categorizes shared resources into five primary types, visible and manageable via the Dashboard UI:
- Commands: Custom markdown-based workflow commands.
- Skills: Extension directories containing functional definitions (typically including a
SKILL.md). - Agents: Custom agent prompts and configuration files.
- Plugins: Installed marketplace extensions.
- Settings: The
settings.jsonfile which can include system-level hooks likePreToolUse.
Sources: ui/src/pages/shared.tsx:50-80, tests/unit/web-server/shared-routes.test.ts:80-150
Symlink Lifecycle & Circular Protection
The SharedManager implements safeguards to prevent circular symlink chains between the project's shared directory and the target runtime's configuration directories (e.g., ~/.claude).
This sequence illustrates the validation process performed by the SharedManager to ensure resource integrity while preventing filesystem loops.
Sources: src/management/shared-manager.ts:180-220, tests/unit/shared-manager.test.ts:180-230
Implementation Details
Codex Hooks & Feature Flags
For the Codex provider, hooks and system behaviors are managed via structured TOML configuration. The system exposes granular controls for feature flags that modify the runtime environment.
| Feature Flag | Description |
|---|---|
multi_agent | Enables parallel agent execution. |
shell_snapshot | Captures terminal state for context. |
runtime_metrics | Collects execution performance data. |
smart_approvals | Automates tool approval based on trust levels. |
Sources: src/web-server/services/codex-dashboard-service.ts:40-60, tests/unit/web-server/codex-dashboard-service.test.ts:80-100
Path Resolution
The system uses a fallback mechanism for resolving the shared resource directories, respecting environment variable overrides:
CLAUDE_CONFIG_DIR: Explicitly set directory for Claude-compatible resources.CCS_HOME: Base directory for all CCS data.~/.claude: Default system fallback.
Sources: tests/unit/web-server/shared-routes.test.ts:390-410, src/web-server/services/codex-dashboard-service.ts:250-265
Summary
The Plugins & System Hooks module provides a unified synchronization layer. By combining a centralized manager (SharedManager) with metadata path normalization and automated symlink reconciliation, CCS allows users to maintain a portable set of skills, agents, and plugins that work across different provider profiles and CLI runtimes without manual configuration thrash.
Sources: src/management/shared-manager.ts:10-50, ui/src/pages/shared.tsx:100-120