csesh

Session manager for Claude Code — search, track, and organize your sessions.

The Problem

Claude Code is a powerful tool, but it generates sessions at a pace that quickly becomes unmanageable. After a few weeks of daily use, you end up with hundreds of sessions stored as UUID-named directories with no search capability, no cost tracking, and no way to find "that conversation where I fixed the auth bug last Tuesday."

The built-in session management is minimal by design — Claude Code focuses on the coding experience, not on what happens to sessions after they end. There is no way to search across session content, no way to see how much each session cost, and no safe way to clean up old sessions without risking the deletion of something important.

For developers who use Claude Code as their primary development tool, this is a real friction point. You accumulate gigabytes of session data, lose track of valuable conversations, and have no visibility into your usage patterns or spending.

Our Solution

csesh is JP.Studio's first open-source contribution — a CLI tool that brings structure and searchability to Claude Code sessions. It was born from our own frustration managing sessions across multiple projects, and we released it under the Apache-2.0 license because every Claude Code user faces the same problem.

Key Features

• Full-text search across all sessions and projects. Find any conversation by keyword, instantly — no more digging through UUID directories.
• Cost and usage tracking per session, per project, per day. Know exactly how much you are spending and where.
• Auto-classification by quality tier. Sessions are automatically categorized (exploration, deep work, debugging) based on duration and interaction patterns.
• Safe deletion with trash manifest. Deleted sessions are logged with metadata for recovery, so you never permanently lose something by accident.
• Web dashboard on localhost:3456 with activity graphs, cost breakdowns, and session timelines.

Design Philosophy

csesh follows a zero-dependency approach. No npm bloat, no supply chain risk — every component is hand-written. The tool is privacy-first: it binds exclusively to localhost, enforces CORS restrictions, collects zero telemetry, and stores all data locally. Your session data never leaves your machine.

Architecture

csesh is built as a CLI-first tool with an integrated web dashboard — two interfaces to the same underlying session engine.

The CLI reads Claude Code's local session storage directly, parsing session files to extract conversation content, metadata, timestamps, and token usage. All indexing and search happens locally using optimized string matching — no external search engine, no database, no dependencies.

The web dashboard is a lightweight HTTP server that serves a vanilla HTML/JS interface on localhost:3456. It provides activity graphs, cost breakdowns, and session browsing in a visual format. The server binds exclusively to the loopback interface and enforces strict CORS headers — it is physically impossible to access from outside your machine.

Key Design Decisions

• Zero dependencies: The entire tool — CLI parser, HTTP server, HTML dashboard, search engine — is built from scratch using only Node.js built-in modules. This eliminates supply chain risk and keeps cold start under one second.
• Localhost-only binding: The web dashboard binds to 127.0.0.1, not 0.0.0.0. Combined with CORS restrictions, this ensures session data is only accessible from your browser on your machine.
• Non-destructive deletion: When you delete sessions through csesh, they are removed from disk but their metadata is preserved in a trash manifest. This allows recovery and audit of what was deleted and when.
• Direct file parsing: csesh reads Claude Code's session files directly rather than maintaining a separate database. This means zero sync issues and immediate availability of new sessions.

Tech Stack

Code Patterns

# Search across all sessions for a specific topic
npx @arthurpcd/csesh search "authentication bug"

# View cost breakdown by project
npx @arthurpcd/csesh costs --by project

# Launch the web dashboard
npx @arthurpcd/csesh dashboard

# Clean up sessions older than 30 days (with trash manifest)
npx @arthurpcd/csesh prune --older-than 30d

# Cost tracking output
Project: jp-studio
  Sessions: 47
  Total cost: $12.34
  Avg cost/session: $0.26
  Top session: "PDF pipeline rework" — $1.87

Project: csesh
  Sessions: 23
  Total cost: $4.56
  Avg cost/session: $0.20
  Top session: "search indexing" — $0.89

// Zero-dependency HTTP server — no Express, no Koa, just Node.js
const { createServer } = require("node:http");

const server = createServer((req, res) => {
  // Enforce localhost-only access
  if (req.headers.origin && !req.headers.origin.includes("localhost")) {
    res.writeHead(403);
    return res.end("Forbidden");
  }

  res.setHeader("Access-Control-Allow-Origin", "http://localhost:3456");
  // Route handling with built-in URL parser
  const url = new URL(req.url, `http://${req.headers.host}`);
  return router.handle(url.pathname, req, res);
});

// Bind exclusively to loopback — not reachable from network
server.listen(3456, "127.0.0.1");

Outcomes

• Zero dependencies — no node_modules, no supply chain risk, no version conflicts.
• Sub-second cold start — npx @arthurpcd/csesh is ready instantly, no build step needed.
• Apache-2.0 licensed — fully open-source with enterprise-friendly terms and patent grant.
• Published on npm — available globally via npx @arthurpcd/csesh or npm install -g @arthurpcd/csesh.
• Privacy-first — localhost binding, CORS enforcement, zero telemetry, all data stays local.
• JP.Studio's first open-source release — demonstrating our commitment to the developer community beyond client work. We use the tools we need, and when they do not exist, we build them and share them.