---
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)
```
