❌  WITHOUT rtk-sf                      ✅  WITH rtk-sf
─────────────────────────────────────   ─────────────────────────────────────
Claude: "Show me AccountService"        Claude: "Show me AccountService"
  → reads AccountService.cls            → calls query_compressed_spec()
  → reads AccountService.cls-meta.xml  → returns YAML spec instantly
  → reads related trigger files
  → reads test class for context
                                        Tokens consumed:  ~300
Tokens consumed:  ~15,000               Time:             <0.1 s
Time:             ~8 s                  Cost (@$3/1M):    $0.0009
Cost (@$3/1M):    $0.045
                                        Savings per lookup: 98%

┌─────────────────────────────────────────────────────────────┐
│                     Salesforce DX Project                    │
│  force-app/main/default/                                     │
│    classes/AccountService.cls       ← raw: ~4,000 tokens    │
│    objects/Account__c.object-meta.xml                        │
│    flows/OnboardingFlow.flow-meta.xml                        │
└──────────────────┬──────────────────────────────────────────┘
                   │  rtk-sf index
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                      .rtk-sf/                                │
│  registry.json   ← mtime differential tracker               │
│  db.sqlite       ← SQLite FTS5 full-text search             │
│  relations.json  ← nodes + edges graph                      │
│  specs/                                                      │
│    AccountService.yaml  ← compressed: ~300 tokens           │
│    Account__c.yaml                                           │
│    OnboardingFlow.yaml                                       │
└──────────────────┬──────────────────────────────────────────┘
                   │  MCP stdio JSON-RPC
                   ▼
┌─────────────────────────────────────────────────────────────┐
│                        AI Agent (Claude Code)                │
│                                                              │
│  query_compressed_spec("AccountService")  → 300-token YAML  │
│                                             + annotations    │
│  search_codebase("payment processing")   → top 5 matches    │
│  search_codebase("不備修正")              → Japanese OK      │
│  get_relations("AccountService")         → callers + deps   │
│  list_components(type="ApexClass")       → all Apex classes  │
│  annotate_component("Account__c", ...)   → write knowledge  │
└─────────────────────────────────────────────────────────────┘
                   │  optional
                   ▼
┌─────────────────────────────────────────────────────────────┐
│            dist/architecture_map.html  (Cytoscape.js SPA)   │
│                                                              │
│  ● Interactive graph of all components                       │
│  ● Click node → YAML spec in sidebar                        │
│  ● Path highlighting: upstream (amber) / downstream (red)   │
│  ● Full-text search filter                                   │
│  ● Self-contained HTML — no web server needed               │
└─────────────────────────────────────────────────────────────┘

curl -sSL https://raw.githubusercontent.com/furuCRM-Inc/rtk-sf/main/scripts/install.sh | bash

pip install rtk-sf
# With vector re-ranking (optional):
pip install "rtk-sf[vector]"

cd your-salesforce-project
rtk-sf index

rtk-sf indexer starting...
  Project root : /projects/my-org
  Source path  : /projects/my-org/force-app
Indexing complete:
  Indexed : 84
  Skipped : 0 (unchanged)
  Errors  : 0
Synced 84 components into search index.

claude mcp add rtk-sf -- python -m rtk_sf serve

## Code Search — Use rtk-sf First (Required)

| Task | Tool to call |
|---|---|
| Find a component | `search_codebase(query)` |
| Read a spec | `query_compressed_spec(component_name)` |
| Blast-radius check | `get_relations(component_name)` |
| List components | `list_components(type)` |
| Write back discovered logic | `annotate_component(component_name, key, value)` |

Never open raw `.cls` or `.xml` files unless the spec is insufficient.

rtk-sf ui && open dist/architecture_map.html

# Register the MCP server (run once per project)
claude mcp add rtk-sf -- python -m rtk_sf serve

# Verify
claude mcp list

Claude: I need to understand AccountService.
→ [calls query_compressed_spec("AccountService")]
→ Returns 300-token YAML instead of reading the 4,000-token .cls file

Claude: Find all payment-related code.
→ [calls search_codebase("payment processing", limit=5)]
→ Returns ranked list of matching components with snippets

