RTK: Rust Context Engine 🚀

The ultimate local context engine to stop AI distraction, optimize prompt layering, and slash LLM API costs by up to 95%.

---

Quickstart (~5 min): docs/QUICKSTART.md · User guide: docs/USER.md · Community: Discussions · Status: v2.3.1 shipped — feature-freeze until real-world feedback (PLAN_CLOSURE)

Install: cargo install rtk-context-engine --locked · macOS: brew tap andreafinazziinfo/rust-context-engine && brew install rtk · Windows: release zip

RTK (Rust Context Engine) is a high-performance, Rust-based local runtime and context engine designed to optimize how Autonomous Agents (like Claude Code, Cursor, Windsurf, Antigravity) interact with your project codebase.

⚠️ The Problem

Modern LLMs are incredibly smart, but they suffer from Context Window Exhaustion & Distraction: they fill their memory with useless terminal logs (like 1000 lines of npm install warnings), raw files, and long reasoning loops, causing them to slow down, hallucinate, and rack up massive API bills.

💡 The Solution

RTK solves this by intercepting commands, stripping the noise, caching the raw data in a local FTS5 vector database, and returning only the pure semantic signal. By enforcing YAGNI developer behaviors and compressing outputs, the toolkit saves an average of ~81% of tokens across verified scenarios (ranging from 41% to 96%).

⚙️ Three-Phase Efficacy Pipeline

graph TD
    %% Define color classes
    classDef phase1 fill:#1e3a8a,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef phase2 fill:#581c87,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef phase3 fill:#065f46,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef database fill:#0f172a,stroke:#64748b,stroke-width:2px,color:#cbd5e1;
    classDef raw fill:#7f1d1d,stroke:#ef4444,stroke-width:2px,color:#fca5a5;

    %% Nodes
    subgraph P1["📥 PHASE 1: INPUT VIRTUALIZATION (Avg -82.5% Tokens)"]
        RawCmds["⚠️ Noisy Commands<br/>(git, cargo, pytest, docker, npm...)"]:::raw
        RTKEngine["⚙️ RTK Filter Engine"]:::phase1
        DLP["🛡️ DLP Redactor<br/>(Scrubs keys/secrets)"]:::phase1
        FilteredOut["✅ Pure Signal Output<br/>(To LLM Context)"]:::phase1
    end

    subgraph P2["🧠 PHASE 2: REASONING & MEMORY (-96.5% Tokens)"]
        RTKThink["🤫 rtk think<br/>(Reasoning Stdin)"]:::phase2
        FTS5["🗄️ Unified Local Database (.rtk/rtk.db)<br/>(Persistent Context Vault)"]:::database
        RTKMemory["🧠 rtk memory set/get<br/>(Project State)"]:::phase2
    end

    subgraph P3["📤 PHASE 3: OUTPUT AUTONOMY (-54% to -75% Output)"]
        SystemRules["📜 Auto-Injected Rules<br/>(.cursor/rules, .agents)"]:::phase3
        Caveman["🗣️ Caveman Persona<br/>(Compressed responses)"]:::phase3
        Ponytail["🧑‍💻 Ponytail Persona<br/>(YAGNI/Minimal code)"]:::phase3
    end

    %% Flows
    RawCmds --> RTKEngine
    RTKEngine --> DLP
    DLP --> FilteredOut
    RTKEngine -- "Cache Raw Log" --> FTS5
    
    RTKThink --> FTS5
    RTKMemory <--> FTS5

    SystemRules --> Caveman
    SystemRules --> Ponytail
    Caveman & Ponytail --> FilteredOut

Loading

---

✨ Features & Benchmarks — Average 81.0% Token Savings

RTK optimizes the entire lifecycle of an Autonomous Agent across 3 phases: Input → Reasoning → Output.

Methodology: All benchmarks below were generated by our internal benchmark.py token-counting suite using the official tiktoken cl100k_base BPE tokenizer. Real commands were executed against the RTK codebase itself. Simulated scenarios use industry-standard mock data matching each tool's documented output format. Output profile benchmarks are sourced from Caveman and Ponytail.

