reza 0.5.0

Universal LLM context database — instant project awareness for Claude, Cursor, Codex, Aider, Kilocode and any AI coding tool

reza

Universal LLM Context Database — give any AI coding tool instant awareness of your project.

Index your project once. Never re-explain it again.

---

The Problem

Every time you start a new AI session, you waste 5–15 minutes re-explaining your project:

• What the stack is
• Where the key files are
• What was already tried
• Why certain decisions were made

Switch from Claude to Cursor mid-task? Start over. Hit a context limit? Your architectural decisions vanish. Use two AI tools at once? They have no idea what each other did.

This is a solved problem. reza solves it.

---

The Solution

reza creates a local SQLite database (.reza/context.db) in your project that stores:

• Every file path, type, line count, and purpose (extracted from docstrings and comments)
• All active LLM sessions and their progress
• Compact session summaries written by the active tool on save/end
• Full raw conversation turns, searchable across the session with SQLite FTS5
• A real-time change log synced via file watcher and git hooks
• Transcript drops in .reza/handoffs/ for tools that export chats instead of writing turns directly

Any AI tool can query this database instead of scanning your files.

---

Quick Start

# via npm (JS / Node ecosystem):
npm install -g @swebreza/reza

# via pip (Python ecosystem):
pip install reza

# then in any project:
cd your-project
reza init

That's it. Your project is now indexed.

reza status          # what reza knows about your project
reza query           # full context overview
reza session handoff # summary + recent turns for the latest session
reza watch &         # optional: real-time file sync

---

Install as an AI CLI Skill

Install reza once into your AI tool so it auto-activates on every project — no manual setup per session.

Claude Code

Installs /reza as a slash command. Type /reza in any Claude Code session to instantly load your project context.

One-line install:

mkdir -p ~/.claude/skills/reza && curl -fsSL \
  https://raw.githubusercontent.com/swebreza/reza/main/integrations/claude-code/SKILL.md \
  -o ~/.claude/skills/reza/SKILL.md

Or manually:

mkdir -p ~/.claude/skills/reza
cp integrations/claude-code/SKILL.md ~/.claude/skills/reza/SKILL.md

Restart Claude Code, then type / — you'll see reza in the skill list.

It also auto-triggers whenever you say:

• "pick up where I left off"
• "what is this project"
• "continue from last session"
• "what was I working on"

---

Cursor

Copy the .cursorrules file into your project root:

cp integrations/cursor/.cursorrules your-project/.cursorrules

Or add globally to ~/.cursor/rules/reza.mdc:

mkdir -p ~/.cursor/rules
cp integrations/cursor/.cursorrules ~/.cursor/rules/reza.mdc

Cursor will now prompt reza queries automatically at session start.

---

Kilocode

# Copy into your project:
cp integrations/kilocode/rules.md your-project/.kilocode/reza.md

# Or add globally to Kilocode's rules directory:
cp integrations/kilocode/rules.md ~/.kilocode/rules/reza.md

---

Aider

# Add to your project's .aider.conf.yml:
echo "read:" >> .aider.conf.yml
echo "  - .reza/CONTEXT.md" >> .aider.conf.yml

# Generate the context file before each session:
reza export

# Then just run aider normally — context is always included:
aider

Or pass it inline per session:

reza export && aider --read .reza/CONTEXT.md

---

GitHub Copilot

# Creates .github/copilot-instructions.md (Copilot reads this automatically):
mkdir -p .github
cp integrations/github-copilot/README.md .github/copilot-instructions.md

Then in Copilot Chat, reference the exported context:

#file:.reza/CONTEXT.md  what files handle authentication?

---

Continue.dev

# Generate context file:
reza export

# Reference in chat:
@.reza/CONTEXT.md

Or add to ~/.continue/config.json to auto-include on every session — see integrations/continue/README.md.

---

Codeium / Windsurf

reza export --format context   # generates .reza/CONTEXT.md

In Windsurf Cascade:

@.reza/CONTEXT.md

In Codeium: keep .reza/CONTEXT.md open in an editor tab — Codeium reads open files.

---

OpenAI Codex CLI

