Agent Access

Agents (Claude Code sub-agents, Codex CLI, or any script) can use aichat programmatically to search session history and recover prior context without human interaction.

Installation

Part of the claude-code-tools package. See Quick Start for installation.

The --json flag

The key to agent access is the --json flag on aichat search. Instead of launching the interactive TUI, it outputs one JSON object per line (JSONL) that agents can parse with jq:

# Search and get structured output
aichat search "MCP server" --json

# Filter with jq
aichat search "auth" --json | jq '.session_id'

# Limit results
aichat search "refactor" --json -n 5

JSONL fields

Each line contains these fields:

Field	Description
session_id	Unique session identifier
agent	claude or codex
project	Project directory name
branch	Git branch at time of session
cwd	Working directory
lines	Number of lines in session
created	Session creation timestamp
modified	Last modification timestamp
first_msg	First user message (preview)
last_msg	Last message (preview)
file_path	Full path to the JSONL session file
derivation_type	null, trimmed, or continued
is_sidechain	Whether this is a sub-agent session
snippet	Matching text snippet

Session-searcher sub-agent

For Claude Code users, the aichat plugin provides a session-searcher sub-agent that handles the entire search-and-summarize workflow. It runs as a sub-agent (using the Task tool) so search results do not pollute your main context.

Use your session-searcher sub-agent to find
sessions where we discussed the auth design.

The sub-agent:

1. Runs aichat search --json with appropriate queries
2. Parses results with jq
3. Reads up to 3 session files for detail
4. Returns a concise markdown summary with key findings and session references

Tip

The session-searcher sub-agent uses the haiku model for efficiency. It is ideal for recovering context from older sessions without consuming your main session’s context window.

Session-search skill

For CLI agents without sub-agent support (e.g., Codex CLI), the session-search skill provides the same workflow as a direct skill invocation:

# The agent follows the skill instructions to:
# 1. Run aichat search --json -n 10 "query"
# 2. Parse results with jq
# 3. Read session files for detail
# 4. Return a focused summary

Note

If you are using Claude Code, prefer the session-searcher sub-agent over the skill. The sub-agent runs in a separate context so it does not consume tokens in your main conversation.

All subcommands

The full list of aichat subcommands:

Most of them share one lookup. info, export, copy, move, query, clone, rollover, lineage, smart-trim, trim, and resume all accept a full session id, a partial id (prefix, middle, or suffix fragment), a session name (set with /rename), a rollout filename fragment (e.g. 2026-03-25T14-50), or a session file path — across both agents, with the agent auto-detected. See Resolve for the exact match precedence.

An ambiguous query fails with the list of matching sessions rather than silently picking one. --agent restricts which agent home is searched; a session file path searches no home at all, so there --agent instead requires the file to belong to that agent. delete and menu keep their legacy id-or-path lookup, so the bare aichat <id> shortcut (which routes to menu) does too.

port accepts the same query forms, but resolves them slightly differently: it has no --agent, it searches both homes for every non-path query (a file path is classified from its content instead), and it calls a query ambiguous whenever each agent yields a match, even when one of them matched on a stronger tier.

Session management

Command	Description
aichat	Action menu for latest session(s)
aichat resume [id]	Resume with strategy options
aichat rollover [id]	Rollover to fresh session
aichat trim [id]	Trim session content
aichat smart-trim [id]	AI-guided trim of session content
aichat clone [id]	Clone a session file
aichat menu [id]	Interactive action menu
aichat lineage [id]	Show parent lineage chain
aichat query [id]	Query a session with AI
aichat port <session>	Port a session to the other agent

Search & index

Command	Description
aichat search [query]	Full-text search (TUI or --json)
aichat resolve <query>	Resolve a name/id to one session (--json)
aichat build-index	Rebuild the Tantivy index
aichat clear-index	Delete the index for fresh rebuild
aichat index-stats	Show index statistics

Export & info

Command	Description
aichat info [id]	Show session metadata
aichat export [id]	Export session to text
aichat copy [id]	Copy session file
aichat move <session> <new-project>	Move session to another project
aichat delete [id]	Delete a session

Find (legacy)

Command	Description
aichat find	Find sessions (all agents)
aichat find-claude	Find Claude sessions
aichat find-codex	Find Codex sessions
aichat find-original	Find original from derived
aichat find-derived	Find derived from original

Note

The find commands are legacy. Prefer aichat search for all discovery tasks.

For help on any subcommand:

aichat <subcommand> --help