📥 Phase 1: Input Virtualization (What the AI reads) — Avg 81.1%

RTK intercepts noisy terminal outputs, caches the full text in SQLite, and returns only the essential signal.

Feature	Command / Scenario	Standard	RTK	Savings
🦀 Cargo Test	rtk cargo test (REAL, 118 tests)	2,465	678	📉 72.5%
🦀 Cargo Build	rtk cargo build (30 crates)	482	95	📉 80.3%
🦀 Cargo Test	rtk cargo test (50 tests, 1 failure)	710	112	📉 84.2%
📜 Git Log	rtk git log (20 commits)	1,713	272	📉 84.1%
📜 Git Log	rtk git log (REAL, 15 commits)	1,333	335	📉 74.9%
📜 Git Diff	rtk git diff (5 files, 15 changes)	1,587	308	📉 80.6%
📜 Git Status	rtk git status (25 untracked)	322	189	📉 41.3%
🐍 Pytest	rtk pytest (30 tests, 8 warnings)	558	172	📉 69.2%
🐳 Docker Build	rtk docker build (8 layers)	2,506	186	📉 92.6%
🟣 .NET Build	rtk dotnet test (49 tests)	245	41	📉 83.3%
🐹 Go Test	rtk go_test (20 tests)	375	41	📉 89.1%
☕ Gradle	rtk gradle build (14 tasks)	114	21	📉 81.6%
📦 NPM Install	rtk npm install (40 packages)	831	259	📉 68.8%
📂 LS Recursive	rtk ls -laR (50 files)	1,473	519	📉 64.8%
🗜️ Context Pack	rtk pack --strip --skeleton (REAL)	32,227	5,640	📉 82.5%

🧠 Phase 2: Reasoning & Memory (The "Middle") — 96.5%

LLMs bloat the context window with long reasoning loops and repeated rule lookups. RTK offloads them to the database.

Feature	What it does	Savings
🤫 Hidden Chain-of-Thought	cat <<EOF | rtk think offloads 462-token reasoning blocks to SQLite. Only 16 tokens returned.	📉 96.5%
🧠 Semantic Memory	rtk memory set/get/search stores architectural decisions across sessions.	Eliminates RAG decay
🔒 DLP Redaction	Auto-redacts API keys, JWT, PEM keys, DB credentials, high-entropy secrets.	📉 41.6%

📤 Phase 3: Output Autonomy (What the AI writes)

RTK injects system prompts that force the AI to use ultra-compressed communication and minimalist code.

Feature	What it does	Validated Savings
🗣️ Caveman Profile	Injects ultra-compressed personas into the AI's system prompt.	📉 ~75% Tokens (Tested by Caveman)
🧑‍💻 Ponytail Profile	Prevents over-engineered code generation (YAGNI, stdlib-first).	📉 ~54% less code (Tested by Ponytail)
🚀 Dynamic Autonomy	Warns the AI when output exceeds 3,000-token safety thresholds.	Auto-correction enabled

💰 Cost & Time Savings (Monthly Projection: 50 commands/day)

Projections are based on 1,500 commands/month (50/day * 30 days) with an average of 2,273 tokens saved per command (totaling 3.41 Million tokens saved/month) and 19.3 seconds saved per command (totaling 8.1 hours saved/month).

Provider	Tier	Modello	Input / 1M	Output / 1M	Monthly Cost Saved (Direct)	Monthly Cost Saved (5x Session Avg)*	Monthly Time Saved	Note
Anthropic	Top	Claude Opus 4.8	$5.00	$25.00	$17.05	$85.25	8.1 hrs	Model pricing ufficiale Claude
Anthropic	Mid	Claude Sonnet 4.6	$3.00	$15.00	$10.23	$51.15	8.1 hrs	Model pricing ufficiale Claude
OpenAI	Top	GPT-5.5	$5.00	$30.00	$17.05	$85.25	8.1 hrs	Pricing ufficiale OpenAI
OpenAI	Mid	GPT-5.4	$2.50	$15.00	$8.53	$42.65	8.1 hrs	Pricing ufficiale OpenAI
Google	Top	Gemini 3.1 Pro Preview	$2.00	$12.00	$6.82	$34.10	8.1 hrs	Fino a 200k token, poi cambia
Google	Mid	Gemini 3.5 Flash	$1.50	$9.00	$5.12	$25.60	8.1 hrs	Buon tier intermedio

