Metadata-Version: 2.5
Name: anysession
Version: 1.0.0
Summary: One fzf picker over every resumable AI coding agent session — Claude Code, Codex, OpenCode, Hermes, Command Code, Antigravity
Project-URL: Homepage, https://github.com/toshon-jennings/anysession
Project-URL: Repository, https://github.com/toshon-jennings/anysession
Project-URL: Issues, https://github.com/toshon-jennings/anysession/issues
Author: Toshon Jennings
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,claude,codex,fzf,opencode,sessions,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Provides-Extra: fzf
Requires-Dist: pyfzf; extra == 'fzf'
Description-Content-Type: text/markdown

# anysession

**anysession** (formerly `agent-sessions`) — a cross-tool session browser for
AI coding agent CLIs. One `fzf` picker over every resumable session on your
machine — searchable by title, path, *and* full conversation content — with
the right resume command run for you.

No daemon, no background process. Pure Python stdlib (including `sqlite3`)
that scans each tool's own on-disk session store, shows you an `fzf` picker,
and `exec`s the right resume command when you pick one.

## Supported tools

| Tool | Source read | Resume command |
|---|---|---|
| Claude Code | `~/.claude/projects/*/*.jsonl` | `claude --resume <id>` |
| Codex | `~/.codex/session_index.jsonl` + `~/.codex/sessions/**` | `codex resume <id>` |
| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite) | `opencode --session <id>` |
| Hermes | `~/.hermes/state.db` (SQLite) | `hermes --resume <id>` |
| Command Code (`cmd`) | `~/.commandcode/projects/*/*.jsonl` | `cmd --resume <id>` |
| Antigravity CLI (`agy`) | `~/.gemini/antigravity-cli/history.jsonl` | `agy --conversation <id>` |
| Antigravity desktop | `~/.gemini/antigravity/conversations/*.db` | listed only — no known CLI resume path yet |

Titles come natively from the tool where available (Codex, OpenCode, Hermes);
for tools that don't store one (Claude Code, Command Code), the title is the
first real user message in the transcript.

Not currently wired up: OpenClaw, Freebuff — no resumable session ID
mechanism found for either. PRs welcome once one exists.

## Install

Requires Python 3.10+ and [`fzf`](https://github.com/junegunn/fzf).

```bash
pip install anysession

# fzf, if you don't have it:
brew install fzf                 # macOS
# or a static binary for Linux: https://github.com/junegunn/fzf/releases
```

This installs both command names — `anysession` and the legacy alias
`agent-sessions` — so existing muscle memory and scripts keep working.

Run from a source checkout instead, if you prefer:

```bash
git clone https://github.com/toshon-jennings/anysession
python3 -m anysession   # from inside the checkout
```

## Use

```bash
anysession
```

Type to search — it matches against titles, working directories, *and* the
full text of every conversation, not just what's shown in the list. The
preview pane below shows the matched excerpt in context. Enter resumes the
selected session in its original directory; Esc cancels.

## Safety

Every resume goes through an allow-list (`RESUME_POLICY` in
`__main__.py`): the tool name must be one of the six known CLIs, the argv
shape is pinned to exactly `[tool, flag, id]`, the session ID must match a
strict character pattern, and the executable is resolved with `shutil.which`
before `execvp`. A tampered or hand-crafted cache cannot smuggle extra
arguments or an unexpected program onto the exec line.

## How it works

Every invocation does a fresh, read-only scan of each tool's session store
(files or SQLite, opened `mode=ro`) and writes a small cache to
`~/.cache/agent-sessions/index.json` — rebuilt on every launch, used only to
make live search-as-you-type fast without rescanning disk on every
keystroke. Nothing is written back to any tool's own data.

## Portability

Paths are all `$HOME`-relative and read with plain Python stdlib, so this
should work unmodified on macOS as long as the same tools are installed
there. Not yet verified on macOS — if something's off, please file an issue
or send a PR.

## License

MIT — see [LICENSE](LICENSE).
