Fainder

---
name: fainder
description: Use Fainder to search, inspect, and contextualize local AI agent conversations across Codex, Claude Code, OpenCode, Hermes, Cursor, GitHub Copilot, and Kiro. Trigger when an agent needs to recover prior work, find a lost thread, inspect a transcript by role or turn, produce bounded chronological context from another harness, locate resume commands, or guide installation/update with Homebrew.
---

# Fainder

Fainder is a local, read-only conversation finder for humans and agents. Prefer the non-interactive CLI when you are an agent.

## Install

```bash
brew install satelerd/tap/fainder
brew update && brew upgrade fainder
fainder doctor
```

On Linux, install the prebuilt binary (see `docs/LINUX.md` in the repo):

```bash
mkdir -p ~/.local/bin && curl -fsSL "https://github.com/satelerd/fainder/releases/latest/download/fainder-$(uname -m)-unknown-linux-gnu.tar.gz" | tar -xz -C ~/.local/bin
```

Supported providers:

- `codex`
- `claude`
- `opencode`
- `hermes`
- `cursor`
- `copilot`
- `kiro`

## Agent Workflow

Use this sequence:

1. `fainder doctor` to confirm local histories.
2. `fainder search` to find candidate conversations.
3. `fainder inspect` to locate the relevant turn range inside the chosen conversation.
4. `fainder context` to print a bounded chronological transcript window.
5. Continue in the current harness using that evidence. Do not run a provider-native `resume_command` unless the user wants to reopen that provider.

## Search

Find candidate conversations:

```bash
fainder search "SmartUp migration" --json --limit 8
fainder search "batch-download Williams" --provider codex,claude --json --limit 10
fainder search "agents bedrock" --words --json --limit 10
fainder search "PR|commit|deploy" --regex --json --limit 10
fainder search "SmartUp agents" --scope metadata --json --limit 10
```

By default the query is matched as one exact phrase (case-insensitive). Use
`--words` to require each word independently in any order, or `--regex` for
alternatives. A single token behaves the same in every mode.

Important JSON fields:

- `provider`
- `id`
- `title`
- `cwd`
- `created_at`
- `updated_at`
- `message_count`
- `resume_command`
- `snippets`
- `latest_messages`

If confidence is low, show the best candidates to the user instead of guessing.

## Inspect

Use `inspect` to navigate one conversation without printing the whole transcript.

List human/user turns first when reconstructing intent:

```bash
fainder inspect claude:cab15fb3 --role user --limit 40
```

Check where the agent stopped:

```bash
fainder inspect claude:cab15fb3 --role agent --tail 20
```

Search inside one conversation:

```bash
fainder inspect claude:cab15fb3 --find "PR|commit|batch-download|documents.append" --regex
fainder inspect codex:019dec17 --find "Raycast Homebrew skill"
```

Read around a relevant turn:

```bash
fainder inspect claude:cab15fb3 --around 96 --context 8
fainder inspect claude:cab15fb3 --turn 96 --context 8 --expand
```

Use JSON for automation:

```bash
fainder inspect claude:cab15fb3 --find "PR|commit" --regex --json
```

`inspect --json` returns previews of each turn (bodies capped, `truncated: true`)
to keep the payload small — a broad `--find ... --json` over a long conversation
would otherwise return 100k+ tokens and get cut off by the harness. Each turn
also carries `full_tokens`, an estimate of its full (untruncated) body size, so
you can tell which turns were heavily clipped. To read the full text of a
specific range, do **not** add `--expand`; instead note the turn numbers (use
`full_tokens` to budget the call) and pull that window with
`fainder context --from-turn N --to-turn M`. Use `--expand` only for a narrow,
already-bounded selection.

`inspect` output uses stable turn numbers. Feed those turn numbers into `context`.

## Context

Use `context` after `inspect` identifies a useful range. It is deterministic: it does not call an LLM, does not start Codex or Claude, and does not summarize. It prints local transcript evidence in chronological order:

```bash
fainder context claude:cab15fb3 --from-turn 90 --to-turn 130
fainder context claude:cab15fb3 --around 96 --context 12
fainder context codex:019dec17 --tail 80 --truncate-tools
```

The default output is Markdown with:

- source metadata
- token budget estimate
- chronological transcript turns
- user, agent, and tool messages in the original order

Large outputs require confirmation. If Fainder prints a budget warning, narrow the range or rerun with `--confirm`:

```bash
fainder context claude:cab15fb3 --from-turn 1 --to-turn 240 --confirm
fainder context claude:cab15fb3 --from-turn 1 --to-turn 240 --max-tokens 30000 --confirm
```

Useful context flags:

- `--from-turn N --to-turn M`
- `--around N --context K`
- `--tail N`
- `--role user|agent|tool|system|all`
- `--truncate-tools`
- `--no-tools`
- `--max-tokens N`
- `--confirm`
- `--format json`

Do not ask Fainder to summarize. If a summary is needed, summarize the deterministic `context` output in the current harness after reading it.

## Resume Commands

Search results include `resume_command`. Use it only when the user wants to reopen the original provider:

```bash
fainder search "SmartUp migration" --command-only --select 1
fainder search "SmartUp migration" --copy --select 1
fainder search "SmartUp migration" --open --select 1
```

For cross-harness continuation, prefer `inspect` and `context` over `resume_command`.

## Query Rules

- Default search matches the whole query as one case-insensitive phrase.
- Use `--words` to require every word independently (any order).
- Use `--regex` for alternatives like `SmartUp|bedrock|shapeup`.
- Use `--provider codex,claude` to reduce noise.
- Use `--scope metadata` when full-text is too noisy.
- Use `--json` for machine-readable output.

## Config

Override provider paths with `~/.config/fainder/config.toml`:

```toml
[paths]
codex = "~/.codex"
claude = "~/.claude"
opencode = "~/.local/share/opencode/opencode.db"
hermes = "~/.hermes/sessions"
cursor = "~/Library/Application Support/Cursor/User/workspaceStorage"
copilot = "~/Library/Application Support/Code/User/workspaceStorage"
kiro = "~/Library/Application Support/kiro-cli/data.sqlite3"
```

Those are the macOS defaults; on Linux Cursor and Copilot default to
`~/.config/...` and Kiro to `~/.local/share/kiro-cli/data.sqlite3`.