kryptobaseddev/SKILL-monorepo

@cleocode/monorepo

CLEO provider adapter for Anthropic Claude Code CLI. Default export is the adapter class for dynamic loading by AdapterManager. T5240

Quick Start

npm install @cleocode/monorepo

import { checkStatuslineIntegration } from './statusline.js';

const status = checkStatuslineIntegration();
if (status === 'not_configured') {
  console.log('Run cleo install to set up context monitoring');
}

API

| Function | Description | |----------|-------------| | checkStatuslineIntegration() | Check if statusline integration is configured. Returns the current integration status. | | getStatuslineConfig() | Get the statusline setup command for Claude Code settings. | | getSetupInstructions() | Get human-readable setup instructions. | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | readLatestTranscript() | Read the most recent JSON or JSONL session file from providerDir and return its contents as a flat transcript string. Files are sorted in descending order by filename — this works naturally for providers that embed timestamps in filenames. The most recently named file is read first. Returns null when: - providerDir does not exist or cannot be read - No JSON/JSONL files are present - The most recent file contains no parseable turns | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | buildOpenCodeAgentMarkdown() | Build the markdown content for an OpenCode agent definition file. OpenCode agents are defined as markdown files with YAML frontmatter in the .opencode/agent/ directory. | | createAdapter() | Factory function for creating adapter instances. Used by AdapterManager's dynamic import fallback. | | getProviderManifests() | Get the manifests for all bundled provider adapters. | | discoverProviders() | Discover all available provider adapters. Returns a map of provider ID to adapter factory function. | | getPlatformPaths() | Get OS-appropriate paths for CAAMP's global directories. | | getSystemInfo() | Get a cached system information snapshot. | | ... | 2500 more — see API reference |

Configuration

import type { DetectionConfig } from "@cleocode/monorepo";

const config: Partial<DetectionConfig> = {
  // Detection methods to try, in order.
  methods: [],
  // Binary name to look up on PATH (for `"binary"` method).
  binary: "...",
  // Directories to check for existence (for `"directory"` method).
  directories: "...",
  // macOS .app bundle name (for `"appBundle"` method).
  appBundle: "...",
  // Flatpak application ID (for `"flatpak"` method).
  flatpakId: "...",
};

See references/CONFIGURATION.md for full details.

Gotchas

