DOCSEARCHbyAlgolia
Submit Docs

coding-agent-search (cass)

repository·main·Indexed 21 days ago

https://github.com/dicklesworthstone/coding_agent_session_search

A high-performance TUI and machine API (version 0.6.23) that indexes and searches local histories from various coding agents such as Claude Code, Cursor, and Aider into a unified timeline. It features lexical, semantic (via MiniLM), and hybrid search modes, a dedicated "Robot Mode" for agent automation, and tools for session management, HTML export, and multi-machine synchronization via SSH/rsync.

Tokens
183.9K
Snippets
450
Records
730
Agent score
75%

What's inside coding-agent-search

  1. What is coding-agent-search (cass)?

    main

    Overview

    cass (coding-agent-search) is a tool designed to unify the fragmented history of various AI coding agents (such as Claude Code, Cursor, Copilot, and Aider) into a single, searchable knowledge base.

    Key Capabilities

    • Normalization: Converts disparate agent storage formats (JSONL, SQLite, Markdown, etc.) into a common schema.
    • Unified Search: Provides a single interface to search across all agent histories, regardless of the original tool used.
    • Semantic Search: Supports optional local ML-powered semantic search to complement fast lexical search.
    • Privacy-First: All indexing and searching are performed locally; no data is sent to external servers.

    Use Cases

    • Individual Developers: Quickly retrieve solutions or debugging steps from past sessions.
    • Teams: Create a shared repository of institutional knowledge from different agent tools.
    • AI Agents: Enable current agents to learn from previous sessions using cass's "Robot Mode."

  2. Overview of `cass` (coding-agent-search)

    main

    What is cass?

    cass (coding-agent-search) is a unified TUI/CLI tool designed to index and search local coding agent session histories. It provides a way to recover and query historical context from AI agent interactions.

    Key Features

    • Search Modes: Supports multiple search modes, including hybrid-preferred (lexical search with semantic refinement).
    • Connectors: Ships with 18 different connectors for various data sources.
    • Analytics: Includes 7 different analytics views.
    • UI/UX: Features 18 themes, a command palette, and a TUI (Terminal User Interface).
    • Advanced Capabilities: Supports multi-machine SSH sync, encrypted HTML export, and a web publishing platform.

  3. Review the Third Simplification Loop Dashboard

    main
    The Third Simplification Loop Dashboard provides a summary of a specific refactoring run (e.g., 20260425T154730Z-third-simplify). It tracks the progress of a specific skill (such as simplify-and-refactor-code-isomorphically), the number of completed passes, and the overall status of the run. This dashboard is useful for auditing the history and verification steps of a complex refactoring session.

  4. Understand CASS Indexing Performance Benchmarks

    main

    The CASS_INDEXING_HISTORICAL_BENCHMARK_RESULTS documentation tracks historical performance optimizations for the coding_agent_search indexer. It uses a custom runner harness (/tmp/cass_runner_r59) to measure wall clock time, conversions per second (Conv/s), messages per second (Msg/s), and database throughput (DB MiB/s) across different indexing strategies.

    Key performance metrics tracked include:

    • Rebuild ms: Time spent rebuilding.
    • Message Stream ms: Time spent in the message stream processing.
    • Prepare/Add/Commit ms: Breakdown of the database operation phases.
    • Finish Conversation ms: Time spent finalizing a conversation grouping.

    Developers looking to optimize the indexer should refer to these historical results to avoid regressing on previously rejected or accepted micro-optimizations.

  5. Core architecture of `cass`

    main

    The cass project is a Rust-based CLI and TUI (Terminal User Interface) designed for managing coding-agent sessions. Its architecture includes:

    • Connector Discovery: Identifying available session sources.
    • Storage: frankensqlite for session data.
    • Indexing: frankensearch for lexical and semantic search capabilities.
    • Robot JSON Contracts: Structured machine-readable interfaces.
    • Remote Sync: Synchronizing histories.
    • Model Management: Handling agent models.
    • Diagnostic/Self-healing Surfaces: Tools for system health and recovery.

  6. Planned CLI features for human users and diagnostics

    main

    The cass roadmap includes several features designed to improve the developer experience for human users and simplify troubleshooting:

    Display & Context:

    • --display <table|lines|markdown>: Provides different human-readable output formats.
    • -C <context>: Adds context around matches (similar to grep).
    • cass export: A command to export search results to Markdown.

    Advanced Querying:

    • Boolean Queries: Support for AND, OR, NOT, and quoted phrases.
    • Field Syntax: Inline field:value syntax for targeted searches.

    Diagnostics & DX:

    • cass diagnose: A command to run health checks and self-service troubleshooting.
    • Shell Completions: Dynamic shell completions for improved command-line ergonomics.

  7. Understand the Repeated Simplification Dashboard

    main

    The Repeated Simplification Dashboard is an artifact generated by an automated agent process (specifically using the simplify-and-refactor-code-isomorphically skill). It provides a structured summary of a multi-pass refactoring loop.

    Key components of a dashboard include:

    • Summary Table: Lists each pass, the mission (goal) of that pass, the number of files affected, the key code change made, and the resulting commit hash.
    • Metrics: Tracks the success of the loop, including pass completion rates, productive vs. zero-change passes, and whether the code passed compilation (cargo check), linting (cargo clippy), and formatting (cargo fmt) gates.
    • Verification: Lists the specific commands and tests executed to validate the changes (e.g., rustfmt, cargo test, cargo clippy).
    • Stop Reason: Explains why the agent stopped the loop (e.g., reaching a pass cap or finding no more high-value refactoring candidates).

  8. Review Pre-Migration Baseline Metrics

    main

    This document provides a performance and quality baseline for the coding_agent_session_search project as of 2026-02-19. It is used to compare subsequent versions against this state to measure regressions in binary size, test coverage, code quality, line counts, benchmark latencies, and search quality.

    Key baseline components include:

    • Binary Size: ~33.94 MB (Release build with opt-level = "z", LTO, and stripped).
    • Test Suite: ~3,635 tests passed (Unit, Connector, Search, E2E, and CLI index tests).
    • Code Quality: Clean Clippy and rustfmt status.
    • Benchmarks: Latency data for Cache, Crypto, Database, and Export operations.
    • Search Quality: Scoring for 10 representative queries.

  9. Overview of the cass architecture

    main
    The cass (coding-agent-search) tool is a Rust-based CLI and TUI designed to index local and remote coding-agent conversation histories. It normalizes these histories into a shared model, persists them to a SQLite database using frankensqlite, and provides multiple interfaces for interaction: a human-friendly TUI, a command-line interface, and a machine-readable JSON API (robot mode).

  10. Understand the CASS Lexical Rebuild Hotspots

    main

    Based on historical benchmarking, the primary performance bottleneck in the CASS lexical rebuild is not the initial prepare phase or the conversation_list materialization, but rather the message scan/merge window (the message_stream_ms phase).

    • Initial Prepare: Typically accounts for a small fraction of time (e.g., ~0.4s).
    • Conversation List: Materializing the conversation envelope vector is relatively inexpensive (e.g., ~0.3s).
    • Message Stream: This is the dominant cost center, often consuming the majority of the wall-clock time (e.g., ~57-58s in a ~64s run).

    Optimization efforts should focus on reducing per-message callback and merge overhead within the message scan path.

  11. Understand the Pack Object Schema

    main

    A pack is a deterministic display scaffolding built from selected evidence. It is not an LLM-generated summary, but a structured object designed for consistent presentation.

    Key components include:

    • title: The normalized query or an explicit issue title.
    • answer_outline[]: A list of evidence-cluster headings, each containing a rank, a heading (derived from matched terms and labels), and evidence_ids.
    • source_summary[]: Statistics on the sources used, including session_count, evidence_count, and healthy status.
    • handoff[]: Extractive next-step bullets (e.g., fact, decision, blocker, next_step, or open_question) paired with evidence_ids.

  12. Optimize Message Streaming via Grouped Scans

    main

    To improve indexing throughput, CASS uses grouped message streaming. Instead of streaming one callback per individual message row, the system stores one callback per conversation.

    This approach reduces the overhead of the message scan/merge window. For example, moving from a standard scan to a grouped stream can improve wall-clock time by approximately 1.6% and increase throughput to ~74k messages/sec.