{"id":50457189,"url":"https://github.com/junxit/agentic-session-explorer","last_synced_at":"2026-06-01T03:01:22.136Z","repository":{"id":361639395,"uuid":"1254802812","full_name":"junxit/agentic-session-explorer","owner":"junxit","description":"Explore, archive, and safely delete the chat sessions AI coding agents (Claude Code, Codex, Gemini, and more) leave on your machine — all from one terminal TUI.","archived":false,"fork":false,"pushed_at":"2026-05-31T15:14:38.000Z","size":68,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T17:08:53.424Z","etag":null,"topics":["ai-agents","claude-code","cli","codex","gemini-cli","llm","python","rich","session-manager","terminal","textual","tui"],"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/junxit.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.txt","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-05-31T02:50:17.000Z","updated_at":"2026-05-31T15:14:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/junxit/agentic-session-explorer","commit_stats":null,"previous_names":["junxit/agentic-session-explorer"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/junxit/agentic-session-explorer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junxit%2Fagentic-session-explorer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junxit%2Fagentic-session-explorer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junxit%2Fagentic-session-explorer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junxit%2Fagentic-session-explorer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junxit","download_url":"https://codeload.github.com/junxit/agentic-session-explorer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junxit%2Fagentic-session-explorer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33757790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"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-agents","claude-code","cli","codex","gemini-cli","llm","python","rich","session-manager","terminal","textual","tui"],"created_at":"2026-06-01T03:01:06.496Z","updated_at":"2026-06-01T03:01:22.111Z","avatar_url":"https://github.com/junxit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sx — session explorer for AI coding harnesses\n\nA terminal TUI that gathers the chat sessions every AI coding harness leaves on\nyour machine — **Claude Code**, **Codex**, **Gemini CLI**, and more — into one\nbrowsable, groupable, *deletable* view. Think of it as a terminal-native\nalternative to Claude Code UI, covering every harness at once.\n\n\u003e **Status:** functional. Browsing, search, grouping, permanent deletion with\n\u003e Markdown export, and orphan cleanup all work across Claude, Codex, Gemini, and\n\u003e opencode.\n\n## Why\n\nEach harness scatters sessions in its own format and location: Claude under\n`~/.claude/projects/\u003cencoded-cwd\u003e/`, Codex in a date tree under\n`~/.codex/sessions/`, Gemini as mutation logs under `~/.gemini/tmp/\u003chash\u003e/`, and\nopencode as rows in a shared SQLite database. Over time these pile up alongside\norphaned folders pointing at projects you deleted long ago. `sx` reads them all,\nlets you scroll any transcript, and permanently removes the ones you no longer\nwant.\n\n## Features\n\n- **Unified browser** — sessions grouped by harness, then by project.\n- **Scrollable transcripts** — normalized rendering across every harness.\n- **Orphan detection** — finds session folders whose project is gone, plus\n  stray temp files, and reports *why* each is flagged.\n- **Permanent delete with guardrails** — dry-run preview, typed confirmation\n  for bulk operations, a path allowlist, an active-session guard, and an\n  append-only deletion log. No accidental `rm -rf`.\n- **Pre-delete Markdown export** — optionally archive a transcript to Markdown\n  before removing it (also available as a standalone export action).\n- **Forward-looking** — harnesses you have not installed yet appear greyed out\n  and light up the moment their session store shows up on disk.\n\n## Supported harnesses\n\n| Harness | Status | Store |\n|---|---|---|\n| Claude Code | ✅ verified | `~/.claude/projects/\u003cencoded-cwd\u003e/\u003cid\u003e.jsonl` |\n| Codex | ✅ verified | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` |\n| Gemini CLI | ✅ verified | `~/.gemini/tmp/\u003chash\u003e/chats/session-*.jsonl` |\n| opencode | ✅ verified | `~/.local/share/opencode/opencode.db` (SQLite) |\n| Qwen Code | 🔎 dormant | Gemini-fork layout |\n| Continue | 🔎 dormant | `~/.continue/sessions/*.json` |\n| Goose | 🔎 dormant | `~/.local/share/goose/sessions/` |\n| Cline | 🧩 dormant | `~/.cline/data/workspaces/\u003cid\u003e/` |\n| Cursor | 🧩 dormant | `~/.cursor/` (SQLite) |\n| Crush | 🧩 dormant | SQLite |\n\n✅ verified on a real machine · 🔎 format known · 🧩 needs probing once installed\n\n## Run it\n\nYou need [`uv`](https://docs.astral.sh/uv/). Pick one of the two ways below.\n\n### Option A — run straight from GitHub, no install (`uvx`)\n\n`uvx` fetches, builds, and runs `sx` in a throwaway environment — nothing is\nadded to your PATH:\n\n```bash\nuvx --from git+https://github.com/junxit/agentic-session-explorer.git sx\n```\n\nTyping that every time is a mouthful, so add an `sx` alias to your shell. The\nalias also sets `SX_NO_UPDATE_CHECK=1`, because `uvx` already pulls the latest\nbuild — the in-app \"update available\" prompt would be redundant here.\n\n**zsh** — append to `~/.zshrc`:\n\n```bash\nalias sx='SX_NO_UPDATE_CHECK=1 uvx --from git+https://github.com/junxit/agentic-session-explorer.git sx'\n```\n\n**bash** — append to `~/.bashrc` (Linux) or `~/.bash_profile` (macOS):\n\n```bash\nalias sx='SX_NO_UPDATE_CHECK=1 uvx --from git+https://github.com/junxit/agentic-session-explorer.git sx'\n```\n\n**fish** — append to `~/.config/fish/config.fish`:\n\n```fish\nalias sx 'env SX_NO_UPDATE_CHECK=1 uvx --from git+https://github.com/junxit/agentic-session-explorer.git sx'\n```\n\nThen reload (`source ~/.zshrc`, etc.) and run `sx`, `sx list`, `sx --version` —\narguments pass straight through the alias.\n\n`uvx` caches builds, so a plain run may reuse a recent one. To force the newest\ncommit, add `--refresh` to the alias's command, or pin a released tag with\n`...explorer.git@v0.2.0`.\n\n### Option B — install as a tool (recommended for regular use)\n\nThis puts a persistent `sx` on your PATH:\n\n```bash\nuv tool install git+https://github.com/junxit/agentic-session-explorer.git\n```\n\n(From a local clone, `uv tool install .` works too.)\n\n**Upgrade:**\n\n```bash\nuv tool upgrade sx\n# or force the very latest commit on main:\nuv tool install --force git+https://github.com/junxit/agentic-session-explorer.git\n```\n\n**Uninstall:**\n\n```bash\nuv tool uninstall sx\n```\n\nWhen you run an installed `sx` interactively, it checks GitHub **at most once a\nday** for a newer release and prints a one-line notice (the TUI shows a toast).\nThe check is cached, times out fast, fails silently, and never blocks startup.\nTurn it off with `--no-update-check` or by exporting `SX_NO_UPDATE_CHECK=1`.\n\n## Usage\n\n```bash\nsx              # launch the interactive TUI\nsx list         # list every discovered session as plain text\nsx harnesses    # show all known harnesses and their status\nsx version      # show the installed version and check for a newer one\nsx update       # show (or, with --run, execute) the upgrade command\n```\n\n### Keys (in the TUI)\n\n| Key | Action |\n|---|---|\n| `↑`/`↓` or `j`/`k` | Move the selection |\n| `enter` | Open the highlighted session's transcript |\n| `g` / `G` | Jump to top / bottom of a transcript |\n| `m` | Cycle grouping: **project → date → recency** |\n| `/` | Filter by title or project (live) |\n| `e` | Export the highlighted session to Markdown |\n| `d` | Permanently delete the highlighted session (with preview) |\n| `o` | Open the orphan-cleanup screen |\n| `r` | Re-scan all harness stores |\n| `q` | Quit |\n\nA session written within the last 90 seconds is flagged `● LIVE`; deleting one\nrequires typing `DELETE` to confirm. Bulk orphan deletion requires typing\n`DELETE \u003cn\u003e`. Exports default to `./session-exports/`; every deletion is\nappended to `./sx-deletions.log`.\n\n## Architecture\n\n```mermaid\nflowchart TD\n    TUI[\"Textual TUI\"] --\u003e REG[\"Adapter registry\"]\n    CLI[\"sx list (CLI)\"] --\u003e REG\n    REG --\u003e BASE[\"HarnessAdapter (abstract)\"]\n    BASE --\u003e JF[\"JsonlFolderAdapter\"]\n    JF --\u003e CL[\"ClaudeAdapter\"]\n    JF --\u003e CX[\"CodexAdapter\"]\n    JF --\u003e GM[\"GeminiAdapter\"]\n    BASE --\u003e OC[\"OpencodeAdapter\\n(SQLite, row-level delete)\"]\n    BASE --\u003e DORM[\"dormant adapters\\n(Cline, Cursor, Crush, ...)\"]\n    REG --\u003e DEL[\"DeleteService\\n(guards + op-log)\"]\n    REG --\u003e EXP[\"MarkdownExporter\"]\n```\n\nEvery adapter normalizes its harness into the same `Session` and `Message`\ntypes, so the transcript viewer, the exporter, and the delete flow are each\nwritten once and work for all harnesses — present and future. Most harnesses\nstore one file per session; opencode keeps all sessions as rows in a shared\nSQLite database, so its adapter subclasses `HarnessAdapter` directly and deletes\na session's rows (and its `session_diff` sidecar) without ever touching the\ndatabase file or other sessions. Its shared `log/` files are left alone.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run sx list\nuv run pytest\n```\n\n### Releasing\n\nThe update check compares the installed version against the latest GitHub\n**release** (falling back to the highest `vX.Y.Z` tag). To publish an update:\n\n1. Bump `version` in `pyproject.toml` and `__version__` in `src/sx/__init__.py`.\n2. Commit, then tag and release:\n\n   ```bash\n   git tag v0.2.0 \u0026\u0026 git push --tags\n   gh release create v0.2.0 --generate-notes\n   ```\n\nInstalled copies will then prompt their users to upgrade.\n\n## Safety\n\n`sx` deletes permanently — there is no trash or undo. To compensate, deletion\nis gated behind a preview, typed confirmation for bulk actions, a guard that\nrefuses to touch anything outside known harness store roots, and a guard that\nrefuses to delete a session that is currently being written. Every deletion is\nappended to `sx-deletions.log`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunxit%2Fagentic-session-explorer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunxit%2Fagentic-session-explorer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunxit%2Fagentic-session-explorer/lists"}