# Create a shell alias that auto-injects reza context:
alias codex-reza='reza export --format context -o /tmp/.reza_ctx.md && codex --system-prompt "$(cat /tmp/.reza_ctx.md)"'

# Use it:
codex-reza "find the authentication middleware"

---

Measured Token Savings

Tested on a real 1,710-file monorepo (Django + 2× FastAPI + 4× React):

Scenario	Without reza	With reza	Reduction
Task orientation (find relevant files)	~18,000 tokens	~4,900 tokens	73%
Cross-LLM handoff	~10,000 tokens	~1,250 tokens	88%
Find a specific file	~7,200 tokens	~450 tokens	94%

At 500 sessions/month on Claude Sonnet: ~$14/month saved in API costs. More importantly: 58+ hours of developer wait time returned.

---

CLI Reference

Core commands

reza init                     # Initialize reza in the current project
reza status                   # Quick project overview
reza watch                    # Start real-time file watcher
reza upgrade                  # Re-scan all files (after big refactors)

Querying

reza query                    # Full project overview
reza query --find "auth"      # Search files by path or purpose
reza query --recent           # Last 30 file changes
reza query --sessions         # Active / interrupted sessions
reza query --file src/api.py  # Full info about one file
reza query --json             # Machine-readable JSON output

One-time setup

reza install-hooks                # auto-detect and register all installed tools
reza install-hooks --tool aider   # register one specific tool
reza install-hooks --list         # see what was detected and enabled

Then just keep reza watch running — it handles file changes AND conversation sync for every registered tool.

Session management

# Start a session (reza auto-links to an existing thread when confident)
reza session start --llm claude --task "implementing JWT auth"
# → [reza] Continuing thread: jwt-auth-thread   (if auto-linked)

# Explicit thread control
reza session start --llm cursor --task "JWT auth" --continue           # force-link to recent thread
reza session start --llm cursor --task "JWT auth" --thread thread-abc  # link to specific thread
reza session start --llm cursor --task "unrelated work"                # new thread

# Save a human-readable summary (optional — auto-sync stores all raw turns)
reza session save --id claude-abc12345 \
  --summary "Models done, starting views" \
  --files "auth/models.py, auth/serializers.py"

# Cross-tool thread handoff (full history across all tools)
reza session handoff                    # full thread, all tools
reza session handoff --budget 8000      # token-budget-aware truncation
reza session handoff --session-only     # single session only
reza session handoff --format json      # machine-readable

# Search across the entire thread
reza session search "jwt middleware"
reza session search "circular import" --id claude-abc12345

# Manual one-shot sync (when reza watch wasn't running)
reza sync-all
reza sync-all --tool aider

# Bulk-import past Cursor / Codex CLI transcripts from disk (idempotent re-sync)
reza sync-cursor
reza sync-codex

# Add turns manually or ingest exported transcripts
reza session turns add --id claude-abc12345 --role assistant --content "Next: wire auth routes"
reza ingest .reza/handoffs/cursor-export.json

# List / inspect sessions (includes imported chats — see source_tool in list)
reza session list
reza session list --source cursor --limit 80 --json
reza session show claude-abc12345
reza session load claude-abc12345 --copy   # handoff pack → clipboard for another tool
reza session graph claude-abc12345         # files + code-graph nodes touched
reza session graph claude-abc12345 --json

# Close a session
reza session end --id claude-abc12345

Thread management

reza thread list                                          # all threads
reza thread show --id thread-abc                          # full thread detail
reza thread link --session cursor-abc --thread thread-xyz # manually link a session
reza thread title --id thread-abc --title "JWT work"      # rename a thread

Exporting (for tools without direct DB access)

reza export                          # .reza/CONTEXT.md (human-readable markdown)
reza export --format json            # .reza/context.json (machine-readable)
reza export --format context         # compact format optimized for LLM prompts
reza export -o /path/to/output.md    # custom output path

Parallel agents — file locks & conflict detection

When two AI tools work on the same repo at the same time, reza prevents silent overwrites.

# Claim a file before editing (prevents other agents from touching it)
reza claim src/auth.py --session claude-abc12345

