Lens Agent CLI Suite

A compact, unixy suite of agent-grade CLI tools built on top of Lens's SPI, designed for AI agent workflows with strict contracts, reproducibility, and safety measures.

🎯 Project Overview

This suite provides 11 CLI tools (1 library + 10 binaries) that enable reliable, deterministic access to code analysis and transformation capabilities. All tools follow shared contracts with JSONL I/O, deterministic output ordering, and budget enforcement.

Performance Targets

• Search latency: p95 < 120ms for k≤50 queries
• Patch success rate: ≥95% with verification
• Memory budget: ≤256MB per operation
• CPU budget: ≤200ms per operation

📦 Tools

Core Tools

sripgrep - Semantic Search

Ripgrep-like search over Lens SPI with hybrid mode support.

sripgrep "function main" --mode hybrid --token-budget 10000 --budget-ms 200

scontext - Context Pack Builder

Constructs deduped, token-capped packs from refs/queries.

scontext --ref lens://abc123/src/main.rs@def456#B1:10 --token-budget 2000

spatch - Structure-Aware Patching

Applies edit plans under drift using AST+fuzzy+semantic anchoring.

spatch --plan patch-plan.yaml --verify "cargo test" --strict

Analysis Tools

simpact - Change Impact Analyzer

Ranks downstream symbols/files affected by changes.

simpact --target "function_name" --depth 3 --explain

sgraph - Code Graph Queries

Provides deps/rdeps/who-calls/path queries with visualization.

sgraph --query deps --source "main" --output dot

sdiffx - Semantic Diff

AST-aware diff with move/rename detection.

sdiffx old_version.rs new_version.rs --detect-moves --ignore-whitespace

Maintenance Tools

srefactor - Constrained Codemods

Safe rename/extract/reorder with verification.

srefactor rename old_function_name --new-name new_function_name --verify "cargo check"

sdoc - Documentation Surfacer

Assembles docstrings/examples/tests with ranked exemplars.

sdoc function_name --include-examples --max-tokens 1024

sqa - Quick Answers

Extractive Q&A over context packs with citations.

sqa "What does this function do?" --ref lens://... --strict

shealth - Health Guardrail

Health checks, budget enforcement, and degradation detection.

shealth check --component all --enforce-budgets

🚀 Installation

From Source

git clone <repository>
cd lens-agent-cli-suite
cargo build --release
cargo install --path .

Prerequisites

• Rust 1.70+
• Lens SPI service running at http://localhost:3000/v1/spi

🛠 Usage

All tools support common arguments:

# Common options
--spi-url <URL>         # Lens SPI endpoint (default: http://localhost:3000/v1/spi)  
--format <FORMAT>       # Output format: jsonl, json, text (default: jsonl)
--strict                # Fail fast on ambiguity (default: true)
--budget-ms <MS>        # CPU budget in milliseconds (default: 200)
--budget-mb <MB>        # Memory budget in MB (default: 256)
--debug                 # Enable debug tracing
--quiet                 # Suppress non-essential output

Output Format

All tools produce deterministic JSONL output by default:

{"type": "result", "rank": 1, "ref": "lens://...", "score": 0.95}
{"type": "timing", "total_ms": 127, "breakdown": {"search": 45, "rank": 82}}
{"type": "summary", "total_results": 15, "success_rate": 1.0}

🔧 Development

Building

cargo build

Testing

cargo test

Linting

cargo clippy

Documentation

cargo doc --open

📋 Architecture

Shared SDK (lens-cli-sdk)

The shared library provides:

• Lens SPI Client: Async HTTP client with budget enforcement
• Reference Handling: Stable lens:// URI parsing and validation
• Output Formatting: Deterministic JSONL with sorted keys
• Budget Enforcement: CPU/memory/wall-time constraints
• Common Types: Shared data structures and error handling

Tool Architecture

Each tool follows the pattern:

1. Argument Parsing: Clap-based CLI with validation
2. Budget Setup: Resource constraint enforcement
3. SPI Integration: Query Lens backend with retries
4. Processing: Tool-specific logic with error handling
5. Output Generation: Structured JSONL results
6. Verification: Optional verification gates

🎯 Design Principles

Agent-Grade Reliability

• Deterministic Output: Same input produces same output
• Budget Enforcement: Hard limits prevent resource exhaustion
• Error Transparency: Structured error reporting with context
• Verification Gates: Optional validation of operations

Performance-First

• Streaming Processing: Handle large codebases efficiently
• Parallel Operations: Concurrent processing where safe
• Smart Caching: LRU caches for repeated operations
• Budget Awareness: Graceful degradation under constraints

Safety & Security

• Strict Mode: Fail fast on ambiguous operations
• Input Validation: All external input validated
• Reference Stability: Immutable lens:// references
• Verification Hooks: Optional build/test validation

📊 Specification Compliance

This implementation follows the SRF v1.1 specification with:

• ✅ 11 Artifacts: 1 library + 10 CLI tools
• ✅ Performance SLOs: Sub-120ms search, >95% patch success
• ✅ JSONL Contracts: Deterministic output ordering
• ✅ Budget Enforcement: CPU/memory/time constraints
• ✅ Lens SPI Integration: Unified backend communication
• ✅ Verification Gates: Optional validation steps
• ✅ Error Handling: Structured error reporting
• ✅ Test Coverage: Comprehensive test suite

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: cargo test
5. Run clippy: cargo clippy
6. Submit a pull request

Code Standards

• Follow existing code style
• Add comprehensive tests
• Document public APIs with rustdoc
• Use structured error handling
• Maintain backwards compatibility

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🔗 Related Projects

• Lens SPI - Backend indexing service
• Tree-sitter - Parser generator for AST operations

---

Built for AI agents, by AI agents 🤖