Claude: What calls AccountService?
→ [calls get_relations("AccountService")]
→ Upstream: [OrderTriggerHandler, QuoteController]
   Downstream: [PaymentGateway, EmailService]

# Start the server manually
python -m rtk_sf serve

# The server reads JSON-RPC 2.0 from stdin, writes to stdout
# Protocol: MCP 2024-11-05

rtk-sf ui
# Opens: dist/architecture_map.html
open dist/architecture_map.html

First run  (84 files): ~2.3 seconds
Re-index (3 changed) : ~0.1 seconds

# All of these work — including short Japanese terms
search_codebase("申込")    # 2-char: LIKE fallback → hits Application__c fields
search_codebase("不備")    # 2-char: LIKE fallback → hits DeficiencyReason__c
search_codebase("主任教諭") # 4-char: FTS5 trigram  → hits RT_ChiefTeacher, related fields
search_codebase("管理職")  # 3-char: FTS5 trigram  → hits RT_Management, related fields

# Full Apex class: ~4,000 tokens
# rtk-sf spec: ~300 tokens (92% reduction)

component: AccountService
type: ApexClass
summary: Handles Account CRUD operations and related business logic
methods:
  - name: createAccount
    returns: Account
    params: [String name, String industry]
    description: Creates and inserts a new Account record
  - name: getAccountsByIndustry
    returns: List<Account>
    params: [String industry]
    description: Returns all Accounts matching the given industry
  - name: updateBillingAddress
    returns: void
    params: [Id accountId, Address newAddress]

rtk-sf watch
# Watching: force-app/
# Ctrl+C to stop

rtk-sf index               # Index ./force-app (differential)
rtk-sf index --path ./src  # Custom source directory
rtk-sf index --force       # Force re-index all files

rtk-sf watch               # Live file watcher
rtk-sf watch --path ./src  # Watch custom directory

rtk-sf serve               # Start MCP stdio server

rtk-sf ui                  # Generate dist/architecture_map.html
rtk-sf ui --output ~/map.html  # Custom output path

rtk-sf --version           # Show version
rtk-sf --help              # Show help

# First session: AI reads source and discovers a condition
Agent → [reads ApplicationSubmissionController.cls]
      → finds: if (app.Status__c != '不備') throw AuraHandledException
      → [calls annotate_component(
            component_name = "Application__c",
            key            = "business_rule",
            value          = "Correction (saveApplicationCorrection) only allowed when Status__c = '不備'. Owner check: EligibleStaff__r.Contact__c = current user. After correction, status reverts to '申込済'.",
            source         = "ai_discovery"
         )]

# All future sessions: no source read needed
Agent → [calls search_codebase("correction condition")]
      → returns Application__c with annotation in results

Agent → [calls query_compressed_spec("Application__c")]
      → returns YAML spec PLUS:
         ## Annotations (discovered business logic)
         [business_rule] (ai_discovery · 2026-09-06)
           Correction only allowed when Status__c = '不備'. ...

pip install rtk-sf

pip install "rtk-sf[vector]"

git clone https://github.com/furuCRM-Inc/rtk-sf.git
cd rtk-sf
pip install -e ".[dev]"

rtk-sf/
├── rtk_sf/
│   ├── __init__.py        # Package exports
│   ├── __main__.py        # CLI entry point
│   ├── indexer.py         # Differential parser (Apex, XML, objects)
│   ├── search.py          # SQLite FTS5 + vector hybrid search
│   ├── watcher.py         # OS file watcher (watchdog)
│   ├── mcp_server.py      # MCP stdio JSON-RPC server
│   └── ui_generator.py    # Generates dist/architecture_map.html
├── ui/
│   └── template.html      # Cytoscape.js SPA template reference
├── docs/
│   ├── installation.md    # Platform-specific install guide
│   ├── mcp-integration.md # MCP setup for Claude Code
│   └── roi.md             # Detailed ROI analysis
└── scripts/
    └── install.sh         # One-command setup script

git clone https://github.com/furuCRM-Inc/rtk-sf.git
cd rtk-sf
pip install -e ".[dev]"
pytest