ctxloom Documentation

Setup

# From anywhere — registers an alias in ~/.ctxloom/repos.json
ctxloom register /path/to/frontend --alias frontend

# List registered repos
ctxloom repos

cd /path/to/frontend
ctxloom init      # writes .mcp.json + agent rules + hooks + skills
ctxloom index     # builds graph + vectors + git overlay
ctxloom register /path/to/frontend --alias frontend  # so other projects can target it

Using the alias in tool calls

// Read a file from the registered "frontend" repo
{
  "tool": "ctx_get_file",
  "args": {
    "path": "src/App.tsx",
    "project_root": "frontend"
  }
}

// Or pass an absolute path directly (no register needed)
{
  "tool": "ctx_search",
  "args": {
    "query": "useEffect",
    "project_root": "/path/to/frontend"
  }
}

Resolution order

1. 1
   Explicit alias — project_root matches a name in ~/.ctxloom/repos.json — resolves to that absolute path
2. 2
   Absolute path — project_root is an absolute path — used directly (must exist and be readable)
3. 3
   Default project — project_root omitted — falls back to the server's default (the dir it was launched from)
4. 4
   Structured error — Returns alias_not_found / no_default_project / project_root_not_found XML if resolution fails — agents can recover instead of crashing

Tuning

ctxloom . --with-git --git-window-days=365

ctxloom . --no-git

New tools

Enriched tools

What it does on every PR:

• →Posts a risk-scored summary: overall risk label + score, blast radius, top high-risk files
• →Inline review comments anchored at the highest-risk hunks
• →Suggests reviewers from git ownership + co-change history
• →Optional Check Run to block merges above a risk threshold

Enable it on a repo

Option 1 — one command (if you have the CLI installed, npm install -g ctxloom-pro):

ctxloom install-pr-bot
git add .github/workflows/ctxloom-review.yml
git commit -m "ci: enable ctxloom pr-bot"
git push

It writes the workflow below — default branch auto-detected, action pinned to @v1. Use --force to overwrite an existing file or --ref v1.7.9 to pin an exact release for reproducible reviews.

Option 2 — paste the workflow yourself:

name: ctxloom review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # REQUIRED — git overlay needs full history
      - uses: kodiii/ctxloom-pr-bot@v1

First run builds the dependency graph (~10–60s for typical repos); subsequent runs reuse the workflow cache. Private repos also need a CTXLOOM_LICENSE_KEY repo secret — the MCP server refuses to start without it.

Configure via .ctxloom.yml

Optional — place at your repo root to override defaults:

risk_threshold: 0.7        # 0–1; comments fire above this
inline_comments: true       # post per-hunk inline notes
suggested_reviewers: true   # nominate reviewers from git history
check_run: false            # set true to BLOCK merge on high risk
excluded_paths: []          # globs the bot ignores
max_inline_per_pr: 10       # cap on inline comments (avoids spam)

Cost

Optional: LLM-narrated reviews opt-in

Want a narrative layer on top of the deterministic analysis? A separate workflow runs four specialist Claude subagents (security, architecture, testing, performance) in parallel, each calling ctxloom's MCP tools for structural evidence so the LLM never hallucinates the graph. It's risk-gated— only fires on PRs the deterministic bot already flagged medium-or-higher, so you don't spend tokens on trivial changes. You can even run it locally from Claude Desktop / Claude Code with no API key using your existing session — no GitHub Action, no secrets. See the AI-REVIEWS.md guide in the repo for the three setup paths.

How search works

1. 1
   Embed — Query embedded with sentence-transformers/all-MiniLM-L6-v2 (local, 384-dim)
2. 2
   Vector search — ANN query against LanceDB
3. 3
   Graph expansion — Results expanded via import graph (importers/imports get score boost)
4. 4
   Skeletonize — Dependency files reduced to signature-only views (~92% token reduction)

• ✓Path traversal prevention (CWE-22), symlink-aware — all file inputs validated against project root
• ✓Shell injection prevention — execFileSync with argument arrays, no shell string interpolation
• ✓XML injection prevention — all user-controlled strings escaped before XML output
• ✓File size limits — files over 5 MB rejected and skipped by indexer
• ✓Input bounds — limit capped at 100, depth capped at 20 across all tools
• ✓Atomic snapshot writes — written to .tmp then renamed, prevents torn reads
• ✓Snapshot schema validation — validated before hydration, prevents prototype pollution