@arthurpcd/csesh

v4.2.0

Published

a day ago

Navigate, search, analyze, and clean up Claude Code sessions

0High
0Medium
0Low

arthurpcd

claude claude-code sessions csesh cli dashboard analyzer cleanup npx

The problem

Claude Code stores every conversation as a JSONL file. After a few weeks, you have dozens of sessions. After a few months: hundreds.

Which session had the auth refactor?
How much did those 300 sessions cost?
Which ones are empty junk and which ones are real work?
How do I resume that session from two weeks ago?

There was no tool to answer these questions. Now there is.

npx @arthurpcd/csesh web

That's it. One command, no install, no config. The dashboard opens in your browser.

Why csesh

| | Before csesh | With csesh | |---|---|---| | Find a session | Open JSONL files in VSCode, scroll through raw JSON | csesh search "refactor auth" -- instant results | | Know your costs | No idea | csesh cost -- today, this week, this month, all-time with sparkline | | Clean up junk | Delete manually, hope you don't lose something | 4-tier auto-classification, safe trash with restore | | Resume a session | Copy-paste a UUID from a file path | csesh rename + csesh resume -- picker with names you chose | | Dependencies | -- | 0. Zero npm dependencies. Zero CDN. Zero tracking. |

Quick Start

# Run directly (no install needed)
npx @arthurpcd/csesh web

# Or install globally
npm install -g @arthurpcd/csesh
csesh web

# Or install as a Claude Code skill via skills.sh
npx skills add ArthurPcd/csesh

The dashboard opens at http://localhost:3456.

What's new in v4.2.0

Non-minified vendor files — Chart.js, marked, and DOMPurify are now shipped as readable, prettified source for supply chain transparency
Code of Conduct — Contributor Covenant v2.1 added
Improved security scores — no more .min.js files flagged by Socket/Snyk audits

What's new in v4.1.0

Wider activity heatmap — 70/30 split gives the heatmap more room to breathe
Stacked top section — heatmap (365d) + activity (30d) on the left, Top Sessions on the right, same height
Token Breakdown chart — doughnut showing input/output/cache read/cache write proportions
Cost by Project fixed — now computed server-side with client-side fallback
Classify & Clean workflow — documented end-to-end flow: analyze → cleanup --dry-run → cleanup, with tag/title follow-ups
Claude Code skill integration — SKILL.md now documents the full classify/clean workflow so Claude Code knows how to orchestrate it

What csesh does

Classify

Every session is automatically assigned a tier:

| Tier | Label | What it means | |:---:|---|---| | 1 | Auto-delete | Empty, hook-only, snapshot. 100% safe to remove. | | 2 | Suggested | Short, abandoned. Quick review recommended. | | 3 | Review | Mixed signals. Manual review needed. | | 4 | Keep | Real work happened here. |

The classifier is conservative -- it promotes borderline sessions to "keep" rather than risk losing real work. You can override any tier manually.

Analyze

csesh analyze <id>

  Deep Analysis: Fix login bug

  Tier:           [keep]
  Turn count:     47
  Tool calls:     156 (3 failed)
  Thinking:       28 blocks, 41,203 chars
  Files touched:  12
  Language:       en
  Auto-tags:      #bugfix #auth #typescript

  Tool Breakdown:
    Edit              52  ████████████████████
    Read              38  ██████████████
    Bash              31  ████████████
    Grep              22  ████████
    Glob              13  █████

Search

csesh search "docker migration"
csesh search "refactor" --project myapp --from 2025-01-01

Full-text search across all your sessions. Instant results.

Rename & Resume

The killer feature. csesh is the only tool that syncs session names with claude --resume.

csesh rename
#  Interactive picker — select a session, type the new name
#  agile-fluttering-turing → fix-login-bug
#  Now visible in claude --resume as fix-login-bug

csesh rename a1b2c3d4 "Fix login bug"
#  Or rename directly by ID

csesh resume
#  Pick from a list with tier badges, tags, and project info
#  cd's into the project directory and launches claude --resume

Under the hood: writes a custom-title record in the JSONL file so claude --resume displays your renamed title natively. Backup + atomic write -- your original data is always safe.