*Note: In multi-turn chat sessions (e.g. Claude Code, Aider), command outputs are re-sent in the prompt history for subsequent turns. A conservative 5x context amplification factor is applied to represent typical developer session savings.

---

🛠️ Advanced Context Architecture & MCP

Version 2.x shifts RTK from a basic CLI output filter to a comprehensive local Context Engine. It coordinates code indexing, semantic search, memory persistence, and tool access via a unified SQLite database and MCP.

📐 Local Context Engine Dataflow

The following diagram illustrates how your development editor or agent (e.g., Claude Code, Cursor) communicates with RTK's unified storage and indices:

graph TD
    %% Styling
    classDef client fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef core fill:#312e81,stroke:#6366f1,stroke-width:2px,color:#f8fafc;
    classDef storage fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
    classDef model fill:#78350f,stroke:#f59e0b,stroke-width:2px,color:#f8fafc;

    %% Nodes
    Agent[🤖 AI Agent / IDE Client<br/>Cursor, Claude Code, Windsurf]:::client
    MCP[🔌 RTK MCP Server<br/>rtk mcp start]:::core
    CLI[💻 RTK CLI<br/>rtk symbols, rtk memory]:::core
    
    subgraph DB["🗄️ Unified Local Database (.rtk/rtk.db)"]
        FTS[SQLite FTS5<br/>project_memory]:::storage
        Graph[petgraph Index<br/>symbols & dependencies]:::storage
        Sess[Session State<br/>task tracking]:::storage
        Arts[Artifact Cache<br/>cli log archives]:::storage
    end

    subgraph RAG["🧠 Local Semantic Pipeline"]
        ONNX[Tract ONNX Engine<br/>Local Vector Embeddings]:::model
        Tokenizer[HF Tokenizers<br/>cl100k_base]:::model
    end

    %% Links
    Agent -- "1. MCP Tool Request" --> MCP
    Agent -- "1. CLI Wrappers / Commands" --> CLI
    
    MCP -- "Query / Write" --> DB
    CLI -- "Query / Write" --> DB

    FTS -- "Hybrid Search" --> ONNX
    ONNX --> Tokenizer
    
    CLI -- "Context Compaction" --> Sess
    CLI -- "Clean / GC" --> Arts

Loading

1. AST Code Indexing & Graph (rtk-index)

Instead of parsing files as raw text, RTK indexes your project's syntax tree using Tree-sitter and constructs a code dependency graph using petgraph:

• Symbol Extraction: Automatically extracts structs, classes, functions, and imports for Rust, Python, JavaScript, TypeScript, and Go.
• Blast Radius Impact Analysis: Running rtk symbols find and rtk deps traverses the dependency graph to find all upstream callers and downstream dependencies, identifying exactly what code might break before editing a symbol.
• Minimal Token Representation: Generates skeletal files (rtk pack --skeleton) showing only signatures and docstrings, stripping implementation bodies to save up to 90% of tokens.

2. Model Context Protocol (rtk-mcp)

RTK implements a lightweight, high-performance MCP server built directly into the Rust binary. It exposes 9 tools to AI clients:

• search_code: Hybrid FTS / substring search across the codebase.
• find_symbols: Locate definitions of structs, traits, functions, or classes.
• find_refs: Identify references and call sites of a symbol.
• project_memory: Fetch or save project ports, configurations, and setup decisions.
• artifact_get: Retrieve a cached raw CLI log by ID.
• context_pack: Compact file trees into a token-stripped XML payload.
• session_state: Check or update active tasks and decisions for handoffs.
• get_budget_status: Budget spend and limit (FinOps for self-regulating agents).
• ping: Version and connectivity check.

Blast-radius analysis (rtk impact analyze) is available via CLI, not as an MCP tool.

MCP tool	Default build	Requires --features embeddings
find_symbols, find_refs	yes (AST graph)	no
search_code	yes (FTS / substring)	hybrid ONNX optional
project_memory, session_state, artifact_get	yes	no
context_pack (--skeleton uses Tree-sitter)	yes	no
get_budget_status, ping	yes	no

