// Pattern 1: Facade (recommended for most use cases)
import { Cleo } from '@cleocode/core';
const cleo = await Cleo.init('./project');

// Pattern 2: Namespace access
import { tasks, sessions, memory, orchestration } from '@cleocode/core';

// Pattern 3: Direct function imports (tree-shakeable)
import { addTask, startSession, observeBrain } from '@cleocode/core';

The Cleo Facade

The Cleo class provides a unified interface to all CLEO functionality:

import { Cleo } from '@cleocode/core';

// Initialize CLEO for a project
const cleo = await Cleo.init('./my-project', {
  configPath: './.cleo/config.yaml',
  logLevel: 'info'
});

// Task operations
await cleo.tasks.add({ title: 'New task', priority: 'high' });
const task = await cleo.tasks.show('T1234');
await cleo.tasks.complete('T1234');

// Session operations
const session = await cleo.sessions.start({ scope: 'feature-branch' });
await cleo.sessions.end(session.id);

// Memory operations
await cleo.memory.observe({ topic: 'architecture', content: '...' });
const entries = await cleo.memory.search('auth pattern');

// Cleanup
await cleo.destroy();

Namespaces

All functionality is organized into namespaces:

Namespace	Purpose
`tasks`	Task CRUD, dependencies, archival
`sessions`	Session lifecycle, context, checkpoints
`memory`	Brain storage, search, observation
`orchestration`	Multi-agent coordination, waves, consensus
`lifecycle`	Pipeline stages, gates, compliance
`compliance`	Protocol enforcement, validation rules
`codebaseMap`	Project structure analysis
`phases`	Phase management and transitions
`release`	Release management, versioning
`research`	Research workflows, web extraction
`skills`	Skill management and execution
`sticky`	Ephemeral notes and context
`validation`	Task validation and verification
`nexus`	Multi-project sync and sharing
`adrs`	Architecture Decision Records
`admin`	Administrative operations
`caamp`	Context-aware agent memory protocol
`context`	Context management and injection
`inject`	Context injection utilities
`issue`	Issue tracking integration
`metrics`	Performance metrics and analytics
`migration`	Database migrations
`observability`	Logging, monitoring, tracing
`otel`	OpenTelemetry integration
`pipeline`	Pipeline execution
`reconciliation`	Task sync and reconciliation
`remote`	Remote operations
`roadmap`	Roadmap planning
`routing`	Request routing
`security`	Security utilities
`sequence`	Task sequencing
`signaldock`	Signal handling
`snapshot`	Project snapshots
`spawn`	Subagent spawning
`stats`	Statistics and reporting
`system`	System operations
`taskWork`	Active task tracking
`templates`	Template management
`ui`	UI utilities

Task Operations

import { tasks, addTask, listTasks, completeTask, updateTask, deleteTask } from '@cleocode/core';

// Create a task
const task = await addTask({
  title: 'Implement user authentication',
  description: 'Add JWT-based auth',
  priority: 'high',
  type: 'feature',
  size: 'medium',
  labels: ['backend', 'security']
});

// List tasks
const allTasks = await listTasks({ status: ['pending', 'in_progress'] });

// Update a task
await updateTask('T1234', { priority: 'urgent', labels: ['backend', 'security', 'urgent'] });

// Complete a task
await completeTask('T1234', { notes: 'Implemented with bcrypt and JWT' });

// Delete a task
await deleteTask('T1234');

// Using namespace
await tasks.add({ title: 'Another task' });
await tasks.archive(['T1234', 'T1235']);

Session Operations

import { sessions, startSession, endSession, listSessions, resumeSession } from '@cleocode/core';

// Start a session
const session = await startSession({
  scope: 'feature/authentication',
  notes: 'Working on auth system'
});

// List active sessions
const activeSessions = await listSessions({ status: 'active' });

// Resume a session
await resumeSession(session.id);

// End a session
await endSession(session.id, { summary: 'Completed auth implementation' });

Memory Operations

import { memory, observeBrain, searchBrain, searchBrainCompact, timelineBrain, fetchBrainEntries } from '@cleocode/core';

// Observe (store) a memory
await observeBrain({
  topic: 'authentication-pattern',
  content: 'Using JWT with refresh tokens',
  tags: ['auth', 'pattern'],
  confidence: 0.95
});

