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.

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:

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

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

All subcommands

The full list of aichat subcommands:

Session-taking commands share one lookup. They accept a full or partial ID, a session name, a rollout filename fragment, or a session file path across both agents. See Resolve for the exact precedence.

In a terminal, ambiguous actions show a numbered Rich table. Enter q, press Ctrl-C, or send end-of-input to cancel without changing anything. Non-terminal and machine-readable modes print the ambiguity and exit nonzero without prompting. --agent restricts the searched agent home. The bare aichat <session> shortcut routes through the same lookup as menu.

port uses the same resolver and picker. It has no --agent, so it searches both configured homes. A direct file path is classified from its content.

Session-reference behavior by command

The following commands use the shared Rich picker for ambiguous interactive queries:

aichat <session> and aichat menu <session>
trim, smart-trim, export, info, copy, move, and query
clone, rollover, lineage, and resume
delete, find-original, and find-derived
the agent-specific export-claude and export-codex commands
port

trim-in-place uses the picker for human-readable output, but its --json mode never prompts and always emits one JSON result or error object. The --json modes for info and lineage also fail deterministically instead of prompting.

move-account applies the same match tiers across all eligible source homes. Its picker includes the source home so equal names in different accounts remain distinguishable.

Every picker sorts candidates newest first. Selecting a number continues with that session. Entering q, pressing Ctrl-C, or sending end-of-input cancels before the command changes anything. Piped and other non-terminal input lists the candidates and exits nonzero.

Command	Description
`aichat`	Action menu for latest session(s)
`aichat <session>`	Action-menu shortcut by name, ID, filename, or path
`aichat resume [session]`	Resume with strategy options
`aichat rollover [session]`	Rollover to fresh session
`aichat trim [session]`	Trim session content
`aichat trim-in-place <session>`	Trim a Claude session in place
`aichat smart-trim [session]`	AI-guided trim of session content
`aichat clone [session]`	Clone a session file
`aichat menu <session>`	Interactive action menu
`aichat lineage [session]`	Show parent lineage chain
`aichat query [session]`	Query a session with AI
`aichat port <session>`	Port a session to the other agent

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

Command	Description
`aichat info [session]`	Show session metadata
`aichat export [session]`	Export session to text
`aichat export-claude [session]`	Export a Claude session to text
`aichat export-codex [session]`	Export a Codex session to text
`aichat copy [session]`	Copy session file
`aichat move <session> <new-project>`	Move session to another project
`aichat delete <session>`	Delete a session
`aichat move-account <session>`	Move a session between accounts

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

For help on any subcommand:

aichat <subcommand> --help