MCP initialize reports the same version as rtk --version and CARGO_PKG_VERSION (see scripts/release_smoke.sh).

To install the MCP server into Claude Desktop or Cursor:

rtk mcp install --client claude
rtk mcp install --client cursor

3. Hybrid Semantic Search & Memory

RTK combines standard full-text lexical search (SQLite FTS5) with optional local vector search (see Default vs Full build below):

• No Cloud Latency (Full build): Uses tract-onnx and HuggingFace tokenizers to generate embeddings locally on your machine.
• Episodic Memory: Active reasoning steps (stored via rtk think) and setup notes are cross-referenced semantically, allowing the agent to retrieve project state without RAG decay or context bloat.
• Context Compaction: rtk context compact runs an automatic compaction on old session states and consolidates task lists inside session_state, keeping the active token window slim.

Default vs Full build

Capability	Default (cargo install rtk-context-engine)	Full (--features embeddings)
Command filters + DLP	yes	yes
FTS5 memory + rtk pack	yes	yes
Code graph (symbols, refs, impact)	yes	yes
MCP server (rtk mcp start)	yes	yes
Hybrid ONNX vector search	no	yes
GPU backends (CUDA/CoreML/DirectML)	no	optional feature flags

The default release binary matches the Default column. Hybrid search requires building with --features embeddings (and optional onnx-* backends).

---

⚙️ Installation & Setup

See docs/QUICKSTART.md for the full 5-minute path.

1. Requirements: Bash-compatible shell for hooks/aliases; Rust toolchain only if building from source.
2. Install (pick one):
   • crates.io (recommended on Linux/WSL):

     cargo install rtk-context-engine --locked

   • Homebrew (macOS):

     brew tap andreafinazziinfo/rust-context-engine
     brew install rtk

   • Release binary (Windows / Linux): download from GitHub Releases (rtk-windows-amd64.zip or rtk-linux-amd64.tar.gz).
   • From source (WSL dev):

     git clone https://github.com/andreafinazziinfo/rust-context-engine.git
     cd rust-context-engine
     bash install.sh

3. Initialize (in your project):

   rtk init --profile high
   rtk index run
   rtk doctor

   init appends RTK aliases to ~/.bashrc, ~/.zshrc, and ~/.profile, and attempts PreToolUse hook setup.

4. AI / IDE Integration (Click to expand)

For Claude Code (PreToolUse Hook) Add this to your settings.json (~/.claude/settings.json or %USERPROFILE%\.gemini\antigravity\settings.json):

  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bash /absolute/path/to/rust-context-engine/hooks/rtk-rewrite.sh", "timeout": 5000 }]
      }
    ]
  }

For Terminals (Cursor, Aider, Bash/Zsh) If you didn't use the auto-installer, add these aliases to your ~/.bashrc or ~/.zshrc:

alias git="rtk git"
alias cargo="rtk cargo"
alias pytest="rtk pytest"
alias ls="rtk ls"
alias npm="rtk npm"
alias yarn="rtk yarn"
alias pnpm="rtk pnpm"
alias dotnet="rtk dotnet"
alias composer="rtk composer"
alias terraform="rtk terraform"

---

💻 Command Reference

• Input Wrappers (15 tools): rtk git status/diff/log, rtk cargo test/build/check, rtk pytest, rtk docker, rtk npm, rtk yarn, rtk pnpm, rtk composer, rtk terraform, rtk dotnet, rtk gradle, rtk go_test, rtk ls.
• Context Virtualization & Compaction: rtk show-log <id> (reads full uncompressed log), rtk context compact (compresses/compacts active context state), rtk gc (cleans old DB logs and reclaims space).
• Directory Packaging: rtk pack [path] [--strip] [--skeleton] [--limit 50000].
  • --strip: remove single-line comments and collapse blank lines (smaller XML, same semantics).
  • --skeleton: Tree-sitter AST mode — function bodies collapsed to signatures/docstrings (~90% savings on large files).
  • --limit: abort if packed token count exceeds budget (uses count_tokens; optional --features tiktoken in rtk-db for exact BPE).
