| name | using-linear-canal |
| description | Use at the start of every session or task in any project — checks whether Linear Canal has indexed this codebase and activates the right workflow. MANDATORY: invoke before any Glob, Grep, Read, or file exploration. Trigger on: session start, first user message, any question about the project, any coding task, any file edit request.
|
Using Linear Canal
Step 1 — Check if this project is indexed
Bash: ls .linear_canal_data/
If the folder exists → Linear Canal index is active. Follow the MCP workflow below.
If the folder does not exist → proceed with normal tools (Glob, Read, etc.).
Step 2 — MCP workflow (index is active)
The MCP tools run semantic vector search (LanceDB) against the indexed codebase.
They are strictly better than Glob/Grep — they find relevant code by meaning, not just filename.
Call lc_context FIRST — every single task
lc_context(task_description="<paste the user's full request here>", token_budget=8000)
This single call:
- Runs vector search across all indexed files
- Returns ARCHITECTURE + RISKS + the most relevant code chunks
- Covers 90% of what you need to start working
Use lc_search for targeted lookup
lc_search(query="auth middleware JWT token validation", limit=5)
lc_search(query="OauthController social login callback")
Returns ranked code chunks with file paths and line numbers. Use when lc_context
gave you the module but you need a specific function or pattern.
Use lc_impact before editing any file
lc_impact(file_path="app/Http/Controllers/Auth/OauthController.php")
Returns: dependents, coupling score, related modules, test files. Always call this
before modifying a file that might have downstream effects.
Step 3 — Fallback (MCP server not running)
If MCP tools are unavailable, read ctx files directly — DO NOT use Glob/Grep:
Read: .linear_canal_data/<project_id>/ctx/ARCHITECTURE.ctx ← always first
Read: .linear_canal_data/<project_id>/ctx/INTERFACES.ctx ← find any symbol
Read: .linear_canal_data/<project_id>/ctx/RISKS.ctx ← before editing
Read: .linear_canal_data/<project_id>/ctx/<module>.ctx ← per-module detail
Get the project_id with: ls .linear_canal_data/
What NOT to do
| Wrong | Right |
|---|
Glob("**/*.php") to explore | lc_context(task_description="...") |
Grep("OauthController") to find code | lc_search(query="OAuth controller login") |
Read("app/Http/Controllers/Auth.php") to understand structure | lc_search(query="auth controller") → read only the specific file returned |
| Reading multiple files to understand architecture | lc_context returns it compiled in one call |
Token economics
| Approach | Tokens | Quality |
|---|
lc_context (one MCP call) | ~2,000–8,000 | Semantic, ranked, pre-analysed |
| Read ctx files manually | ~1,500 | Good — same data, no vector search |
| Glob + Read raw source files | 20,000–100,000 | High noise, slow |
If .linear_canal_data/ is missing
This project hasn't been indexed by Linear Canal yet.
Run: PYTHONUTF8=1 linear-canal setup
(takes 3–10 min depending on codebase size)