// Search memories
const results = await searchBrain('authentication', { limit: 10 });

// Compact search (lightweight)
const compact = await searchBrainCompact('auth', { maxResults: 5 });

// Timeline view
const timeline = await timelineBrain({ from: '2026-01-01', to: '2026-03-01' });

// Fetch specific entries
const entries = await fetchBrainEntries(['entry-1', 'entry-2']);

Orchestration

import { orchestration } from '@cleocode/core';

// Analyze dependencies
const analysis = await orchestration.analyze({
  taskIds: ['T1234', 'T1235', 'T1236'],
  includeBlocked: true
});

// Execute in waves (parallel where possible)
const waves = await orchestration.waves({
  taskIds: ['T1234', 'T1235', 'T1236', 'T1237'],
  maxParallel: 3
});

// Bootstrap orchestration
await orchestration.bootstrap({
  projectPath: './my-project',
  config: { autoSpawn: true }
});

// Validate spawn context
const validation = await orchestration.validateSpawn({
  taskId: 'T1234',
  context: { memoryBudget: 100000 }
});

Compliance & Validation

import { compliance, validation } from '@cleocode/core';

// Check compliance
const report = await compliance.check({
  taskId: 'T1234',
  rules: ['has-description', 'has-acceptance-criteria']
});

// Validate task structure
const result = await validation.validateTask({
  taskId: 'T1234',
  schema: 'standard'
});

Configuration

import { loadConfig, getConfigValue, setConfigValue, getRawConfig } from '@cleocode/core';

// Load configuration
const config = await loadConfig();

// Get a config value
const logLevel = getConfigValue('logging.level');

// Set a config value
await setConfigValue('logging.level', 'debug');

Paths & Project Info

import { 
  getProjectRoot, 
  getCleoDir, 
  isProjectInitialized,
  getProjectInfo,
  resolveProjectPath
} from '@cleocode/core';

// Get project root
const root = getProjectRoot();

// Get .cleo directory
const cleoDir = getCleoDir();

// Check if initialized
if (isProjectInitialized()) {
  const info = await getProjectInfo();
  console.log(`Project: ${info.name}`);
}

Logging

import { getLogger, initLogger, closeLogger } from '@cleocode/core';

// Initialize logger
initLogger('./.cleo', {
  level: 'info',
  filePath: 'logs/cleo.log'
});

// Get logger instance
const logger = getLogger('my-module');
logger.info('Starting operation');
logger.debug({ taskId: 'T1234' }, 'Task details');

// Cleanup
closeLogger();

Hooks

import { hooks, HookRegistry } from '@cleocode/core';

// Register a hook
hooks.register('onTaskCreate', async (context) => {
  console.log(`Task created: ${context.taskId}`);
});

// Dispatch a hook
await hooks.dispatch('onTaskCreate', { taskId: 'T1234' });

Output Formatting

import { formatOutput, formatSuccess, formatError, pushWarning } from '@cleocode/core';

// Format successful response
const success = formatSuccess({ taskId: 'T1234', title: 'My Task' });

// Format error response
const error = formatError('E_TASK_NOT_FOUND', { taskId: 'T1234' });

// Add warning
pushWarning('Task is overdue');

Pagination

import { paginate, createPage } from '@cleocode/core';

// Paginate results
const page = paginate(allTasks, { page: 1, limit: 20 });

// Create a page object
const pageObj = createPage({
  items: tasks,
  total: 100,
  page: 1,
  limit: 20
});

Error Handling

import { CleoError, getErrorDefinition, ERROR_CATALOG } from '@cleocode/core';

// Throw CLEO error
throw new CleoError('E_TASK_NOT_FOUND', { taskId: 'T1234' });

// Get error definition
const def = getErrorDefinition('E_TASK_NOT_FOUND');
console.log(def.message); // "Task not found"

Platform Utilities

import { 
  getSystemInfo, 
  detectPlatform, 
  getIsoTimestamp,
  sha256,
  PLATFORM
} from '@cleocode/core';

// Get system information
const info = getSystemInfo();
console.log(info.platform, info.arch, info.nodeVersion);

// Current platform
const platform = detectPlatform();

// ISO timestamp
const timestamp = getIsoTimestamp();

// Hash
const hash = sha256('content to hash');

Migration