• Project Memory & Search: rtk memory set <key> <val>, rtk memory get <key>, rtk memory list, rtk memory search <query> (FTS5 keyword search; hybrid ONNX requires --features embeddings).
• Hidden Chain-of-Thought: rtk think (reads from stdin to store reasoning in the FTS5 DB out of the chat context).
• Rules & Profiles: rtk init --profile <low|medium|high|max>, rtk sync-rules (recursively mirrors .cursor/rules to subprojects).
• Command Rewriting: rtk rewrite "<command>" (PreToolUse hook engine: auto-allows, denies, or asks for dangerous commands).
• Configuration: rtk config show, rtk config deny add "<pattern>", rtk config dlp add "<regex>", rtk config export (exports global config to stdout), rtk config import [--path <file>] (imports/overwrites config from a file or stdin).
• PR Cost Estimator: rtk estimate / rtk est (analyzes the active git diff and projects token usage & estimated API costs across top model tiers, showing exact potential savings).
• Telemetry, Stats & Audit: rtk status, rtk stats [--chart] / rtk gain [--chart] (prints shorthand savings metrics and displays a beautiful ASCII cost trend chart), rtk dashboard (live Web UI), rtk audit (aggregates savings metrics, prints summary and writes rtk-audit.md), rtk telemetry export (exports Prometheus-compatible scraping metrics).
• Quality gate (contributors): rtk validate — runs scripts/dev-gate.sh (fmt + clippy + tests) when present in the repo.
• Dynamic Plugins: rtk plugin -- <command> (runs a command using custom rules from plugins.toml).

Personal Configuration & Guardrails (Click to expand)

RTK uses ~/.config/rtk/config.json and local .rtk.json.

• Show config: rtk config show
• Add Guardrail: rtk config deny add "git push.*--force" (Prevents AI from running this).
• Add DLP Regex: rtk config dlp add "MY_API_KEY_[0-9a-zA-Z]{32}" (Redacts custom secrets).
• Export Settings: rtk config export > my_backup.json (Dumps current configuration to a file).
• Import Settings: rtk config import --path my_backup.json or cat my_backup.json | rtk config import (Overwrites settings from stdin or file).

Dynamic Plugins Configuration (plugins.toml) (Click to expand)

To wrap and filter tools not natively supported by RTK core, create a global ~/.config/rtk/plugins.toml or a local ./plugins.toml:

[[plugin]]
bin = "ruff"
drop_prefixes = ["ℹ️", "DEBUG", "Analyzing"]
keep_prefixes = ["Error:", "Found"]

Then run the tool using rtk plugin -- ruff check . (or alias ruff to rtk plugin -- ruff).

Architecture & Workflow (Click to expand)

sequenceDiagram
    actor LLM as AI Agent / Developer
    participant Hook as Shell Hook (PreToolUse)
    participant RTK as RTK CLI
    participant Filter as Filters (15 Modules)
    participant DLP as DLP Redaction
    participant DB as Unified DB (.rtk/rtk.db)
    participant Cmd as Target Command

    rect rgb(30, 60, 100)
    Note over LLM,Cmd: 📥 PHASE 1 — INPUT VIRTUALIZATION
    LLM->>Hook: Execute Command (e.g. cargo test)
    Hook->>RTK: rtk rewrite "cargo test"
    alt Rewrite Matched (Exit 0)
        RTK-->>Hook: Rewritten to rtk cargo test
        Hook->>RTK: Run: rtk cargo test
        RTK->>Cmd: Execute cargo test
        Cmd-->>RTK: Raw Output (1,290 tokens)
        RTK->>Filter: cargo_test::filter()
        Filter-->>RTK: Filtered Output (94 tokens, -92.7%)
        RTK->>DLP: Redact Secrets (API keys, JWT, PEM)
        DLP-->>RTK: Clean Output
        RTK->>DB: Cache raw log in artifacts table (id=42)
        RTK-->>LLM: Filtered Output + [rtk show-log 42]
    else Denied (Exit 2)
        RTK-->>Hook: BLOCKED (e.g. git push --force)
    else No Match (Exit 1)
        Hook->>Cmd: Passthrough original command
    end
    end

    rect rgb(60, 30, 80)
    Note over LLM,DB: 🧠 PHASE 2 — REASONING & MEMORY
    LLM->>RTK: cat <<EOF | rtk think (462 tokens)
    RTK->>DB: Store in project_memory table
    RTK-->>LLM: [Thought offloaded] (16 tokens, -96.5%)
    LLM->>RTK: rtk memory set db_port 5432
    RTK->>DB: Store KV in project_memory
    LLM->>RTK: rtk memory search "database"
    RTK->>DB: FTS5 Search (ONNX optional in full build)
    DB-->>RTK: Matching Entries
    RTK-->>LLM: Relevant Context
    end

    rect rgb(30, 80, 50)
    Note over LLM,Cmd: 📤 PHASE 3 — OUTPUT AUTONOMY
    LLM->>RTK: rtk init --profile high
    RTK->>RTK: Inject Caveman (~75% output reduction)
    RTK->>RTK: Inject Ponytail (~54% less code)
    RTK-->>LLM: AI rules installed in .cursor/rules/
    Note over RTK: check_autonomy() monitors output > 3000 tokens
    end

