Skip to content

feat: Session history viewer (aggregate & search past CLI agent conversations) #83

@SherlockSalvatore

Description

@SherlockSalvatore

Hi @RealZST,

I'd like to implement a session history manager/viewer feature for HarnessKit. I wanted to align with you on the overall design direction and scope before diving into development. My proposed design ideas are as follows:

Summary

Add a Sessions view to HarnessKit: aggregate local conversation logs written by CLI agents (Claude Code, Codex, Gemini) and allow users to browse, search, and resume them from one unified interface.

Motivation

CLI agents store their conversation sessions locally in distinct paths and formats (e.g., ~/.claude/projects/**.jsonl, ~/.codex/sessions/rollout-*.jsonl, ~/.gemini/tmp/*/chats/session-*.json).

Finding or reviewing a specific conversation from yesterday across different workspace projects is currently tedious. HarnessKit already resolves agent root directories via AgentAdapter, making it the perfect central hub to aggregate and search this data.

Scope (M1)

  • Scan & Aggregate: Scan sessions across claude / codex / gemini (file-based agents). Roots are dynamically resolved via adapter.base_dir().
  • Filtering: Dual dropdown filters for Agent and Project (derived from project CWD or metadata).
  • Search (SQLite FTS5): Add an incremental full-text search index in SQLite (session_messages_idx) mapping message contents. This enables sub-millisecond search across massive project histories with match snippets and keyword highlighting in the list view (similar to Mubu search).
  • Detail & TOC Jump: Render lazy-loaded conversation timelines. Features a table of contents to jump to specific user prompts using smooth native scrollIntoView (zero new dependencies).
  • Editable Titles: Store custom titles in HarnessKit's sidecar SQLite table (session_overrides), leaving original agent files completely untouched.
  • Soft Archiving: Allow users to "delete" (hide) sessions from the list view via a soft archive flag in SQLite without modifying or deleting physical files.
  • Incremental GC: Automatically prune index/override records in SQLite if their corresponding physical files are deleted on the disk.
  • Resume: One-click action to copy the <agent> --resume <id> command.

Non-goals (deferred to M2)

  • Physical deletion of agent files (fs::remove).
  • One-click terminal execution (which requires platform-specific osascript or macOS Automation permissions).
  • SQLite-backed agents (Hermes/Openclaw/Opencode).

Design & Architecture

  • Read-Only on Agent Files: No write operations occur on the agent's raw JSON/JSONL directory. All custom titles and archive states reside safely in HarnessKit's SQLite db.
  • Parsers: Native Rust parsers ported from the MIT-licensed cc-switch (no new Rust crate dependencies; uses existing regex/chrono/serde_json).
  • Frontend: Follows existing HarnessKit UI/UX conventions (Zustand store, modal, toast).

Would you accept this feature? I'd love to align on the scope before opening a PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions