Rectilinear

Local-first Linear issue intelligence. Maintains a search-optimized SQLite mirror of your Linear issues, projects, and project milestones with hybrid full-text + vector search. Find duplicates before filing, search across teams instantly, and manage complete project hierarchies from the terminal, native clients, or MCP.

Why

Linear teams accumulate hundreds of issues. Duplicate detection is hard, search is scattered, and context lives across many views. Rectilinear keeps a local copy with embeddings so you can:

• Find duplicates before creating new issues — semantic similarity, not just keyword matching
• Search fast — hybrid FTS5 + vector search with Reciprocal Rank Fusion, all local
• Manage issues from the CLI or let Claude Code do it through MCP tools
• Preserve project structure with first-class project/milestone metadata and portable imports that include linked issues

Linear remains the source of truth. The local database is a read-optimized cache. Writes go to Linear first, then sync back.

Just want to wire this up to Claude Code and start filing/triaging issues by voice? See QUICKSTART.md.

Architecture

┌─────────────────────────────────────────────────┐
│                  rectilinear                     │
│                                                  │
│  CLI (clap)              MCP Server (rmcp)       │
│  ┌──────────┐            ┌──────────────────┐    │
│  │ sync     │            │ search_issues    │    │
│  │ projects │            │ import_project   │    │
│  │ milestone│            │ project CRUD     │    │
│  │ search   │            │ find_duplicates  │    │
│  │ find     │            │ get_issue        │    │
│  │ show     │            │ create_issue     │    │
│  │ create   │            │ update_issue     │    │
│  │ append   │            │ append_to_issue  │    │
│  │ embed    │            │ sync_team        │    │
│  │ config   │            │ issue_context    │    │
│  └────┬─────┘            └────────┬─────────┘    │
│       │                           │              │
│  ┌────┴───────────────────────────┴──────────┐   │
│  │              Core Engine                   │   │
│  │  Search (FTS5 + Vector + RRF)             │   │
│  │  Embedding (Gemini API / local GGUF)      │   │
│  │  Linear GraphQL Client                    │   │
│  │  SQLite (WAL, FTS5, blob embeddings)      │   │
│  └───────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
         │                          │
         ▼                          ▼
   Linear API                 Gemini API
   (source of truth)          (embeddings)

Component	Choice
Language	Rust — fast startup, single binary
CLI	clap (derive)
Database	rusqlite (bundled, FTS5)
Vector storage	f32 blobs + cosine similarity in Rust
Embeddings	Gemini API (768-dim), or local GGUF with local-embeddings feature (EmbeddingGemma, 256-dim)
Linear API	reqwest + GraphQL
MCP server	rmcp, stdio transport
Config	TOML at ~/.config/rectilinear/config.toml

Install

From crates.io

cargo install rectilinear

To include the local GGUF embedding backend (EmbeddingGemma-300M, requires cmake):

cargo install rectilinear --features local-embeddings

From source

git clone https://github.com/pieter-ouwerkerk/rectilinear.git && cd rectilinear
cargo build --release
cp target/release/rectilinear ~/.local/bin/

Prerequisites