Loading

Context Directory Packaging (rtk pack)

graph TD
    Start([Run: rtk pack path --strip --skeleton]) --> Canonical[Canonicalize Root Path]
    Canonical --> LoadIgnores[Load Ignore Patterns<br>Defaults + .gitignore + .rtkignore]
    LoadIgnores --> LoadConfig[Load config.json / .rtk.json<br>For DLP patterns]
    LoadConfig --> StartRecurse[Recursively Traverse Directory]
    StartRecurse --> NextEntry{Get Next Entry}
    
    NextEntry -- No More Entries --> End([Output XML Context Block])
    NextEntry -- Has Entry --> CheckIgnore{Matches Ignore Pattern?}
    CheckIgnore -- Yes --> NextEntry
    CheckIgnore -- No --> IsDirectory{Is Directory?}
    
    IsDirectory -- Yes --> RecurseDir[Recurse into Directory] --> NextEntry
    IsDirectory -- No --> IsBinary{Is Binary?}
    IsBinary -- Yes --> NextEntry
    
    IsBinary -- No --> ReadFile[Read Content] --> CheckStrip{--strip?}
    CheckStrip -- Yes --> Minify[Minify: Strip comments/empty lines] --> CheckSkeleton
    CheckStrip -- No --> CheckSkeleton{--skeleton?}
    
    CheckSkeleton -- Yes --> Skeletonize["Collapse function bodies via Tree-Sitter AST"] --> DLPRedact
    CheckSkeleton -- No --> DLPRedact[Apply DLP Redact]
    
    DLPRedact --> WrapXML["Wrap in &lt;file path='...'&gt;&lt;![CDATA[...]]&gt;&lt;/file&gt;"]
    WrapXML --> NextEntry
    End --> CheckLimit{--limit set?}
    CheckLimit -- Yes --> ValidateLimit{Tokens > Limit?}
    ValidateLimit -- Yes --> Error([ERROR: Pack exceeded token limit!])
    ValidateLimit -- No --> Print([Print XML to stdout])
    CheckLimit -- No --> Print

Loading

Unified Project Database Architecture To ensure complete project portability and clean namespace isolation, RTK consolidates all project-level context, logs, and artifacts in a single SQLite database:

• Path: .rtk/rtk.db under the project workspace root.
• Tables Included: project_memory & project_memory_fts (semantic notes), session_state (episodic histories), artifacts (cached uncompressed CLI outputs), symbols & dependencies (Tree-sitter AST code graph indices).
• Global Telemetry: Isolated at ~/.local/share/rtk/rtk.db for multi-project savings aggregates and cost projections.

---

🤖 AI Agent Guide (Readiness & Instructions)

Note

This section is specifically written for AI Coding Assistants to read and follow. If you are an AI agent, you MUST follow these guidelines.

