feat: add 'search' subcommand and document features in README

Author: dudegladiator

README.md

@@ -2,13 +2,23 @@
 
 Interactive terminal UI for browsing, searching, and surgically editing Claude Code session JSONL files.
 
-Claude Code persists conversations as JSONL under `~/.claude/projects/<slug>/<uuid>.jsonl`. Built-ins only support rewind, clear, and compact. `cc-session` lets you:
-
-- Browse and search every session across all projects.
-- Open any session and view messages with role, text, token count, timestamp.
-- Delete individual messages, ranges, from-top, or from-bottom.
-- Auto-pair tool_use and tool_result blocks so you never orphan one half.
-- Save atomically with a `.bak` backup — and refuse to save when Claude Code holds the file open.
+Claude Code persists conversations as JSONL under `~/.claude/projects/<slug>/<uuid>.jsonl`. Built-ins only support rewind, clear, and compact. `cc-session` fixes that.
+
+## Features
+
+- **Session browser** — every session across every project, sorted by recency, with project, title, modified time, size, and full UUID.
+- **Fuzzy search** — same engine as fzf/Helix (`nucleo-matcher`), searches project + title, ranks by score.
+- **Message viewer** — shows only real user/assistant text by default; system messages, tool blocks, attachments, and harness wrappers (`<bash-input>`, `<system-reminder>`, etc.) are hidden but preserved on disk.
+- **Edit a session** — open any session and surgically edit it.
+- **Delete individual messages** — pick one and drop it.
+- **Delete ranges, from-top, from-bottom** — bulk trim by range, prefix, or suffix.
+- **Turn-level auto-pair** — deleting a user message also deletes its assistant response (and vice versa). Marking any message in a turn deletes the whole turn cleanly.
+- **tool_use ↔ tool_result safety** — tool calls always travel with their results, so resume never breaks.
+- **Token counts per message** — tiktoken `cl100k_base`, with `usage` metadata as fallback when present.
+- **Atomic save with `.bak` backup** — write `.tmp`, fsync, rename. Backup written every save.
+- **Concurrent-open detection** — `lsof` check refuses to save while Claude Code holds the file. Override with `--force`.
+- **LLM-friendly non-interactive CLI** — `list`, `search`, `show`, `info`, `delete` subcommands with `--json` output. Other agents (Claude Code, Codex, scripts) can drive every action a human can.
+- **Cross-platform** — macOS and Linux. Windows lsof equivalent deferred.
 
 ## Install
 
@@ -59,12 +69,12 @@ cc-session --version
 Every operation is also available as a subcommand with structured output, so other agents (Claude Code, Codex, scripts, CI) can drive the editor without a human at the terminal.
 
 ```sh
-cc-session list --json [--project <slug>] [--limit N]
-cc-session show <id-or-path> [--json] [--full] [--include-hidden]
-cc-session info <id-or-path> [--json]
+cc-session list   [--json] [--project <slug>] [--limit N]
+cc-session search <query> [--json] [--limit N]
+cc-session show   <id-or-path> [--json] [--full] [--include-hidden]
+cc-session info   <id-or-path> [--json]
 cc-session delete <id-or-path> --indices 3,5,7 [--from-top N] [--from-bottom N] [--range lo..hi] [--dry-run] [--force] [--json]
 ```
-
 `<id-or-path>` accepts a full path, a session UUID, or a unique substring of one. Indices are 0-based positions in the raw JSONL (use `cc-session show --json` to map text → index). Auto-pair always extends the delete set to keep `tool_use`/`tool_result` blocks together; `paired_added` in the output reports what was added.
 
 ### Example LLM workflow

src/cli.rs

@@ -74,6 +74,35 @@ pub fn list(
     Ok(())
 }
 
+pub fn search(projects_dir: &Path, query: &str, limit: Option<usize>, json: bool) -> Result<()> {
+    let entries = scan::scan(projects_dir)?;
+    let mut hits: Vec<&SessionEntry> = crate::search::fuzzy_filter(&entries, query);
+    if let Some(n) = limit {
+        hits.truncate(n);
+    }
+    if json {
+        let out: Vec<ListItem> = hits.iter().map(|e| list_item(e)).collect();
+        println!("{}", serde_json::to_string_pretty(&out)?);
+    } else {
+        println!(
+            "{:<40} {:<50} {:<17} {:<10} id",
+            "project", "title", "modified", "size"
+        );
+        for e in &hits {
+            println!(
+                "{:<40} {:<50} {:<17} {:<10} {}",
+                truncate(&e.project_slug, 40),
+                truncate(&e.title, 50),
+                format_mtime(e),
+                human_size(e.size),
+                e.session_id
+            );
+        }
+        println!("\n{} match(es)", hits.len());
+    }
+    Ok(())
+}
+
 fn list_item(e: &SessionEntry) -> ListItem {
     ListItem {
         project: e.project_slug.clone(),

src/main.rs

@@ -41,6 +41,17 @@ enum Command {
         #[arg(long)]
         limit: Option<usize>,
     },
+    /// Fuzzy search sessions by project + title. Same matcher the TUI uses.
+    Search {
+        /// Query string. Subsequence match, case-insensitive.
+        query: String,
+        /// Limit output to N best matches.
+        #[arg(long)]
+        limit: Option<usize>,
+        /// Output JSON.
+        #[arg(long)]
+        json: bool,
+    },
     /// Show messages in a session.
     Show {
         /// Session id (uuid), file path, or substring of either.
@@ -103,6 +114,9 @@ fn main() -> anyhow::Result<()> {
             json,
             limit,
         }) => cli::list(&projects_dir, project.as_deref(), json, limit),
+        Some(Command::Search { query, limit, json }) => {
+            cli::search(&projects_dir, &query, limit, json)
+        }
         Some(Command::Show {
             target,
             include_hidden,