# See all active locks across all agents
reza locks
reza locks --session cursor-xyz789   # filter by session

# Release a lock when done
reza release src/auth.py --session claude-abc12345
reza release --all-session claude-abc12345   # release all at once

# View all open conflicts
reza conflicts
reza conflicts --all                          # include resolved

# Resolve conflicts
reza conflicts --resolve 3                    # by ID
reza conflicts --resolve-file src/auth.py     # all conflicts on one file

Conflicts are also detected automatically:

• reza watch prints a stderr alert the moment a locked file is written by a different session
• The git pre-commit hook checks staged files against active locks on every commit
• reza session end auto-releases all locks for that session — no dangling locks

Auto-sync (Claude Code Stop hook)

reza install-claude-hook          # Install Stop hook → ~/.claude/settings.json
reza install-claude-hook --uninstall   # Remove it

Fires after every Claude response. Reads Claude's .jsonl conversation file and appends new turns to reza automatically. Zero tokens consumed. Runs even when Claude hits its context limit.

Git hooks

reza hooks                    # Install pre-commit hook (auto-update on commit)
reza hooks --uninstall        # Remove the hook

---

Integrations

reza works with every major AI coding tool.

Tool	Skill Install	Per-Project Setup	Guide
Claude Code	curl into ~/.claude/skills/reza/	reza init	→
Cursor	Copy .cursorrules globally	reza init	→
Kilocode	Copy rules.md to ~/.kilocode/rules/	reza init	→
Aider	Add to .aider.conf.yml	reza export	→
Continue.dev	Edit ~/.continue/config.json	reza export	→
GitHub Copilot	Copy to .github/copilot-instructions.md	reza export	→
Codeium / Windsurf	Open context file in editor	reza export	→
OpenAI Codex	Shell alias with --system-prompt	reza export	→
Any other tool	reza export → paste output	reza export	—

Universal approach (works with any tool)

reza export --format context
# Paste .reza/CONTEXT.md content into your tool's context window

---

Parallel Agents — Running Claude + Cursor Simultaneously

reza makes it safe to run multiple AI tools on the same repo at the same time.

Claude (terminal 1)              Cursor (editor)
        │                               │
reza session start                reza session start
--llm claude                      --llm cursor
        │                               │
reza claim src/auth.py            reza claim src/auth.py
--session claude-abc123           --session cursor-xyz789
        │                               │
  ✅ GRANTED                       ❌ CONFLICT — file locked by claude
                                   Alert printed to stderr immediately
                                   Logged to conflicts table

Typical parallel workflow:

# Terminal 1 — Claude works on backend
reza session start --llm claude --task "auth backend"
reza claim src/auth.py --session claude-abc123
reza claim src/models.py --session claude-abc123
# ... Claude edits auth.py and models.py ...

# Terminal 2 — Cursor works on frontend simultaneously
reza session start --llm cursor --task "login UI"
reza claim src/components/Login.jsx --session cursor-xyz789
# ... Cursor edits Login.jsx (no conflict) ...

# Cursor tries to touch a locked file:
reza claim src/auth.py --session cursor-xyz789
# → CONFLICT: auth.py is locked by claude (claude-abc123)

# Claude finishes and releases
reza session end --id claude-abc123   # auto-releases all locks

# Now Cursor can claim it safely
reza claim src/auth.py --session cursor-xyz789   # ✅ granted

---

Cross-Tool Threads — The Killer Feature

Work moves between tools. You start in Cursor, continue in Claude Code when it gets complex, hand off to Codex when Claude hits its context limit, then come back to Cursor for the frontend. reza treats all of that as one logical thread — not four disconnected sessions.

Thread: "jwt-auth-thread"
├── cursor-abc      Cursor       09:00  completed
├── claude-def      Claude Code  11:30  interrupted  ← context limit hit here
├── codex-ghi       Codex        14:00  interrupted
└── cursor-jkl      Cursor       15:22  active        ← you are here

reza session handoff --budget 8000
# → Full conversation history across ALL four tools, budget-truncated, ready to paste

One-time setup

