CLEO Nexus Guide

Cross-project intelligence for the global task graph

CLEO Nexus

Nexus is CLEO’s global intelligence system - a “super brain” that spans all your registered projects, enabling cross-project relationship discovery and unified dependency analysis.

Quick Start

Initialize Nexus

cleo nexus init

Creates ~/.cleo/nexus/ directory structure with global registry.

Register Projects

# Register with read-only access (default)
cleo nexus register /path/to/project-a --name my-app

# Register with write access
cleo nexus register /path/to/project-b --name api --permissions write

# Register with full access
cleo nexus register /path/to/project-c --name infra --permissions execute

List Registered Projects

# List all projects
cleo nexus list

# JSON output
cleo nexus list --json

Cross-Project Queries

Query Syntax

Use project:task_id format to reference tasks across projects:

Syntax	Meaning	Example
my-app:T001	Task T001 in project “my-app”	Specific project reference
.:T001	Task T001 in current project	Explicit current project
*:T001	Search T001 in all projects	Wildcard search
T001	Implicit current project	Standard single-project syntax

The project:task_id syntax works in any CLEO command that accepts task IDs.

Discover Related Tasks

Find related tasks across all registered projects:

# Find tasks related to my-app:T001
cleo nexus discover my-app:T001

# Limit results to top 5
cleo nexus discover my-app:T001 --limit 5

# Use specific discovery method
cleo nexus discover my-app:T001 --method labels

# Output as JSON
cleo nexus discover my-app:T001 --json

Discovery methods:

• labels - Match by shared labels/topics
• description - Match by description keywords
• hierarchy - Match by tree proximity
• auto - Combine all methods (default)

Cross-Project Dependencies

Analyze dependencies that span project boundaries:

# Show what a task depends on
cleo nexus deps my-app:T001

# Show what depends on this task (reverse lookup)
cleo nexus deps my-app:T001 --reverse

# Include transitive dependencies
cleo nexus deps my-app:T001 --transitive

Permission Model

Three-tier permissions control cross-project access:

Level	Numeric	Capabilities
read	1	Query tasks, discover relationships
write	2	read + modify task fields, add relationships
execute	3	write + create/delete tasks, run commands

Permissions are hierarchical: execute includes write and read capabilities.

Permission Examples

# Update permissions for existing project
cleo nexus register /path/to/project --name api --permissions write

# Check if operation is allowed (exit codes)
# 0 = allowed, 72 = E_NEXUS_PERMISSION_DENIED
cleo nexus query api:T001 --require-write

Same-Project Exception

Operations within the current project always have full permissions, regardless of how it’s registered in Nexus. This preserves backward compatibility with single-project workflows.

Neural Brain Concepts

Nexus implements neural network semantics designed for AI agents:

Concept	Implementation	Purpose
Neurons	Tasks (across all projects)	Units of work
Synapses	Relationships (relates field)	Connections
Weights	Similarity scores + boosts	Relevance
Activation	Score threshold (0.0-1.0)	Filtering
Memory	Persistent global graph	Context

For Autonomous Agents

Nexus enables autonomous AI agents to:

1. Self-navigate - Query related tasks without human guidance
2. Persist memory - State survives across sessions
3. Cross-reference - Connect work across projects
4. Discover context - Find relevant prior work automatically

Agent Discovery

# Agent queries for related work
cleo nexus discover ".:T001" --method auto --limit 10

# Returns related tasks from all registered projects
# Agent can follow relationships autonomously

Discovery Algorithms

Label Matching

Scores tasks by shared labels/topics:

• 3+ shared labels: 0.9+ score
• 2 shared labels: 0.7-0.9 score
• 1 shared label: 0.5-0.7 score

Boosts: parent tasks +0.1, blocking tasks +0.15

Description NLP

Keyword extraction and matching:

• Filters common words (the, a, is, etc.)
• Scores by shared keywords
• Weighted by keyword rarity

Best for semantic similarity

Hierarchy

Tree structure proximity:

• Same epic: 0.8+ score
• Sibling tasks: 0.7+ score
• Cousin tasks: 0.5+ score

Best for project structure

Auto (Default)

Combines all methods:

• Weighted average of all scores
• Deduplicates results
• Sorts by combined relevance

Most comprehensive

Syncing Metadata

Keep project metadata up-to-date:

# Sync single project
cleo nexus sync my-app

# Sync all registered projects
cleo nexus sync

# Force full resync (ignores checksums)
cleo nexus sync --force

Nexus caches task metadata locally. Run sync after significant project changes.

Unregister Projects

# Remove project from registry
cleo nexus unregister my-app

# Confirm removal
cleo nexus list

Troubleshooting

Exit Codes

Code	Constant	Meaning	Fix
70	E_NEXUS_NOT_INITIALIZED	Nexus not set up	Run cleo nexus init
71	E_NEXUS_PROJECT_NOT_FOUND	Project not registered	Check cleo nexus list
72	E_NEXUS_PERMISSION_DENIED	Insufficient permissions	Update project permissions
73	E_NEXUS_INVALID_SYNTAX	Invalid query format	Use project:task_id format

Common Issues

Project not found

Error: E_NEXUS_PROJECT_NOT_FOUND

Cause: Project name not in registry

Fix:

# List registered projects
cleo nexus list

# Register if missing
cleo nexus register /path/to/project --name correct-name

Permission denied

Error: E_NEXUS_PERMISSION_DENIED

Cause: Operation requires higher permission level

Fix:

# Update permissions
cleo nexus register /path/to/project --name api --permissions write

Invalid syntax

Error: E_NEXUS_INVALID_SYNTAX

Cause: Query format not recognized

Valid formats:

• project:T001 - Named project
• .:T001 - Current project
• *:T001 - All projects
• T001 - Implicit current

Invalid:

• project T001 (no colon)
• project::T001 (double colon)
• :T001 (empty project)

Stale metadata

Symptom: Discovery returns outdated results

Cause: Metadata cache out of sync

Fix:

# Force sync all projects
cleo nexus sync --force

Example Workflow

1. Initialize Nexus

   cleo nexus init
   

   Creates global registry at ~/.cleo/nexus/registry.json

2. Register Projects

   # Backend API (read-only)
   cleo nexus register ~/projects/backend --name backend
   
   # Frontend (write access)
   cleo nexus register ~/projects/frontend --name frontend --permissions write
   
   # Infrastructure (full access)
   cleo nexus register ~/projects/infra --name infra --permissions execute
   
3. Discover Relationships

   # Working in backend project
   cd ~/projects/backend
   
   # Find related tasks across all projects
   cleo nexus discover .:T001
   
   # Discovers frontend:T042 mentions same API endpoint
   
4. Check Dependencies

   # See what frontend task depends on
   cleo nexus deps frontend:T042
   
   # Shows: depends on backend:T001
   
5. Sync Regularly

   # After major changes
   cleo nexus sync
   
   # Keeps discovery accurate
   

Advanced Usage

Integration with CLI Commands

Cross-project syntax works throughout CLEO:

# Show task from other project
cleo show api:T001

# Update task in other project (requires write permission)
cleo update api:T001 --notes "Updated from frontend"

# Create dependency on other project
cleo update .:T042 --depends api:T001

# List tasks from other project
cleo list --project api

Scripting with Nexus

#!/usr/bin/env bash

# Find all blocking tasks across projects
cleo nexus list --json | jq -r '.projects[].name' | while read -r project; do
    cleo nexus deps "${project}:*" --json | jq -r '.blockers[]'
done

# Sync all projects before analysis
cleo nexus sync

# Run discovery for current task
current_task=$(cleo focus show --json | jq -r '.taskId')
cleo nexus discover ".:${current_task}" --limit 10

Next Steps

Sessions Guide

Learn session management across projects

Architecture

Understand CLEO’s system design

Multi-Agent Setup

Configure for multiple AI agents

Vision

See CLEO’s design philosophy