| name | using-linear-canal |
| description | Use at the start of every session or task in a project that has a `.linear_canal_data/` folder. This is a mandatory orientation check — invoke it before any file read, Glob, Grep, or codebase action. The folder signals that Linear Canal has pre-compiled the entire codebase into ctx files, which means raw exploration is unnecessary and expensive. Trigger on: session start, first user message, any question about the project, any task involving code.
|
Using Linear Canal
Why this matters
When .linear_canal_data/ exists, Linear Canal has already done the expensive
work: it scanned every file, built a dependency graph, identified risks, and
compiled all of that into small, structured .ctx files.
Reading those ctx files gives you full project understanding in ~1,500 tokens.
Skipping them and using Glob/Grep instead costs 10,000–100,000 tokens and gives
you less accurate results. The ctx files are strictly better — faster, cheaper,
and pre-analysed.
The protocol
Step 1: Check for the index
Bash: ls .linear_canal_data/
If the folder exists and contains a project directory — the index is active.
Step 2: Use the lc-context skill
Invoke lc-context before reading any source file, before any Glob or Grep,
before answering any question about the project structure.
The skill tells you exactly which ctx file to read for any situation. Start
with ARCHITECTURE.ctx — it orients you to the full module map in ~400 tokens.
Step 3: Only then open raw source files
After reading the relevant ctx files, open only the specific source files you
actually need to make a change. Not to explore — to act.
Common rationalisations — and why they don't hold
| Thought | Why it's wrong |
|---|
| "Let me just grep for this quickly" | INTERFACES.ctx already has every export — grep is slower and noisier |
| "I need to understand the structure first" | ARCHITECTURE.ctx is the structure, compiled and ready |
| "This is a simple question" | ARCHITECTURE.ctx answers simple questions in 400 tokens; grep costs 10x that |
| "I remember this codebase" | ctx files reflect the current state; memory doesn't |
| "The MCP server isn't running" | ctx files work without MCP — lc-context covers both paths |
What to do if .linear_canal_data/ is missing or empty
The project hasn't been indexed yet. Tell the user:
This project doesn't have a Linear Canal index yet.
Run: linear-canal setup
Then proceed with normal exploration tools.
