lc-context

name

lc-context

description

Use whenever working in a project that has a `.linear_canal_data/` folder — this signals Linear Canal has indexed the codebase. Invoke before any Glob, Grep, or raw file reads. Covers: "how does X work", "where is Y defined", "what files handle Z", explaining architecture, fixing bugs, adding features, or any file edit. The ctx files contain pre-compiled insights — reading them first saves 80-95% of tokens vs raw source exploration. If you see `.linear_canal_data/` in the project root, use this skill first.

Linear Canal — lc-context

Linear Canal has indexed this codebase into pre-compiled .ctx files. Reading them costs 200–800 tokens each instead of the thousands you'd spend walking raw source files.

---

Step 0 — Find the project ID

The project ID is the directory name inside .linear_canal_data/. Find it with:

Bash: ls .linear_canal_data/

All ctx files live at:

.linear_canal_data/<project_id>/ctx/

---

The ctx files

Read these in order — stop when you have enough context.

1. ARCHITECTURE.ctx — always read first

Full module map, entry points, tech stack, file counts per module, deployment notes. Answers most "where does X live" questions without opening a single source file.

Read: .linear_canal_data/<project_id>/ctx/ARCHITECTURE.ctx

2. INTERFACES.ctx — find any exported symbol

Every exported function, class, and method across the codebase, grouped by module. Use when you know the symbol name but not the file.

Read: .linear_canal_data/<project_id>/ctx/INTERFACES.ctx

3. RISKS.ctx — before editing anything

Files flagged for LONG_FUNCTION, SILENT_ERROR, NO_TEST_COVERAGE, STALE_TODO — with exact paths and line numbers. Read this before touching a file so you know what to watch out for.

Read: .linear_canal_data/<project_id>/ctx/RISKS.ctx

4. DEPENDENCIES.ctx — before adding imports

Module dependency graph and breaking-change edges. Read before adding a new import or creating a cross-module dependency.

5. PATTERNS.ctx — before writing new code

Detected design patterns (FACTORY, SINGLETON, MIDDLEWARE, etc.) with the files where they're used. Helps you match the project's conventions.

6. <module>.ctx — deep dive into one module

When ARCHITECTURE.ctx tells you which module to look at, read that module's own ctx file for detailed context: purpose, public interface, risks, full file list.

Read: .linear_canal_data/<project_id>/ctx/<module_name>.ctx

---

Recommended workflow

1. Bash: ls .linear_canal_data/              → get project ID
2. Read ARCHITECTURE.ctx                     → orient (~400 tokens)
3. Identify relevant module(s)
4. Read <module>.ctx                         → deep context (~300 tokens)
5. Read INTERFACES.ctx if you need a symbol  → (~500 tokens)
6. Read RISKS.ctx for any file you'll edit
7. Only then open raw source files — and only the specific ones needed

Total: ~1,500 tokens for full project understanding vs 10,000–50,000 for raw exploration.

---

MCP tools

If the Linear Canal MCP server is running (auto-started via .mcp.json when the plugin is installed, or manually via linear-canal serve), you have three additional tools:

lc_search — semantic search

Searches Qdrant vector collections for natural-language queries.

lc_search("user authentication JWT token validation", limit=5, tier="HIGH")

Use when you need the exact location of a concept and ARCHITECTURE.ctx gave you the module but not the line.

lc_impact — change impact before editing

lc_impact(file_path="src/services/auth.py")

Returns: dependents, coupling score, related modules, test coverage. Call this before editing any file that might have downstream effects.

lc_context — task-specific context bundle

lc_context(
  task_description="add rate limiting to the API authentication endpoint",
  token_budget=8000
)

Returns the most relevant ctx + code chunks for a specific task, pre-filtered to your token budget. Best entry point for complex multi-file tasks.

If MCP tools aren't available (server not running), fall back to the ctx file workflow above — it covers ~90% of the same ground.

---

Token economics

Approach	Tokens	Signal
Glob + read all source files	20k–100k	High noise
ARCHITECTURE + module ctx	600–1,500	Focused
lc_context() for a task	2k–8k	Targeted
lc_search() for a symbol	200–500	Precise

---

File reference

.linear_canal_data/<project_id>/
  ctx/
    ARCHITECTURE.ctx    ← start here always
    INTERFACES.ctx      ← find any export
    RISKS.ctx           ← before editing
    DEPENDENCIES.ctx    ← before importing
    PATTERNS.ctx        ← before adding code
    OWNERSHIP.ctx       ← coupling / owners
    <module>.ctx        ← per-module deep dive
  scores.json           ← per-file importance scores
  graph.db              ← SQLite graph store

.LC/
  CLAUDE.md             ← agent instructions (Claude Code / Kilo / Roo)
  AGENTS.md             ← agent instructions (OpenCode / universal)
  GEMINI.md             ← agent instructions (Gemini CLI)
  .cursorrules          ← agent instructions (Cursor)