{"id":51971651,"url":"https://github.com/yexela/csess","last_synced_at":"2026-07-29T23:01:29.859Z","repository":{"id":371319726,"uuid":"1300420678","full_name":"yexela/csess","owner":"yexela","description":"Searchable, portable store for your Claude Code sessions — full-text search, AI titles, tags, fuzzy find, and resume any session in any folder.","archived":false,"fork":false,"pushed_at":"2026-07-14T13:52:32.000Z","size":706,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T14:05:35.650Z","etag":null,"topics":["ai","anthropic","claude-code","cli","developer-tools","fzf","postgres","productivity","session-manager"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yexela.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-14T11:43:00.000Z","updated_at":"2026-07-14T13:53:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yexela/csess","commit_stats":null,"previous_names":["yexela/csess"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/yexela/csess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yexela%2Fcsess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yexela%2Fcsess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yexela%2Fcsess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yexela%2Fcsess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yexela","download_url":"https://codeload.github.com/yexela/csess/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yexela%2Fcsess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36052204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","claude-code","cli","developer-tools","fzf","postgres","productivity","session-manager"],"created_at":"2026-07-29T23:01:28.968Z","updated_at":"2026-07-29T23:01:29.851Z","avatar_url":"https://github.com/yexela.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# csess — a searchable, portable store for Claude Code sessions\n\n![csess — fuzzy-find any past session, plus an interactive menu of every command](docs/demo.gif)\n\nClaude Code keeps every session as a JSONL file under\n`~/.claude/projects/\u003cencoded-cwd\u003e/\u003cuuid\u003e.jsonl`. That means your history is\n**bound to the folder** it was created in, keyed only by an opaque UUID, and\nsearchable only by grepping raw files.\n\n`csess` mirrors that history into a local Postgres database so you can:\n\n- 🔎 **Search the full text of every conversation** — not just the first line\n- 🏷️ **Tag** sessions and browse by topic\n- 🤖 **Auto-title + auto-tag** sessions with a cheap Haiku call\n- 🎯 **Fuzzy-find** a session (`fzf`) and **resume it in *any* folder** — the\n  folder binding becomes a client-side detail\n- 🔁 **Auto-sync** every turn via a Claude Code hook (incremental — only new\n  bytes are shipped, since JSONL is append-only)\n\nEverything runs **locally**. The database is bound to `127.0.0.1` only.\n\n```\n   ~/.claude/projects/**/*.jsonl                Postgres (Docker, localhost)\n   ┌───────────────────────────┐   index/push   ┌────────────────────────────┐\n   │ session JSONL (per folder) │ ─────────────▶ │ metadata · tags · FTS      │\n   └───────────────────────────┘                 │ full JSONL body (bytea)    │\n             ▲  claude --resume                   └────────────────────────────┘\n             │                                                 │ load\n   ┌─────────┴───────────┐                                     ▼\n   │ any folder, resumed  │ ◀───────────────  materialize session into cwd\n   └─────────────────────┘\n```\n\n## Prerequisites\n\n`install.sh` **auto-installs everything else for you** via Homebrew — Docker\n(headless, via Colima), `fzf`, and `python3` — and starts the Docker daemon. So\nyou only need two things up front:\n\n| Need | Why |\n|------|-----|\n| **[Homebrew](https://brew.sh)** | the installer uses it to fetch the rest |\n| **[Claude Code](https://claude.com/claude-code)** | provides the sessions (`claude` on your PATH) |\n\nEverything below is handled automatically by the installer:\n\n| Auto-installed | Purpose |\n|----------------|---------|\n| Docker (Colima) | hosts the Postgres database, started headlessly |\n| `fzf` | powers `csess find` |\n| `python3` | runs the `csess` script |\n\n\u003e Already have Docker Desktop? The installer detects it and just starts it\n\u003e instead of installing Colima.\n\n## Install\n\n```bash\ngit clone https://github.com/yexela/csess.git\ncd csess\n./install.sh\n```\n\nOn a fresh install this:\n\n- starts Postgres and applies the schema;\n- links `csess` into `~/.local/bin` (adding it to your `PATH` if needed);\n- **indexes every session already in `~/.claude`** — your *whole existing\n  history*, retroactively, not just sessions created from now on;\n- **offers to generate AI titles + tags** for those existing sessions right then\n  (a `[y/N]` prompt — say yes for a browsable history out of the box, or skip it\n  and run `csess summarize` whenever). Auto-skipped if it's non-interactive or\n  `claude` isn't on your PATH;\n- prints a summary and the optional auto-sync hook to add.\n\n`install.sh` is idempotent — safe to re-run anytime (e.g. after `git pull`).\n\n## Usage\n\nNew here? Just run **`csess`** (or `csess start`) — it opens an interactive menu\nof every action, so you don't have to memorize commands:\n\n```\ncsess\u003e ▏                type to filter · ↑↓ move · Enter select · Esc quit\n❯ 🔎  find \u0026 resume a session\n  📋  list recent sessions\n  🔍  search sessions by text or tag\n  🏷   add tags to a session\n  🤖  generate AI titles + tags\n  ⬆   back up session bodies\n  🔄  re-scan sessions into the DB\n```\n\nOr call the commands directly:\n\n```bash\ncsess find                 # interactive fuzzy picker → Enter resumes here\ncsess search testflight    # full-content search (matches anywhere in a convo)\ncsess list                 # recent sessions with titles + tags\ncsess summarize            # AI title + auto-tags for all untitled sessions (also offered at install)\ncsess tag \u003cuuid\u003e billing   # your own tags (UUID prefix is enough)\ncsess run \u003cuuid\u003e           # materialize into current folder + claude --resume\ncsess index                # re-scan metadata (also run by the hook)\ncsess push                 # store/refresh JSONL bodies (incremental)\n```\n\n### Resume anywhere\n\n`csess load`/`run` copy the session's JSONL into the **current** folder's\nproject dir (preferring the body stored in Postgres, falling back to the\noriginal file) and then call `claude --resume`. So a session created in project\nA can be resumed from project B — or, once the DB lives on a server, from\nanother machine entirely.\n\n## Updating\n\n```bash\ncsess update       # git-pulls the latest, tells you the new version\n```\n\nOr manually:\n\n```bash\ncd /path/to/csess \u0026\u0026 git pull\n```\n\nThe `csess` command is a symlink into the clone, so a pull takes effect\nimmediately. If a release changes dependencies or the database schema, re-run\n`./install.sh` (it's idempotent). Check what you're on with `csess version`, and\nsee [CHANGELOG.md](CHANGELOG.md) for what changed.\n\n## How it works\n\n- **Metadata + FTS** — `csess index` parses each JSONL for cwd, branch,\n  timestamps, message count, the first user message, and all conversational\n  text. A Postgres generated `tsvector` over (summary + first message + content)\n  powers `csess search`.\n- **Bodies** — `csess push` stores the raw JSONL in a `bytea` column,\n  **incrementally**: it tracks how many bytes are already stored and appends\n  only the new tail each time (JSONL is append-only). This is what makes a\n  session portable independent of `~/.claude`.\n- **Auto-sync hook** — `csess hook` reads the `transcript_path` from the hook\n  payload on stdin and indexes + pushes **only the current session**. Wired to\n  `Stop` (every turn) and `SessionEnd`, so the DB tracks live sessions.\n\n## Configuration\n\nEnvironment variables (all optional):\n\n| Var | Default | Purpose |\n|-----|---------|---------|\n| `CSESS_DSN` | _(unset)_ | Postgres connection string for a **remote** DB (see below); overrides the local container |\n| `CSESS_CONTAINER` | `claude-sessions-db` | Postgres container name |\n| `CSESS_DB` | `sessions` | database name |\n| `CSESS_DB_USER` | `postgres` | database user |\n| `CSESS_WORKDIR` | `~/.cache/csess` | scratch dir for internal `claude -p` calls |\n| `CLAUDE_PROJECTS_DIR` | `~/.claude/projects` | where Claude Code stores sessions |\n\n### Local vs. remote database\n\nBy default `csess` talks to the local Docker container — no host `psql` client\nneeded. To point it at a **remote** Postgres instead (e.g. a shared server so\nseveral machines share one history), set a connection string:\n\n```bash\nexport CSESS_DSN=\"postgresql://user:pass@db.example.com:5432/sessions\"\ncsess index          # now reads/writes the remote DB\n```\n\n- With `CSESS_DSN` set, csess uses a host `psql` if present, otherwise routes\n  through the local container as a client.\n- Apply `schema.sql` to the remote database once before first use.\n- Everything else is identical — indexing your local sessions and resuming them\n  into folders works the same; only the storage moves off-box.\n- Unset `CSESS_DSN` to switch back to local.\n\n## Security notes\n\n- The database contains your **full session transcripts**, which can include\n  secrets, code, and file contents. The container binds to `127.0.0.1` only.\n- Nothing is uploaded anywhere. Everything stays on your machine.\n\n## Roadmap\n\n- Lift Postgres off-box (RDS / self-hosted) for **multi-machine** shared history\n- Cross-machine `pull`\n- Optional MCP tool so you can search sessions from inside a conversation\n\n## Troubleshooting\n\n**`csess: command not found`** — make sure `~/.local/bin` is on your `PATH`.\n\n**`psql error: ... connection refused`** — the database isn't running. Locally:\n`docker compose up -d` (or `docker start claude-sessions-db`).\n\n**`csess find` just prints a list** — install fzf: `brew install fzf`.\n\n**Search returns nothing** — run `csess index` (metadata); AI titles need\n`csess summarize`.\n\n**Auto-sync hook isn't firing** — hooks load at session start, so they only\naffect sessions started *after* you added them. Use the **absolute path** to\n`csess` in `~/.claude/settings.json` (hooks may run without `~/.local/bin` on\nPATH), and confirm the container is running.\n\n**`load`: \"no stored body and original file missing\"** — that session's body was\nnever pushed and the original file isn't on this machine. Run `csess push` on the\nmachine that has it.\n\n## License\n\nMIT © Oleksii Chernetskyi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyexela%2Fcsess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyexela%2Fcsess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyexela%2Fcsess/lists"}