# Register all tools you have installed:
reza install-hooks

# Start a session (reza links subsequent sessions automatically):
reza session start --llm cursor --task "JWT auth"

After that — nothing. Every tool's conversation is saved automatically as you work.

How auto-sync works per tool

Tool	Sync method
Claude Code	Stop hook — fires after every response, zero tokens
Aider	File-watch on .aider.chat.history.md — near-instant
Codex CLI	File-watch on ~/.codex/conversations/ or reza sync-codex for rollouts under ~/.codex/sessions/
Cursor	reza sync-cursor for agent JSONL under ~/.cursor/projects/… or drop exports in .reza/handoffs/ (ingested by reza watch)
Kilocode	Drop .reza/handoffs/export.json — auto-ingested
Codex Desktop	Drop .reza/handoffs/export.json — auto-ingested

For GUI tools where you do not use the CLI transcript paths, export the chat once and drop it in .reza/handoffs/ — reza watch ingests it automatically.

Bulk import: Cursor & Codex on-disk transcripts

If you use Cursor or Codex from the terminal, reza can pull existing agent transcripts into .reza/context.db in one shot. Re-running is safe: only new turns are appended.

reza sync-cursor    # Cursor agent JSONL under ~/.cursor/projects/
reza sync-codex     # Codex rollout JSONL under ~/.codex/sessions/

Use reza session list to see imported rows (with source_tool), and reza session graph <id> to map a session to files and graph nodes. In the VS Code extension’s graph view, open the Sessions strip to highlight or isolate the subgraph for a selected session.

Thread linking — three modes

reza links sessions into threads automatically. You can also control it explicitly:

# Auto (reza detects same task, < 2hr gap) — silent, just works
reza session start --llm claude --task "JWT auth"
# → [reza] Continuing thread: jwt-auth-thread

# Semi-auto (longer gap or ambiguous) — one prompt
reza session start --llm codex --task "JWT refresh tokens"
# → Continue thread 'jwt-auth-thread'? [Y/n]

# Explicit — you decide
reza session start --llm cursor --task "JWT auth" --continue        # link to recent thread
reza session start --llm cursor --task "unrelated work"             # new thread

Full cross-tool handoff

reza session handoff                    # full thread, all tools
reza session handoff --budget 8000      # token-budget-aware truncation
reza session handoff --session-only     # single session only (old behavior)
reza session handoff --format json      # machine-readable

# Search across the entire thread:
reza session search "JWT" 
reza session search "circular import" --id claude-abc12345

---

How It Works

Your project
├── .reza/
│   ├── context.db          ← SQLite database (the brain)
│   └── CONTEXT.md          ← Exported markdown (for tools without SQL)
├── src/
│   └── ...your code...
└── .git/
    └── hooks/
        └── pre-commit       ← Auto-updates DB on every commit

Database schema (conversation-aware):

Table	What it stores
project_meta	Language, framework, project name
files	All files with path, type, line count, purpose
sessions	LLM sessions with progress, optional source_tool / source_path / source_id for imported chats
conversation_turns	Raw per-turn chat history for each session
conversation_turns_fts	Full-text search index over raw chat turns
handoff_drops	Transcript files already ingested from .reza/handoffs/
changes	Real-time change log linked to sessions
file_locks	Active file locks — which session owns which file
conflicts	Conflict history — when two agents touched the same locked file
dependencies	File import relationships

Four sync mechanisms:

1. reza init — full scan on first use
2. reza watch — file watcher (Python watchdog) for real-time updates
3. git pre-commit hook — updates staged files on every commit
4. Claude Code Stop hook — reza install-claude-hook fires after every Claude response; reads Claude's .jsonl file and saves new turns to reza automatically, even when context limit is hit

---

Installation

via npm (recommended for JS/Node developers)

npm install -g @swebreza/reza

Automatically installs the Python backend via pip. Requires Python 3.8+.

via pip (recommended for Python developers)

pip install reza

via npx (no global install)

npx @swebreza/reza init
npx @swebreza/reza query

From source

git clone https://github.com/swebreza/reza
cd reza
pip install -e .

