agf

Find the AI coding session you meant to resume.

agf is a local-first fuzzy finder for AI coding-agent sessions. Search the sessions your terminal agents already keep locally, then resume the right one in a keystroke.

Install

cargo install agf
agf setup
agf

Requires a Rust toolchain (rustup recommended). Prebuilt binaries for macOS, Linux, and Windows are also available on the Releases page.

Quick Resume (no TUI)

agf resume project-name   # fuzzy-matches and resumes the best match directly

Scripts and agent tools

agf search parser --agent codex --limit 10
agf show SESSION_ID --agent codex --include-summaries
agf resume-plan SESSION_ID --agent codex
agf mcp --agent codex --project /absolute/project/path

The first three commands return versioned JSON. They do not launch agents or modify their stores; resume-plan returns literal arguments, working directory and scoped storage environment for review. The stdio MCP server uses the same read-only API. See agent integration for schemas, limits, client configuration and the portable AGF skill.

Why agf?

AI coding agents are great at keeping context — until you lose the terminal.

You switch projects, close a tab, forget the session ID, or resume the wrong agent. Then you either dig through history files or start over.

agf gives you one searchable list of local agent sessions and resumes the right one.

Supported agents

agf reads the session files each agent already stores locally. No account, no cloud sync, no extra agent process.

Agent	Resume command	Local session source
Claude Code	`claude --resume <id>`	`~/.claude/history.jsonl` + `~/.claude/projects/`
Codex	`codex resume <id>`	`~/.codex/sessions/*/.jsonl`
Grok Build	`grok --resume <id>`	`$GROK_HOME/sessions/` or `~/.grok/sessions/`
Kimi Code	`kimi --session <id>`	`$KIMI_CODE_HOME/sessions/` or `~/.kimi-code/sessions/`
Qwen Code	`qwen --resume <id>`	`$QWEN_RUNTIME_DIR/projects/` or `~/.qwen/projects/`
Prime Agent	`prime-agent --resume <id>`	`~/.prime/agent/sessions/<id>.jsonl`
Gemini CLI	`gemini --resume <id>`	`~/.gemini/tmp/<project>/chats/session-*.json` or `.jsonl`
Cursor CLI	`cursor-agent --resume <id>`	`~/.cursor/projects//agent-transcripts/<id>/<id>.jsonl` (Composer 2+) `~/.cursor/projects//agent-transcripts/<id>.txt` (legacy)
OpenCode	`opencode -s <id>`	`~/.local/share/opencode/opencode.db`
Kiro	`kiro-cli chat --resume-id <id>`	Kiro v2 SQLite + Kiro v3 `~/.kiro/sessions/cli/`
pi	`pi --session <id>`	`~/.pi/agent/sessions/<cwd>/*.jsonl`
Hermes	`hermes --resume <id>` (cwd-independent — resumes in your current shell directory)	`~/.hermes/state.db`
Oh My Pi	`omp --resume <id>`	`~/.omp/agent/sessions/<cwd>/*.jsonl`
Yolop	`yolop --session <id>`	Platform data directory under `yolop/sessions/`

Full session storage paths