Track costs

csesh cost

  ⬡ csesh — Cost Breakdown

  ┌────────────────────┬──────────────┬────────────┐
  │ PERIOD             │ COST         │ SESSIONS   │
  ├────────────────────┼──────────────┼────────────┤
  │ Today              │ $12.34       │ 5          │
  │ This week          │ $89.21       │ 23         │
  │ This month         │ $342.17      │ 74         │
  │ All time           │ $1,627.54    │ 312        │
  └────────────────────┴──────────────┴────────────┘

  Last 14 days: ▁▂▃▁▅▂▁▃▇▁▂█▃▁

Classify & Clean

The full workflow to organize and clean up sessions:

csesh analyze                 # deep analysis + auto-classify all sessions
csesh cleanup --dry-run       # preview what would be trashed
csesh cleanup --tier1-only    # remove tier 1 (100% safe)
csesh cleanup                 # interactive: prompts per tier

After analyzing, tag and title the sessions worth keeping:

csesh tag <id> bugfix         # tag important sessions
csesh title <id> "Fix auth"   # name unnamed sessions
csesh web                     # visual review in the dashboard

Nothing is ever deleted directly. Everything goes to trash with a manifest. Restore anytime with csesh trash restore <id>. The dashboard automatically reflects classification — the Refresh button re-fetches and re-classifies all sessions.

Web dashboard

csesh web launches a full interactive dashboard:

10 stat cards with cost tracking and weekly comparison
Activity heatmap (365 days) + activity chart (30 days) stacked alongside Top Sessions
7 charts: model distribution, token breakdown, tier distribution, cost over time, cost by project, top tools, top files
Session table with sort, filter, batch operations
Detail view with full conversation, Markdown rendering, syntax highlighting, collapsible thinking blocks
In-conversation search: find specific messages with text highlighting, match navigation, and display modes (Cmd+F)
Resume from dashboard: copy-paste claude --resume commands or open directly in terminal
Custom title sync: renamed sessions appear natively in claude --resume picker
Streamer mode: blur sensitive paths for screen recordings
Dark/light/auto theme
Keyboard shortcuts: j/k navigate, g dashboard, Cmd+F search in conversation, f favorite, t trash

Everything runs locally on 127.0.0.1. No external requests. The three front-end libraries (Chart.js, marked, DOMPurify) are vendored locally.

Zero dependencies

$ npm ls
@arthurpcd/[email protected]
└── (empty)

csesh has zero npm dependencies. The three libraries that most CLI tools depend on -- chalk, cli-table3, commander -- are replaced by native modules:

| What | Was | Now | Lines | |---|---|---|---:| | Terminal colors | chalk (72 KB) | lib/colors.js -- ANSI escape codes + Proxy | 55 | | Table formatting | cli-table3 (68 KB + 5 transitive deps) | lib/table.js -- UTF-8 box drawing | 120 | | CLI parsing | commander (220 KB) | lib/cli.js -- util.parseArgs native | 270 |

Why it matters:

npx @arthurpcd/csesh web resolves in under 2 seconds on a cold machine
Zero supply chain attack vectors (cli-table3 pulled @colors/colors, the fork of the sabotaged colors.js)
npm audit has nothing to audit
No node_modules bloat, no transitive dependency surprises

Full CLI Reference

| Command | Description | |---|---| | csesh list | List sessions (filter by tier, tag, project, favorites) | | csesh show <id> | Full session detail with metadata, tokens, cost | | csesh analyze [id] | Deep analysis: tools, thinking, files, auto-tags | | csesh search <query> | Full-text search with project and date filtering | | csesh stats | Aggregated statistics across all sessions | | csesh cost | Cost breakdown: today / week / month / all-time + sparkline | | csesh cleanup | Interactive trash by tier (dry-run available) | | csesh resume | Interactive picker to resume a session in Claude Code | | csesh rename <id> <title> | Rename session slug (syncs with claude --resume) | | csesh tag <id> <tag> | Add a tag to a session | | csesh title <id> <title> | Set a custom display title | | csesh export | Export as JSON, CSV, or Markdown | | csesh web | Start the web dashboard | | csesh doctor | Health check: Claude dir, cache, metadata, versions | | csesh trash list\|restore\|delete\|empty | Manage trashed sessions | | csesh cache clear\|stats | Manage the scan cache |