• HookEvent is deprecated: Use CanonicalHookEvent from ../hooks/types.js for the normalized CAAMP taxonomy. This type remains for backward compatibility with registry.json's capabilities.hooks.supported string arrays.
• CtSkillEntry is deprecated: Use SkillLibraryEntry instead.
• CtValidationResult is deprecated: Use SkillLibraryValidationResult instead.
• CtValidationIssue is deprecated: Use SkillLibraryValidationIssue instead.
• CtProfileDefinition is deprecated: Use SkillLibraryProfile instead.
• CtDispatchMatrix is deprecated: Use SkillLibraryDispatchMatrix instead.
• CtManifest is deprecated: Use SkillLibraryManifest instead.
• CtManifestSkill is deprecated: Use SkillLibraryManifestSkill instead.
• getTaskPath is deprecated: Use getAccessor() from './store/data-accessor.js' instead. This function returns the database file path for legacy compatibility, but all task data access should go through the DataAccessor interface to ensure proper SQLite interaction. Example: // OLD (deprecated): const taskPath = getTaskPath(cwd); const data = await readJsonFile(taskPath); // NEW (correct): const accessor = await getAccessor(cwd); const data = await accessor.queryTasks();
• getClaudeAgentsDir is deprecated: Use AdapterPathProvider.getAgentInstallDir() from the active adapter instead.
• getClaudeMemDbPath is deprecated: Use AdapterPathProvider.getMemoryDbPath() from the active adapter instead.
• OnSessionStartPayload is deprecated: Use SessionStartPayload instead. Kept for backward compatibility.
• OnSessionEndPayload is deprecated: Use SessionEndPayload instead. Kept for backward compatibility.
• OnToolStartPayload is deprecated: Use PreToolUsePayload instead. Kept for backward compatibility.
• OnToolCompletePayload is deprecated: Use PostToolUsePayload instead. Kept for backward compatibility.
• OnFileChangePayload is deprecated: Use NotificationPayload instead. Kept for backward compatibility.
• OnErrorPayload is deprecated: Use PostToolUseFailurePayload instead. Kept for backward compatibility.
• OnPromptSubmitPayload is deprecated: Use PromptSubmitPayload instead. Kept for backward compatibility.
• OnResponseCompletePayload is deprecated: Use ResponseCompletePayload instead. Kept for backward compatibility.
• AdapterTransportProvider is deprecated: Use Transport instead. Will be removed after unification.
• getRegistryPath is deprecated: Use nexus.db via getNexusDb() instead. Retained for JSON-to-SQLite migration.
• OnSessionStartPayloadSchema is deprecated: Use SessionStartPayloadSchema. Kept for backward compatibility.
• OnSessionEndPayloadSchema is deprecated: Use SessionEndPayloadSchema. Kept for backward compatibility.
• OnToolStartPayloadSchema is deprecated: Use PreToolUsePayloadSchema. Kept for backward compatibility.
• OnToolCompletePayloadSchema is deprecated: Use PostToolUsePayloadSchema. Kept for backward compatibility.
• OnFileChangePayloadSchema is deprecated: Use NotificationPayloadSchema. Kept for backward compatibility.
• OnErrorPayloadSchema is deprecated: Use PostToolUseFailurePayloadSchema. Kept for backward compatibility.
• OnPromptSubmitPayloadSchema is deprecated: Use PromptSubmitPayloadSchema. Kept for backward compatibility.
• OnResponseCompletePayloadSchema is deprecated: Use ResponseCompletePayloadSchema. Kept for backward compatibility.
• Capability is deprecated: Use AgentSkill instead.
• ServiceConfig is deprecated: Use AgentCard instead.
• EndpointConfig is deprecated: Will be removed in v2.0.0.
• DiscoveryDocument is deprecated: Use AgentCard instead.
• resolveProvidersRegistryPath() throws: Error if providers/registry.json cannot be found within 8 parent levels
• ensureProviderInstructionFile() throws: Error if the provider ID is not found in the registry
• ensureAllProviderInstructionFiles() throws: Error if any provider ID is not found in the registry
• resolveFormat() throws: Error if format flags conflict
• readConfig() throws: If the file cannot be read or the format is unsupported
• writeConfig() throws: If the format is unsupported
• removeConfig() throws: If the format is unsupported
• fetchWithTimeout() throws: NetworkError on timeout or network failure
• ensureOkResponse() throws: NetworkError when response.ok is false
• recommendSkills() throws: Error with code and issues properties when criteria are invalid
• loadLibraryFromModule() throws: If the module cannot be loaded or does not implement SkillLibrary
• buildLibraryFromFiles() throws: If skills.json is not found at the root
• registerSkillLibraryFromPath() throws: Error if the library cannot be loaded from the given path
• checkTaskExists() throws: SafetyError if task exists and strict mode is enabled
• verifyTaskWrite() throws: SafetyError if verification fails
• validateStage() throws: Error If stage is invalid
• setEmbeddingProvider() throws: Error if provider dimensions do not match EMBEDDING_DIMENSIONS
• loadAdapterFromManifest() throws: If the module cannot be loaded or does not export a valid adapter
• initializePipeline() throws: CleoError If pipeline already exists or database operation fails
• getPipeline() throws: CleoError If database query fails
• advanceStage() throws: CleoError If transition is invalid or prerequisites not met
• getCurrentStage() throws: CleoError If database query fails
• listPipelines() throws: CleoError If database query fails
• completePipeline() throws: CleoError If pipeline not found or not in releasable state
• cancelPipeline() throws: CleoError If pipeline not found or already completed
• getPipelineStatistics() throws: CleoError If database query fails
• validatePipelineStage() throws: CleoError(VALIDATION_ERROR) if invalid
• validatePipelineTransition() throws: CleoError(VALIDATION_ERROR) if the transition is backward
• validateEpicCreation() throws: CleoError(VALIDATION_ERROR) in strict mode when constraints are violated.
• validateChildStageCeiling() throws: CleoError(VALIDATION_ERROR) in strict mode when the child stage exceeds the epic.
• validateEpicStageAdvancement() throws: CleoError(VALIDATION_ERROR) in strict mode when incomplete children exist.
• assertLafsShape() throws: LafsViolationError if the envelope fails any shape invariant
• bindSession() throws: if a session is already bound (call unbindSession first).
• parseQuery() throws: CleoError with NEXUS_INVALID_SYNTAX for bad format.
• withRetry() throws: The last error thrown by fn, augmented with RetryContext fields (attempts, totalDelayMs).
• formatIsoDate() throws: Error if date format is invalid or missing T4552
• getProjectInfo() throws: Error If .cleo/project-info.json does not exist or is invalid JSON.
• resolveSkillPathsForProvider() throws: Error if provider not found
• decrypt() throws: If decryption fails (wrong key, corrupted data, or machine key mismatch).
• resolveTemplate() throws: Error If a referenced variable is not found in any scope.
• checkPrerequisites() throws: CleoError If validation fails
• validateTransition() throws: CleoError If validation fails unexpectedly
• executeTransition() throws: CleoError If transition is invalid
• setStageStatus() throws: CleoError If status transition is invalid
• skipStage() throws: CleoError If stage cannot be skipped
• resolveOutputFormat() throws: LAFSFlagError When humanFlag and jsonFlag are both truthy.
• assertEnvelope() throws: Error When the input does not conform to the envelope schema.
• assertCompliance() throws: ComplianceError When any compliance stage fails.
• parseLafsResponse() throws: LafsError When the envelope indicates failure (success=false).
• parseLafsResponse() throws: Error When the envelope is structurally invalid or requireRegisteredErrorCode is true and the code is unregistered.
• resolveFieldExtraction() throws: LAFSFlagError When both fieldFlag and fieldsFlag are set.
• resolveFlags() throws: LAFSFlagError When format or field layer flags conflict.
• getErrorCodeMapping() throws: Error if the error type is not a known A2A error type
• ExitCode enum values: SUCCESS, GENERAL_ERROR, INVALID_INPUT, FILE_ERROR, NOT_FOUND, DEPENDENCY_ERROR, VALIDATION_ERROR, LOCK_TIMEOUT, CONFIG_ERROR, PARENT_NOT_FOUND, DEPTH_EXCEEDED, SIBLING_LIMIT, INVALID_PARENT_TYPE, CIRCULAR_REFERENCE, ORPHAN_DETECTED, HAS_CHILDREN, TASK_COMPLETED, CASCADE_FAILED, HAS_DEPENDENTS, CHECKSUM_MISMATCH, CONCURRENT_MODIFICATION, ID_COLLISION, SESSION_EXISTS, SESSION_NOT_FOUND, SCOPE_CONFLICT, SCOPE_INVALID, TASK_NOT_IN_SCOPE, TASK_CLAIMED, SESSION_REQUIRED, SESSION_CLOSE_BLOCKED, ACTIVE_TASK_REQUIRED, NOTES_REQUIRED, VERIFICATION_INIT_FAILED, GATE_UPDATE_FAILED, INVALID_GATE, INVALID_AGENT, MAX_ROUNDS_EXCEEDED, GATE_DEPENDENCY, VERIFICATION_LOCKED, ROUND_MISMATCH, CONTEXT_WARNING, CONTEXT_CAUTION, CONTEXT_CRITICAL, CONTEXT_EMERGENCY, CONTEXT_STALE, PROTOCOL_MISSING, INVALID_RETURN_MESSAGE, MANIFEST_ENTRY_MISSING, SPAWN_VALIDATION_FAILED, AUTONOMOUS_BOUNDARY, HANDOFF_REQUIRED, RESUME_FAILED, CONCURRENT_SESSION, NEXUS_NOT_INITIALIZED, NEXUS_PROJECT_NOT_FOUND, NEXUS_PERMISSION_DENIED, NEXUS_INVALID_SYNTAX, NEXUS_SYNC_FAILED, NEXUS_REGISTRY_CORRUPT, NEXUS_PROJECT_EXISTS, NEXUS_QUERY_FAILED, NEXUS_GRAPH_ERROR, NEXUS_RESERVED, LIFECYCLE_GATE_FAILED, AUDIT_MISSING, CIRCULAR_VALIDATION, LIFECYCLE_TRANSITION_INVALID, PROVENANCE_REQUIRED, ARTIFACT_TYPE_UNKNOWN, ARTIFACT_VALIDATION_FAILED, ARTIFACT_BUILD_FAILED, ARTIFACT_PUBLISH_FAILED, ARTIFACT_ROLLBACK_FAILED, PROVENANCE_CONFIG_INVALID, SIGNING_KEY_MISSING, SIGNATURE_INVALID, DIGEST_MISMATCH, ATTESTATION_INVALID, ADAPTER_NOT_FOUND, ADAPTER_INIT_FAILED, ADAPTER_HOOK_FAILED, ADAPTER_SPAWN_FAILED, ADAPTER_INSTALL_FAILED, NO_DATA, ALREADY_EXISTS, NO_CHANGE, TESTS_SKIPPED, LAFS_VIOLATION
• OrchestrationLevel enum values: HITL, Prime, ProjectLead, TeamLead, Ephemeral
• Severity enum values: Low, Medium, High, Critical
• ManifestIntegrity enum values: Valid, Partial, Invalid, Missing
• InstructionStability enum values: Stable, Clarified, Revised, Unstable
• SessionDegradation enum values: None, Mild, Moderate, Severe
• AgentReliability enum values: High, Medium, Low, Unreliable
• MetricCategory enum values: Compliance, Efficiency, Session, Improvement
• MetricSource enum values: Task, Session, Agent, System, Orchestrator
• AggregationPeriod enum values: Instant, Hourly, Daily, Weekly, Monthly
• ErrorSeverity enum values: INFO, WARNING, ERROR, CRITICAL
• ErrorCategory enum values: GENERAL, HIERARCHY, CONCURRENCY, SESSION, VERIFICATION, CONTEXT, PROTOCOL, NEXUS, LIFECYCLE, SPECIAL
• ProtocolExitCode enum values: SUCCESS, E_GENERAL_ERROR, E_INVALID_INPUT, E_FILE_ERROR, E_NOT_FOUND, E_DEPENDENCY_ERROR, E_VALIDATION_ERROR, E_PARENT_NOT_FOUND, E_DEPTH_EXCEEDED, E_SIBLING_LIMIT, E_CIRCULAR_REFERENCE, E_SESSION_REQUIRED, E_PROTOCOL_RESEARCH, E_PROTOCOL_CONSENSUS, E_PROTOCOL_SPECIFICATION, E_PROTOCOL_DECOMPOSITION, E_PROTOCOL_IMPLEMENTATION, E_PROTOCOL_CONTRIBUTION, E_PROTOCOL_RELEASE, E_PROTOCOL_GENERIC, E_PROTOCOL_VALIDATION, E_TESTS_SKIPPED, E_LIFECYCLE_GATE_FAILED
• ProtocolType enum values: RESEARCH, CONSENSUS, SPECIFICATION, DECOMPOSITION, IMPLEMENTATION, CONTRIBUTION, RELEASE, VALIDATION, TESTING
• GateLayer enum values: SCHEMA, SEMANTIC, REFERENTIAL, PROTOCOL
• GateStatus enum values: PENDING, PASSED, FAILED, BLOCKED, SKIPPED
• WorkflowGateName enum values: IMPLEMENTED, TESTS_PASSED, QA_PASSED, CLEANUP_DONE, SECURITY_PASSED, DOCUMENTED

Key Types

• ClaudeCodePathProvider — Path provider for Anthropic Claude Code CLI. Resolves Claude Code's standard directory layout: - Config dir: ~/.claude (or CLAUDE_HOME) - Settings: ~/.claude/settings.json (or CLAUDE_SETTINGS) - Agents: ~/.claude/agents - Memory DB: ~/.claude-mem/claude-mem.db (or CLAUDE_MEM_DB)
• ClaudeCodeContextMonitorProvider — Context monitor provider for Claude Code. Processes context window JSON from Claude Code and writes state files for statusline display. Also provides statusline configuration and setup instructions specific to Claude Code's settings.json.
• ClaudeCodeHookProvider — Hook provider for Claude Code. Claude Code registers hooks via its global config at ~/.claude/settings.json. Supported handler types: command, http, prompt, agent. Event mapping is based on getProviderHookProfile('claude-code') from CAAMP 1.9.1. Async accessors (getSupportedCanonicalEvents, getProviderProfile) call CAAMP directly when available. Since hooks are registered through the config system (managed by the install provider), registerNativeHooks and unregisterNativeHooks track registration state without performing filesystem operations.
• ClaudeCodeInstallProvider — Install provider for Claude Code. Manages CLEO's integration with Claude Code by: 1. Ensuring CLAUDE.md contains -references to CLEO instruction files 2. Registering the brain observation plugin in ~/.claude/settings.json
• ClaudeCodeSpawnProvider — Spawn provider for Claude Code. Spawns detached Claude CLI processes for subagent execution. Each spawn writes its prompt to a temporary file, then runs claude --allow-insecure --no-upgrade-check <tmpFile> as a detached, unref'd child process.
• ClaudeCodeTaskSyncProvider — Claude Code TaskSyncProvider. Reads Claude's TodoWrite JSON state, parses [T001]-prefixed task IDs and status, and returns normalized ExternalTask[]. Optional: accepts a custom file path for testing.
• ClaudeCodeTransportProvider — Transport provider for Claude Code inter-agent communication.
• ClaudeCodeAdapter — CLEO provider adapter for Anthropic Claude Code CLI. Bridges CLEO's adapter system with Claude Code's native capabilities: - Hooks: Maps Claude Code events (SessionStart, PostToolUse, etc.) to CAAMP events - Spawn: Launches subagent processes via the claude CLI - Install: Manages instruction files and brain observation plugin registration
• CodexHookProvider — Hook provider for Codex CLI. Codex CLI registers hooks via its configuration system at ~/.codex/. Hook handlers are shell commands or script paths that execute when the corresponding event fires. Since hooks are registered through the config system (managed by the install provider), registerNativeHooks and unregisterNativeHooks track registration state without performing filesystem operations.
• CodexInstallProvider — Install provider for Codex CLI. Manages CLEO's integration with Codex CLI by: 1. Ensuring AGENTS.md contains -references to CLEO instruction files

References

• references/CONFIGURATION.md — Full config options
• references/API-REFERENCE.md — Signatures, parameters, examples