Agent	Format	Default Path
Claude Code	JSONL	`~/.claude/history.jsonl` (sessions) `~/.claude/projects/*/` (worktree detection)
Codex	JSONL	`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
Grok Build	JSON + JSONL	`$GROK_HOME/sessions/<encoded-cwd>/<id>/summary.json` (default `~/.grok`) Activity, title, recap, branch, and worktree metadata come from the bounded summary document
Kimi Code	JSON + JSONL	`$KIMI_CODE_HOME/sessions/<workDirKey>/<id>/state.json` (default `~/.kimi-code`) `session_index.jsonl` supplies cwd fallback for migrated legacy sessions
Qwen Code	JSONL	`$QWEN_RUNTIME_DIR/projects/<project>/chats/<id>.jsonl` Defaults to `$QWEN_HOME` or `~/.qwen`; `advanced.runtimeOutputDir` and legacy `tmp/<project>/chats/` are also supported
Prime Agent	JSONL	`~/.prime/agent/sessions/<id>.jsonl` (also honors Prime Agent environment/global settings overrides)
OpenCode	SQLite	`~/.local/share/opencode/opencode.db`
pi	JSONL	`~/.pi/agent/sessions/--<encoded-cwd>--/<ts>_<id>.jsonl`
Oh My Pi	JSONL	`~/.omp/agent/sessions/<encoded-cwd>/<ts>_<id>.jsonl`
Kiro	SQLite + JSON/JSONL	v2: macOS `~/Library/Application Support/kiro-cli/data.sqlite3`, Linux `~/.local/share/kiro-cli/data.sqlite3` v3: `$KIRO_HOME/sessions/cli/` or `~/.kiro/sessions/cli/`
Cursor CLI	SQLite + JSONL/TXT	`~/.cursor/chats/<workspace>/<id>/store.db` (metadata; required for `.jsonl` to be resumable) `~/.cursor/projects//agent-transcripts/<id>/<id>.jsonl` (Composer 2+ transcript) `~/.cursor/projects//agent-transcripts/<id>.txt` (legacy transcript)
Gemini	JSON + JSONL	`~/.gemini/tmp/<project>/chats/session-*.json` or `.jsonl` `<project>` is a named dir or SHA-256 hash of the project path Project paths resolved via `~/.gemini/projects.json`
Hermes	SQLite	`~/.hermes/state.db` (sessions + messages) JSON dumps in `~/.hermes/sessions/session_<id>.json` Hermes is cwd-independent — resume runs in your current shell directory
Yolop	JSONL + JSON	macOS: `~/Library/Application Support/yolop/sessions/<id>/` Linux: `$XDG_DATA_HOME/yolop/sessions/<id>/` Windows: `%APPDATA%\yolop\sessions\<id>\`

Storage and executable overrides

Provider	Supported settings
Codex	`CODEX_HOME`; user `config.toml` `sqlite_home` takes precedence over `CODEX_SQLITE_HOME`, then the Codex home
Claude Code	`CLAUDE_CONFIG_DIR`
Gemini	`GEMINI_CLI_HOME` selects the parent of `.gemini`
Cursor	`AGF_CURSOR_CLI` explicitly selects one executable path/name, including installations named `agent`
OpenCode	`XDG_DATA_HOME`
pi	`PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`
Hermes	`HERMES_HOME`; native Windows defaults to `%APPDATA%/hermes`

Existing Grok, Kimi, Qwen, Kiro and Prime Agent overrides remain supported. Resuming freezes the resolved executable and applicable storage roots before changing directory. A generic agent found on PATH is not automatically assumed to be Cursor. Codex project-trust/profile/managed configuration layers and Oh My Pi profile/XDG extensions are not emulated; use the documented roots explicitly.

Features

Cross-agent search — see all supported agents in one list
Fuzzy search — find sessions by project name, path, branch, or summary
One-key resume — resume the selected session with the right agent command
Quick resume — agf resume <query> skips the TUI entirely
Bulk delete — Ctrl+D to multi-select and clean up stale sessions
Project awareness — git branches and Claude Code --worktree sessions surface in the UI

Also supports Unicode/CJK search, mouse navigation, agent filters, permission/approval-mode picker, agent auto-detection, and shell wrappers for zsh, bash, fish, and PowerShell.

Basic controls

Key	Action
Type anything	Fuzzy search
`↑` `↓` / `Ctrl+K` `Ctrl+J`	Navigate
`Enter`	Open action menu
`Tab` / `Shift+Tab`	Cycle agent filter
`→` / `Ctrl+L`	Preview session
`Ctrl+D`	Bulk delete
`?`	Help / settings
`Esc`	Quit

Full keybindings

Browse

Key	Action
Type anything	Fuzzy search
`↑` `↓` / `Ctrl+K` `Ctrl+J`	Navigate
`[` `]`	Cycle session summary
`Enter`	Open action menu
`→` / `Ctrl+L`	Preview session details
`Tab` / `Shift+Tab`	Cycle agent filter
`Ctrl+S`	Cycle sort (time / name / agent)
`Ctrl+D`	Enter bulk delete mode
`?`	Help / settings
`Esc`	Quit

Bulk Delete (`Ctrl+D`)

Key	Action
`Space`	Toggle selection + move down
`↑` `↓` / `Ctrl+K` `Ctrl+J`	Navigate
`Enter`	Confirm deletion (when items selected)
`Esc`	Cancel and return to browse

New Session (Agent Select)

Key	Action
`1`-`9`	Quick select agent
`Tab`	Open permission/approval mode picker
`Enter`	Launch with default mode
`Esc`	Back

Configuration

Optional. Create ~/.config/agf/config.toml:

sort_by = "time"            # "time" | "name" | "agent"
max_sessions = 200
search_scope = "name_path"  # "name_path" (default) | "all" (include summaries)
summary_search_count = 5    # number of summaries included when search_scope = "all"
include_non_interactive = false # show Codex subagent/exec threads

You can also edit search_scope and summary_search_count interactively by pressing ? in the TUI.

Shell integration

agf setup auto-detects your shell and installs the wrapper. Use agf setup --shell powershell (or another supported shell) when auto-detection is ambiguous.

zsh / bash — appends to ~/.zshrc or ~/.bashrc
fish — writes to ~/.config/fish/config.fish
PowerShell (Windows or cross-platform pwsh) — writes to $PROFILE.CurrentUserAllHosts (Documents\PowerShell\profile.ps1 on Windows, ~/.config/powershell/profile.ps1 elsewhere)

If auto-detection misses your shell, run the matching agf init form manually:

eval "$(agf init zsh)"                               # zsh
eval "$(agf init bash)"                              # bash
agf init fish | source                               # fish
agf init powershell | Out-String | Invoke-Expression # PowerShell

After upgrading, run agf setup again (or restart your shell) to apply the latest wrapper. See CHANGELOG.md for release notes.

Requirements

macOS, Linux, or Windows (PowerShell 5.1+ / PowerShell 7+)
One or more of: claude, codex, grok, kimi, qwen, prime-agent, opencode, pi, kiro-cli, cursor-agent, gemini, hermes, omp, yolop

Install from source

git clone https://github.com/subinium/agf.git
cd agf
cargo install --path .
agf setup

Limitations

agf works best with agents that store resumable sessions locally.

Direct deletion is intentionally disabled for Prime Agent, Grok Build, Kimi Code, Qwen Code, and Gemini. Their native pickers coordinate active sessions, secondary indexes, or session sidecar/subagent artifacts; deleting only the visible file from AGF could leave corrupted or stale upstream state. Use the provider's native deletion workflow instead.

JSON API and MCP metadata can contain private or untrusted text. Summaries are opt-in, and project scope limits returned records rather than providing an OS sandbox. CSV preserves source values, including spreadsheet formula prefixes; import it as text when opening untrusted session data in a spreadsheet.

Amp is not supported yet because its sessions are stored remotely, which makes it hard to reliably resolve local project paths from session metadata. We are monitoring upstream changes and will add support when feasible.

Built with

agf uses Rust 2024 (MSRV 1.88), SuperLightTUI 0.24, and the official Rust MCP SDK. The default mcp feature can be omitted with --no-default-features; the TUI and JSON CLI remain available.

Contributing

Issues and PRs are welcome. Adding support for another agent/harness is a self-contained change — see docs/adding-an-agent.md for the wiring checklist.

Unix PTY tests use Python 3 and requirements-test.txt to reconstruct terminal screens, including incremental redraws. Install these test dependencies in a virtual environment and set AGF_TEST_PYTHON to its Python executable when running cargo test. They are not AGF runtime dependencies.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets		assets
docs		docs
homebrew		homebrew
scripts		scripts
skills/agf		skills/agf
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
RELEASE_NOTES.md		RELEASE_NOTES.md
requirements-test.txt		requirements-test.txt

Navigation Menu

Repository files navigation

agf

Install

Quick Resume (no TUI)

Scripts and agent tools

Why agf?

Supported agents

Storage and executable overrides

Features

Basic controls

Browse

Bulk Delete (`Ctrl+D`)

New Session (Agent Select)

Configuration

Shell integration

Requirements

Install from source

Limitations

Built with

Contributing

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

agf

Install

Quick Resume (no TUI)

Scripts and agent tools

Why agf?

Supported agents

Storage and executable overrides

Features

Basic controls

Browse

Bulk Delete (Ctrl+D)

New Session (Agent Select)

Configuration

Shell integration

Requirements

Install from source

Limitations

Built with

Contributing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Bulk Delete (`Ctrl+D`)