• A Linear API key (https://linear.app/settings/api)
• Optional: a Gemini API key for embeddings (https://aistudio.google.com/apikey)

Configure

Connect a Linear workspace

Rectilinear is multi-tenant: you connect one or more Linear orgs as named workspaces, and pass the workspace name on each MCP call (or set a default). The interactive flow keeps the API key out of shell history:

rectilinear config add-workspace

You'll be prompted for:

• Workspace name — a short label you'll reference later, e.g. home, work, oss. Agents pass this as workspace in MCP calls.
• Linear API key — get one at https://linear.app/settings/api. Linear API keys are org-scoped, so one key covers every team in that org. If your new workspace is in a Linear org you've already connected, you can reuse the existing key.
• Default team — the team prefix (e.g. ENG, SFO) Rectilinear should use when you don't pass --team explicitly.
• Set as default workspace? — Y if this is your primary; N otherwise.

The config is written to ~/.config/rectilinear/config.toml with mode 0600 (owner read/write only).

Useful follow-ups:

rectilinear workspace list      # show configured workspaces
rectilinear workspace current   # show the active default
rectilinear workspace assume X  # switch the active default to workspace X
rectilinear config show         # full config dump (keys masked)

Optional: Gemini API key for embeddings

Embeddings power vector / hybrid search and duplicate detection. Configure once:

rectilinear config set embedding.gemini-api-key AIza...
rectilinear config set embedding.backend api

Or set GEMINI_API_KEY in your environment — it overrides the config value.

Single-workspace shortcut (legacy)

If you only ever work with one Linear org, the older single-tenant flow still works and skips the workspace concept entirely:

rectilinear config set linear-api-key lin_api_XXXX
rectilinear config set default-team ENG

LINEAR_API_KEY env var works too. New users should prefer config add-workspace.

Sync issues

# First sync (automatically does a full sync)
rectilinear sync --team ENG

# Sync and generate embeddings in one step
rectilinear sync --team ENG --embed

# Force full re-sync
rectilinear sync --team ENG --full

# Include archived issues on an incremental sync. Full syncs include archived issues automatically.
rectilinear sync --team ENG --include-archived

# Show each bounded request, page size, and adaptive complexity reduction
rectilinear sync --team ENG --full --include-archived --verbose

Synchronization uses shallow, independently paginated Linear queries. Pages are persisted before traversal continues, complexity rejections reduce only the affected operation's page size, and the team cursor advances only after projects, labels, cycles, issues, issue labels, relationships, and comments all succeed. Page sizes can be overridden with RECTILINEAR_LINEAR_<OPERATION>_PAGE_SIZE; the default planner targets 7,000 points rather than Linear's 10,000-point ceiling. See Complexity-aware Linear synchronization for the batching model, retry and partial-failure semantics, supported membership paths, and large-workspace fixture.

Generate embeddings

Embeddings power vector search and duplicate detection. Uses the Gemini API if GEMINI_API_KEY is set. If you installed with --features local-embeddings, it can also use a local GGUF model (EmbeddingGemma-300M, auto-downloaded on first use) as a fallback.

# Embed issues that don't have embeddings yet
rectilinear embed --team ENG

# Regenerate all embeddings (e.g. after changing backend)
rectilinear embed --force

Usage

Search

# Hybrid search (FTS + vector, default)
rectilinear search "login timeout on mobile"

# FTS-only (no embeddings needed)
rectilinear search "login timeout" --mode fts

# Filter by team and state
rectilinear search "auth" --team ENG --state "In Progress"

# JSON output for scripting
rectilinear search "auth" --json --limit 5

Find duplicates

# Check if an issue already exists before filing
rectilinear find --similar "Users can't reset password on Safari"

# Lower the threshold to cast a wider net
rectilinear find --similar "password reset bug" --threshold 0.5

View issues

rectilinear show ENG-123
rectilinear show ENG-123 --comments
rectilinear show ENG-123 --json

When comments are requested through MCP, Rectilinear returns comments with comments_status, comments_synced_at, and comments_sync_error. Treat comments: [] as meaningful only with the status:

• synced means comments were fetched and at least one comment was found.
• none_found means Linear returned no comments for the issue.
• not_synced means comments have not been fetched yet.
• permission_denied or unavailable means Linear could not provide comments; see comments_sync_error.

Create and update issues

# Create an issue (writes to Linear, syncs back locally)
rectilinear create --team ENG --title "Fix Safari password reset" \
  --description "Users on Safari 17+ can't complete the reset flow" \
  --priority 2

# Add a comment
rectilinear append ENG-123 --comment "Reproduced on Safari 17.4"

# Append to description
rectilinear append ENG-123 --description "Also affects Safari 17.3"

Projects and milestones

Projects and milestones are first-class cached resources. Linear remains the source of truth; sync, projects sync, and the MCP refresh operations update the relational mirror.

# Query project metadata and milestones
rectilinear projects list
rectilinear projects show "API Reliability"
rectilinear milestones list --project "API Reliability"

# Create and update the hierarchy
rectilinear projects create --name "API Reliability" --teams ENG \
  --description "Improve service resilience and incident response" --priority 2 \
  --labels Infrastructure
rectilinear milestones create --project "API Reliability" --name "Request tracing" \
  --target-date 2026-09-01
rectilinear milestones update "Request tracing" \
  --description "Instrument critical request paths"

# Export one complete relationship graph as JSON
rectilinear projects import "API Reliability"
rectilinear milestones import "Request tracing" --project "API Reliability"

Project imports contain the complete project metadata, ordered milestones, and all linked issues across the project’s teams. Milestone imports contain the owning project, milestone metadata, and every issue assigned to that milestone. This is the preferred downstream-client boundary when the relationship graph matters; consumers no longer need to copy or reconstruct individual issues.

The MCP server exposes matching list/get/create/update/delete_project, *_project_milestone, import_project, and import_project_milestone tools. Project CRUD preserves teams, members, labels, status, lead, priority, dates, content, and visual metadata. create_issue, update_issue, and mark_triaged accept project_milestone so an issue can be created or moved within the hierarchy. The UniFFI RectilinearEngine exposes the same local reads, CRUD calls, hierarchy imports, and set_issue_project_context for Swift clients.

Use with AI agents (MCP)

Rectilinear ships an MCP server (rectilinear serve, stdio transport) that any MCP-aware agent can connect to. Register it once at user scope and every project on your machine gets access — there's nothing per-repo to configure for the server itself, only for which workspace a given repo should use (see Per-project guidance below).

Claude Code

User-scope (recommended — available in every project automatically):

claude mcp add rectilinear -s user -- rectilinear serve

Verify it's connected:

claude mcp list  # should show: rectilinear: ... ✓ Connected

Per-project alternative — add to the project's .mcp.json:

{
  "mcpServers": {
    "rectilinear": {
      "command": "rectilinear",
      "args": ["serve"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.rectilinear]
command = "rectilinear"
args = ["serve"]
enabled = true

(Use an absolute path to the binary if rectilinear isn't on your $PATH when Codex spawns the server.)

Per-project guidance

The server exposes the same tools to every repo on your machine, so agents need a hint to pick the right workspace. Drop a short section in the repo's AGENTS.md (read by Codex, Cursor, and Claude Code) or CLAUDE.md:

## Linear / Rectilinear

Issues for this repo live in Linear team `SFO`. Use the Rectilinear MCP
with workspace `home` — it's already configured with `SFO` as the default
team, so you don't need to pass `team` explicitly.

Without this hint, agents have to call list_workspaces and guess; with it, they go straight to the right one.

Tools exposed

This exposes 25 tools to MCP clients:

Tool	Purpose
list_workspaces	Discover configured Linear workspaces
list_labels	Read the cached workspace label catalog
list_projects	Refresh and list project metadata
get_project	Read a project, its milestones, and optionally all issues
create_project	Create a project with teams and metadata
update_project	Update project metadata and relationships
delete_project	Archive a project and remove its cached hierarchy
import_project	Return a portable project + milestones + issues bundle
list_project_milestones	List ordered milestones for a project
get_project_milestone	Read a milestone and optionally all issues
create_project_milestone	Create a milestone inside a project
update_project_milestone	Update or move a milestone
delete_project_milestone	Delete a milestone
import_project_milestone	Return a portable project + milestone + issues bundle
search_issues	Hybrid search with team/state filters
find_duplicates	Semantic duplicate detection given title + description
get_issue	Full issue details with optional comments and comment sync diagnostics
create_issue	Create in Linear with optional project/milestone + sync back
update_issue	Update title, description, priority, state, labels, project, and milestone
append_to_issue	Add comment or extend description
sync_team	Trigger sync for a team; full syncs include archived issues and refresh comments
issue_context	Issue + its N most similar issues, comments, and comment sync diagnostics
get_triage_queue	Batch of unprioritized issues enriched with similar issues and code search hints
mark_triaged	Set priority, state, labels, project/milestone + update title/description + add comment in one call
manage_relation	Add or remove issue relations

Triage workflow

The MCP server includes built-in instructions that teach Claude Code how to triage issues conversationally. Setup:

# 1. Sync and embed your team's issues (needed once, then incremental)
rectilinear sync --team CUT --embed

# 2. Add rectilinear to your Claude Code MCP config (see above)

# 3. In Claude Code, just say:
#    "triage CUT issues"
#    "let's triage some random CUT issues"  (uses shuffle for variety)

What happens: Claude calls get_triage_queue, which syncs from Linear to get fresh data. For each issue, Claude:

1. Explores the codebase using extracted code_search_hints (file paths, identifiers, labels) to understand the current implementation
2. Presents the issue with code findings and similar issues, then asks clarifying questions from the perspective of a staff engineer who would implement it
3. Proposes priority, improved title/description (with code references), state changes, labels, and project assignment
4. After you confirm, calls mark_triaged to apply all changes to Linear in one call

Issues are presented one at a time — Claude waits for your input and applies changes before moving to the next.

Staleness protection: mark_triaged re-fetches the issue from Linear before applying changes. If an issue that was unprioritized when queued has since been prioritized, Claude skips it. Issues that were already prioritized when selected can be intentionally re-triaged. If the content changed since the queue was fetched, Claude shows what changed and re-evaluates. Embeddings are automatically updated when content changes.

Best results: Run triage from within your project directory so Claude can explore the actual codebase. If you use Cuttlefish, its MCP tools (get_symbols, find_references) give Claude even richer code context.

You can also add project-specific guidance in your CLAUDE.md:

## Triage

When triaging Linear issues, present and resolve one issue at a time
before moving to the next. Explore the codebase to understand each
issue's context before asking questions.

Data storage

Path	Contents
~/.config/rectilinear/config.toml	API keys, defaults, preferences
~/.local/share/rectilinear/rectilinear.db	SQLite database (issues, FTS index, embeddings)
~/.local/share/rectilinear/models/	Local GGUF models (auto-downloaded)

Search modes

FTS — BM25 keyword search via SQLite FTS5 with Porter stemming. Fast, no embeddings needed.

Vector — Embeds the query via Gemini API, computes cosine similarity against stored issue chunks, returns max similarity per issue.

Hybrid (default) — Runs both FTS and vector search, combines results with Reciprocal Rank Fusion (score = Σ 1/(k + rank)). For duplicate detection, vector results are weighted 0.7 vs FTS 0.3.