1. Intercepted Commands: Running standard tools (e.g., pytest, cargo test) yields filtered outputs. If a log is truncated, a cache note appears. DO NOT re-run the command to view failures; instead, run rtk show-log <id> to retrieve the raw database record.
2. Context Packaging: DO NOT execute cat on many files. Use rtk pack . --strip to read directories. Pass --limit <max_tokens> to prevent overflows. Use --skeleton to collapse function bodies into API signatures.
3. Long-Term State Memory: Use rtk memory set/get to save project-specific settings (like open ports, DB URLs, architecture decisions) across chat sessions. Use rtk memory search for semantic retrieval.
4. Hidden Chain-of-Thought: When solving complex logic, DO NOT write long reasoning in the chat. Pipe it to rtk think (e.g., cat << 'EOF' | rtk think) to save output tokens, and only print a brief summary to the user.
5. Stale Context Rule: If you modify the project's architecture, you MUST proactively overwrite old rules using rtk memory set <key> <val> to prevent stale RAG context hallucinations.
6. DLP Awareness: RTK automatically redacts API keys, JWT tokens, PEM private keys, and database credentials from all outputs. If you see [REDACTED_API_KEY] or [REDACTED_SECRET], do NOT attempt to reconstruct or guess the original value.
7. Guardrails: RTK blocks dangerous commands like rm -rf /, git push --force, git reset --hard. If your command is denied, respect the guardrail and use a safer alternative.
8. Behavioral Rules: RTK enforces Ponytail and Caveman styles. Implement the minimal amount of code possible. DO NOT write boilerplate, unrequested features, or restructure folders. Keep diffs extremely narrow.

---

🛡️ Known Limitations & Safety Caveats

• Best-Effort DLP Redaction: RTK's Data Loss Prevention (DLP) engine uses pattern matching (regular expressions) and entropy-based heuristics (Shannon entropy scanner) to strip private keys, credentials, and API tokens. While highly effective, no scanner can guarantee 100% secret detection. Avoid writing plain text production secrets in files or terminal commands.
• Alias Bypassing: RTK terminal wrappers rely on shell aliases (e.g., alias git="rtk git"). These wrappers are developer aids to keep context slim, but they are not an OS-level sandbox. The AI agent or a script can bypass RTK by using absolute paths (e.g., /usr/bin/git) or escaping the alias (e.g., \git).
• PreToolUse Hook Support: Transparent rewriting via PreToolUse hook requires support from the AI CLI client (such as Claude Code). If you run another client, ensure you register the suggestion hook in its configuration.
• Hook exit codes: rtk rewrite returns 0 = rewrite found, 1 = passthrough, 2 = denied, 3 = ask user. If hooks silently fail, run rtk doctor and verify hooks/rtk-rewrite.sh path is absolute in settings.json.
• Hook timeout: Claude Code default hook timeout is 5s; increase if rewrite runs on slow disks.

---

🤝 Contributing

See docs/CONTRIBUTING.md — rtk validate, golden fixtures, release checklist, git hooks.

Maintainers: docs/RELEASE.md · Roadmap: docs/ROADMAP.md · Active plan: docs/PLAN_CLOSURE.md (Fase D: real-world use, no new features)

---

🔧 Troubleshooting

• Aliases not loaded: If aliases like git or cargo do not execute rtk, ensure you run source ~/.bashrc or source ~/.zshrc after the installer completes.
• Database is Locked (database is locked): SQLite can temporarily lock the database during concurrent write/read operations. RTK is optimized for low latency, but if this happens, wait a few seconds and run the command again. You can also run rtk gc to clean up old logs.
• WSL Paths on Windows: When running under Windows with WSL, make sure rtk is installed in the WSL environment. If git outputs look raw, check that your WSL shell profiles contain the ALIASES_BLOCK.
• PreToolUse hook not rewriting: Confirm absolute path to hooks/rtk-rewrite.sh in Claude/Gemini settings; run bash hooks/rtk-rewrite.sh manually with RTK_REWRITE_CMD='git status'. Exit 2 means guardrail deny (expected for dangerous commands).
• Stale code index: RTK has no filesystem watcher — after large refactors run rtk index run (also noted by rtk doctor).

---

📄 License

Licensed under the Apache License 2.0.