Skip to content

AGENTS.md

Latest commit

 

History

History
126 lines (95 loc) · 4.59 KB

AGENTS.md

File metadata and controls

126 lines (95 loc) · 4.59 KB
Raw

CCS - Claude Code Search

Overview

CLI tool to search and resume Claude Code conversations using a bubbletea TUI.

Development

Build & Test

go build
go test -v -cover

Test Coverage

  • Target: 60%+ statement coverage
  • Current: ~69%
  • All new features must include tests
  • Break logic into testable functions when possible
  • Refactor for testability (e.g., use variables instead of functions for dependency injection)

Run locally

./ccs                    # search recent (60 days, <1GB files)
./ccs <query>            # search with initial query
./ccs --max-age=7        # last 7 days only
./ccs --all              # include everything
./ccs -- --plan          # pass flags to claude
./ccs prune --dry-run    # preview lossless size reduction of large files

Release Process

  1. Update version in main.go:

    const version = "X.Y.Z"

  2. Commit changes:

    git add -A && git commit -m "feat/fix: description"

  3. Push and tag:

    git push
git tag vX.Y.Z
git push origin vX.Y.Z

  4. CI will run tests, then release via GoReleaser and update Homebrew tap

Version Bumping

  • Patch (0.0.X): Bug fixes, minor tweaks
  • Minor (0.X.0): New features, backwards compatible
  • Major (X.0.0): Breaking changes

Architecture

  • main.go - Single file containing all logic
  • main_test.go - Unit tests
  • .goreleaser.yaml - Release configuration
  • .github/workflows/test.yaml - CI test workflow (reusable)
  • .github/workflows/release.yaml - Release workflow (calls test.yaml)

Dependencies

  • github.com/charmbracelet/bubbletea - TUI framework
  • github.com/charmbracelet/bubbles/textinput - Text input component
  • github.com/charmbracelet/lipgloss - Styling

Key Types

  • Conversation - Parsed conversation with messages, timestamps, cwd
  • Message - Single message (role, text, timestamp)
  • listItem - Display item with conversation and search text
  • model - Bubbletea application state (includes delete confirmation state)

Key Functions

  • getConversations(cutoff, maxSize) - Loads conversations from ~/.claude/projects/ with filters
  • parseConversationFile(path, cutoff, maxSize) - Parses JSONL files, skips by mtime/size
  • buildItems() - Creates list items with searchable text
  • initialModel() - Sets up bubbletea TUI
  • Update() - Handles keyboard/mouse input, including delete confirmation
  • View() - Renders the TUI with delete confirmation prompt
  • renderPreview() - Renders conversation preview with highlights
  • previewLines() - Memoised buildPreviewLines for the selected conversation (rebuilt only when selection/query changes), avoids per-frame rescans of huge conversations
  • hitCount() / countHits() - Memoised per-query HITS count (messages containing the query), keyed by SessionID, so formatListItem doesn't rescan every visible row each frame
  • formatListItem() - Formats a single list row
  • deleteConversation() - Removes conversation file and updates UI state
  • pruneConversation() - Prunes the selected conversation in place (Ctrl+R) and refreshes its size
  • getTopic() - Extracts first user message as topic
  • pruneFile() / pruneStream() - Shrink a conversation by dropping duplicate/redundant data (never touches user/assistant lines)
  • runPrune() - ccs prune subcommand driver

TUI Layout

  ccs · claude code search    Resume:Enter Delete:Ctrl+D Prune:Ctrl+R Scroll:Ctrl+J/K Exit:Esc
  > type to search...                                                     (N/total)

  DATE              PROJECT               TOPIC                       MSGS  HITS    SIZE
──────────────────────────────────────────────────────────────────────────────────────
  2024-01-08 15:04  project-name          ✎ Refactor auth flow          42     3   1.2GB
> 2024-01-08 14:30  selected              This one is selected          28     1    12MB
──────────────────────────────────────────────────────────────────────────────────────
Project: /path/to/project
Session: abc123...

    2024-01-08 12:00 User:
    message text here...

    2024-01-08 12:01 Claude:
    response text here...

Conventions

  • Use conventional commits (feat:, fix:, docs:, etc.)
  • Run tests before releasing
  • Keep it simple - single file is fine for this project