import { 
  runMigration, 
  runAllMigrations, 
  getMigrationStatus,
  compareSemver,
  detectVersion
} from '@cleocode/core';

// Run a specific migration
await runMigration('v2.0.0');

// Run all pending migrations
await runAllMigrations();

// Check migration status
const status = await getMigrationStatus();

Store / Data Accessor

import { createDataAccessor, getAccessor } from '@cleocode/core';

// Create data accessor for a project
const accessor = createDataAccessor('./my-project');

// Get global accessor
const globalAccessor = getAccessor();

// Use accessor
const tasks = await accessor.queryTasks({ status: ['pending'] });
await accessor.updateTask('T1234', { status: 'completed' });

Usage Examples

Complete Workflow Example

import { Cleo } from '@cleocode/core';

async function main() {
  // Initialize CLEO
  const cleo = await Cleo.init('./my-project');
  
  try {
    // Create tasks for a feature
    const epic = await cleo.tasks.add({
      title: 'User Authentication System',
      type: 'epic',
      priority: 'high'
    });
    
    const task1 = await cleo.tasks.add({
      title: 'Implement login endpoint',
      parentId: epic.id,
      type: 'task',
      priority: 'high'
    });
    
    const task2 = await cleo.tasks.add({
      title: 'Add password hashing',
      parentId: epic.id,
      type: 'task',
      priority: 'high',
      dependsOn: [task1.id]
    });
    
    // Start a session
    const session = await cleo.sessions.start({
      scope: 'auth-feature',
      notes: 'Implementing authentication'
    });
    
    // Store architectural decision
    await cleo.memory.observe({
      topic: 'auth-architecture',
      content: 'Using bcrypt for password hashing with cost factor 12',
      tags: ['architecture', 'security', 'auth'],
      confidence: 0.95
    });
    
    // Complete work
    await cleo.tasks.start(task1.id);
    await cleo.tasks.complete(task1.id);
    
    // End session
    await cleo.sessions.end(session.id, {
      summary: 'Completed login endpoint'
    });
    
  } finally {
    await cleo.destroy();
  }
}

main().catch(console.error);

Working with Dependencies

import { tasks, orchestration } from '@cleocode/core';

async function manageDependencies() {
  // Add tasks with dependencies
  const backend = await tasks.add({ title: 'Backend API' });
  const frontend = await tasks.add({ 
    title: 'Frontend UI',
    dependsOn: [backend.id]
  });
  const tests = await tasks.add({
    title: 'Integration Tests',
    dependsOn: [backend.id, frontend.id]
  });
  
  // Analyze dependency tree
  const analysis = await orchestration.analyze({
    taskIds: [backend.id, frontend.id, tests.id]
  });
  
  // Get execution order
  console.log('Execution order:', analysis.sequence);
  
  // Find blocked tasks
  console.log('Blocked:', analysis.blocked);
}

Memory Bridge Example

import { memory } from '@cleocode/core';

async function buildKnowledge() {
  // Store observations
  await memory.observe({
    topic: 'database-choice',
    content: 'Selected PostgreSQL over MongoDB for ACID compliance',
    tags: ['database', 'decision'],
    confidence: 0.9
  });
  
  await memory.observe({
    topic: 'api-design',
    content: 'RESTful API with OpenAPI 3.0 spec',
    tags: ['api', 'design'],
    confidence: 0.95
  });
  
  // Search for patterns
  const results = await memory.search('database', { 
    tags: ['decision'],
    limit: 5 
  });
  
  // Build context for AI
  const context = results.map(r => ({
    topic: r.topic,
    content: r.content,
    confidence: r.confidence
  }));
}

Dependencies

Production Dependencies

@cleocode/contracts - Type definitions
@cleocode/caamp - Context-aware agent memory protocol
@cleocode/lafs-protocol - Language-agnostic feedback schema
drizzle-orm - Database ORM
zod - Schema validation
pino - Logging
yaml - YAML parsing
ajv - JSON Schema validation
And more...

Development Dependencies

typescript - Type checking
vitest - Testing framework
@types/* - Type definitions

License

MIT License - see LICENSE for details.

FAQs

What is @cleocode/core?

Is @cleocode/core popular?

Is @cleocode/core well maintained?

Package last updated on 20 Mar 2026

@cleocode/core