All commands support --json for machine-readable output. Use --help on any command for full options.

Architecture

bin/csesh.js            CLI entry point (zero external dependencies)

lib/
  scanner.js            JSONL parser: fast mode (headers) + full mode (deep analysis)
  classifier.js         4-tier engine: weighted signals, conservative promotion
  analyzer.js           Tool usage, thinking metrics, auto-tags, language detection
  cache.js              Disk cache keyed by file path + mtime + size
  metadata.js           Sidecar store: titles, tags, favorites, notes
  rename.js             JSONL slug rewriter (backup + atomic write)
  cleanup.js            Trash with manifest restore, never direct delete
  search.js             Full-text search, filtering, sorting
  stats.js              Aggregated statistics and cost estimation
  cli.js                Native CLI framework (util.parseArgs)
  colors.js             Native ANSI colors (Proxy-based)
  table.js              Native table formatter (UTF-8 box drawing)
  utils.js              Shared constants and helpers
  config.js             Configuration loader

web/
  server.js             Native Node.js HTTP server (http.createServer)
  dashboard.html        Single-file dashboard (vanilla HTML/CSS/JS)
  vendor/               Chart.js, marked, DOMPurify (vendored, no CDN)

skills/csesh/
  SKILL.md              skills.sh integration (Claude Code agent skill)

Data safety principles

Original JSONL files are never deleted. Cleanup moves to trash with a manifest.
Metadata is stored in a sidecar. Titles, tags, favorites, notes live in metadata.json, not in the JSONL.
Rename creates a backup. csesh rename writes a .bak before modifying the slug, using atomic write (temp + rename).
Uninstall leaves no trace. Remove csesh and your Claude Code data is exactly as it was.

REST API

The web server exposes a full REST API at http://localhost:<port>/api/.

| Method | Path | Description | |--------|------|-------------| | GET | /api/sessions | List sessions. Params: project, tier, tag, favorite, sort, q, limit, offset | | GET | /api/sessions/:id | Session detail (triggers deep analysis if not cached) | | GET | /api/sessions/:id/messages | Conversation messages with rich content blocks | | PATCH | /api/sessions/:id/meta | Update title / notes (also renames JSONL slug) | | POST | /api/sessions/:id/tags | Add a tag | | DELETE | /api/sessions/:id/tags/:tag | Remove a tag | | POST | /api/sessions/:id/favorite | Toggle favorite | | POST | /api/sessions/:id/tier | Override tier (1--4) | | GET | /api/stats | Aggregated statistics | | GET | /api/projects | Project breakdown | | GET | /api/search | Full-text search. Param: q | | GET | /api/tags | All known tags | | POST | /api/trash/:id | Trash a session | | POST | /api/batch/trash | Batch trash { "ids": [...] } | | POST | /api/batch/tag | Batch tag { "ids": [...], "tag": "..." } | | POST | /api/batch/trash-delete | Batch permanent delete from trash | | POST | /api/batch/restore | Batch restore from trash | | GET | /api/trash | List trashed sessions | | POST | /api/restore/:id | Restore from trash | | DELETE | /api/trash/:id | Permanently delete from trash |

Security

Binds to 127.0.0.1 only -- the dashboard is never exposed to the network
CORS strict -- only same-origin requests accepted
Body limit -- 1 MB max request body
DOMPurify -- all HTML sanitized before rendering
No CDN, no external requests -- everything served from local vendored files
npm Trusted Publishing -- published via GitHub Actions OIDC (no stored tokens)

Configuration

Create config.json in the tool directory to override defaults:

{
  "webPort": 3456,
  "scanMode": "fast",
  "defaultSort": "date",
  "pageSize": 50
}

Community

GitHub Discussions — feature requests, Q&A, feedback
skills.sh — install csesh as a Claude Code agent skill

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 -- see LICENSE.