Contextually (cxl) -- Claude Code Integration

What is cxl?

cxl is context infrastructure: it captures, assembles, and transfers context across actors and sessions. It indexes your project into a graph and provides token-budgeted context assembly, cursor-based session persistence, and observation-driven learning.

Quick Start

cxl init
cxl assemble --task CMT-0042 --lens agent --json   # context for a work item
cxl assemble src/auth.rs --expand impact --json     # context from seed files

Core Workflow

Starting work

# Get context for a task (auto-creates/resumes cursor)
cxl assemble --task "FIX-042" --lens agent --json

# Or assemble from specific files
cxl assemble src/auth.rs --expand impact --budget 50000 --lens agent --json

During work

cxl observe useful -c <cursor> src/auth.rs     # this file helped
cxl observe missing -c <cursor> "error types"  # needed but not loaded
cxl observe noise -c <cursor> src/old.rs       # this was irrelevant
# Observations automatically improve future assembly ranking

Handing off

cxl handoff <cursor-id> next-agent -m "auth fix in progress, tests passing"
# Produces full context briefing: key files, observations, history

Understanding the codebase

cxl impact src/auth.rs --json        # what breaks if this changes?
cxl depends src/main.rs --json       # what does this need?
cxl why src/a.rs src/b.rs --json     # explain relationship
cxl rank --by centrality --json      # most important files
cxl rank --by churn --json           # most frequently changed

Learning from observations

cxl learn                            # analyze observations locally
cxl learn --publish                  # push signals to global catalog

Key Commands

Command	Purpose
cxl assemble	Token-budgeted context assembly (primary interface)
cxl observe	Record useful/missing/noise signals
cxl handoff	Transfer cursor with full context briefing
cxl status	Index health, active cursors, observations
cxl help-agent --tier N	Progressive discovery (0-3)
cxl impact <node>	Transitive impact analysis
cxl why <a> <b>	Explain relationship between nodes
cxl rank --by centrality	Most important files (PageRank)
cxl learn --publish	Push learning signals to global catalog
cxl catalog search <q>	Cross-project node search

Assembly Lenses

• agent -- XML-tagged context with <system_context>, <context_window>, <graph_context>
• terminal -- Colored markdown for human reading
• roundtrip -- Editable format: ## /path + code fences (use with cxl apply)
• compact -- Minimal token usage

Seed Patterns

Pre-built recipes that auto-match based on task keywords:

• bug-investigation -- Error context + recent changes + tests
• feature-development -- Source files + related tests + docs
• code-review -- Source files + conventions + impact analysis

Patterns resolve hierarchically: cursor -> project -> global catalog -> built-in.

Tips for AI Agents

1. Start with cxl help-agent --tier 0 to orient yourself
2. Use --json flag for structured output you can parse
3. Record observations so future sessions benefit from learning
4. Use --task on assemble to auto-create/resume cursors
5. Check cxl status to see if the index is fresh