Requirements

Requirement	Version	Notes
Python	3.8+	Core runtime — always required
pip	any	For pip install reza
Node.js	14+	Only if installing via npm
watchdog	3.0+	Only for reza watch (auto-installed)

All Python dependencies install automatically.

---

Per-Project Setup

cd your-project
reza init

This:

1. Creates .reza/context.db
2. Scans all source files and extracts purposes from docstrings/comments
3. Detects your project's language and framework
4. Installs a pre-commit git hook
5. Adds a comment to .gitignore (you decide whether to commit .reza/)

Should I commit .reza/?

Team projects: Yes — commit it. Everyone gets shared context and session history.

Solo projects: Optional. The DB regenerates quickly with reza init.

---

Supported Languages & Frameworks

Purpose extraction works for:

Language	Purpose extracted from
Python	Module docstrings ("""...""")
JavaScript / TypeScript	JSDoc comments (/** ... */)
Markdown	First # heading
Go / Java / Kotlin / Swift	// first-line comments
Rust	/// doc comments
HTML / XML	<!-- ... --> comments
SQL / Lua	-- comments
Ruby / Shell / YAML	# comments

Framework detection: Django, FastAPI, Flask, React, Vue, Next.js, Nuxt, Svelte, Astro, Express, Fastify, Go, Rust/Cargo, Maven, Gradle, Rails, and more.

---

Configuration

reza works with zero configuration. For advanced use:

Extra ignore patterns

reza init --ignore generated --ignore vendor --ignore legacy

Skip git hooks

reza init --no-hooks

Custom project directory

reza init --dir /path/to/project

---

Real-World Example

Sequential handoff (Claude → Codex, context limit mid-session)

# Day 1: Start with Claude Code
cd my-saas-project
reza init
# → Indexed 847 files in 8.2 seconds

reza session start --llm claude --task "build subscription billing"
# → Session started: claude-f3a91b2c
# → Wrote .reza/current_session

reza install-claude-hook
# → Claude Code Stop hook installed in ~/.claude/settings.json

# ... Claude works. Hook fires after every response. Turns saved silently. ...
# ... Claude hits context limit. No action needed — turns were already synced. ...

# Switch to Codex immediately (no waiting required):
reza session handoff --budget 8000
# → Full structured brief: what was done, last 8k tokens of conversation, files modified, pick-up point

# Paste the handoff output into Codex as your first message.
# Codex picks up exactly where Claude stopped.

# In Codex, save your own session when done:
reza session start --llm codex --task "frontend checkout flow"
reza session save --id codex-a1b2c3d4 \
  --summary "Checkout UI wired to Stripe. Next: webhook confirmation page." \
  --files "src/components/Checkout.jsx, src/api/stripe.js"

# Back in Claude next day — it sees the Codex session too:
reza session handoff
reza session search "idempotency keys"

Parallel agents (Claude + Aider at the same time)

# Both agents initialized on the same repo
reza watch &   # real-time conflict detection running in background

# Claude takes the API layer
reza session start --llm claude --task "REST endpoints"
reza claim src/api/ --session claude-f3a91b2c

# Aider takes the tests simultaneously
reza session start --llm aider --task "write test suite"
reza claim tests/ --session aider-8c2d4e1f

# If Aider tries to touch src/api/:
reza claim src/api/auth.py --session aider-8c2d4e1f
# → CONFLICT: src/api/auth.py is locked by claude (claude-f3a91b2c)
# → Conflict logged, alert fired to terminal

# Check all open conflicts:
reza conflicts

# Claude finishes and releases everything:
reza session end --id claude-f3a91b2c
# → All claude locks auto-released — Aider can now claim any file safely

---

Contributing

Contributions are welcome. See CONTRIBUTING.md.

High-value contributions:

• New tool integrations (in integrations/)
• Better purpose extraction heuristics
• Language-specific parsers (AST-based)
• VS Code extension that reads .reza/context.db directly
• Web UI for browsing the context database

---

License

MIT — see LICENSE.

---

Author

Built by Suweb Reza.

If reza saves you time, star the repo and tell your team.