f ai

Manage Claude Code, Codex, and Cursor sessions for the current project.

Flow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save. When you need to reopen a repo's session from another working directory, use --path <project-root> on resume or provider-specific continue. Cursor transcripts are supported for reading only.

Architecture note:

for the underlying transport split between wrapped Codex CLI, jd, and codex app-server, see docs/codex-interface.md

Quick Start

# Fuzzy-pick a recent session (Claude + Codex + Cursor)
f ai

# Provider-specific list/read
f ai claude list
f ai codex list
f ai codex sessions
f ai codex sessions --path ~/repos/mark3labs/kit
f ai cursor list
f codex resolve "latest"
f codex resolve "https://linear.app/.../project/.../overview" --json
f codex open "continue the deploy work"
f codex agent list
f codex agent show commit
f ai claude resume <session-id-or-name>
f ai codex resume <session-id-or-name>
f ai codex resume --path ~/work/example-project
f ai codex continue --path ~/work/example-project
f ai codex find --path ~/repos/openai/codex "where does codex store"
f ai codex find --all-history --path ~/repos/openai/codex "older migration plan"
f ai codex find --recent-days 30 --path ~/repos/openai/codex "thread/read"
f ai codex find --json --limit 5 --path ~/repos/openai/codex "thread/read"
f codex connect --path ~/repos/openai/codex --exact-cwd --json "app-server"
f codex connect --all-history --path ~/repos/openai/codex "old designer cutover"
f ai cursor context - /path/to/repo 3
f cursor copy

# Save a memorable alias for a session
f ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385

Session Sources

Claude: ~/.claude/projects/<project-path>/*.jsonl
Codex: ~/.codex/sessions/**/*.jsonl (Flow matches by session_meta.cwd)
Cursor: ~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl
Saved aliases: .ai/sessions/claude/index.json in your repo

Resume Behavior (Important)

TTY requirement

Resume is interactive by design.

f ai claude resume ... requires a terminal TTY.
f ai codex resume ... requires a terminal TTY.
In non-interactive shells, Flow exits with a clear error and non-zero status.
Cursor does not currently expose a Flow resume/continue path; use list, copy, or context.

Claude exact-ID behavior

If you pass an explicit session (name, id, or id-prefix), Flow is strict:

it attempts claude --resume <id>
if Claude cannot open that exact session, Flow fails
Flow does not auto-fallback to --continue for explicit sessions (prevents opening the wrong conversation)

Claude no-arg behavior

For f ai claude resume with no argument:

Flow picks most recent Claude session for this project
if that resume fails, Flow may fallback to claude --continue in the same cwd (TTY only)

Codex behavior

For Codex, Flow runs:

codex resume <id> --dangerously-bypass-approvals-and-sandbox

No fallback is applied on resume failure; Flow returns non-zero.

Codex open and resolve

Use open when you want one Codex entrypoint that stays conservative about context:

f codex open
f codex open "continue the deploy work"
f codex open "resume latest"
f codex open --path ~/work/example-project "what was I doing here"
f codex resolve "https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview" --json
f codex doctor --path ~/work/example-project

Behavior:

no query: start a fresh Codex session in the target repo
explicit session lookup queries like latest, resume session, ordinals, or session IDs: resume the matching Codex session
explicit recovery prompts like what was I doing or continue the ... work: build a compact recovery handoff and start a new session
matching reference resolvers: inject only compact resolver output, then append the user request
otherwise: start a new session with the raw query and no extra wrapper text

This keeps prompt cost flat unless Flow has a strong reason to recover or unroll context. Use f codex doctor to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.

Codex connect and find

f codex connect and f ai codex find now use a Flow-managed local session-search index before falling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt from the Codex state DB when needed, and keeps transcript snippets for better recall on natural language queries.

By default, search now prefers sessions from roughly the last 7 days for faster and more accurate ranking on active work, then automatically widens back to the full session history when the recent window looks weak or sparse.

Useful commands:

f codex connect --path ~/repos/openai/codex --exact-cwd "app-server"
f codex connect --path ~/repos/openai/codex --exact-cwd --json "thread/read"
f codex connect --all-history --path ~/repos/openai/codex "old migration plan"
f ai codex find --path ~/repos/openai/codex "where does codex store"
f ai codex find --recent-days 30 --path ~/repos/openai/codex "thread/read"
f ai codex find --json --limit 5 --path ~/repos/openai/codex "where does codex store"

Behavior:

connect stays the interactive handoff path and returns the exact session match
connect --json prints the selected session instead of attaching
find still resumes the top hit
find --json is read-only and prints ranked candidates for inspection/eval work
by default both commands prefer the last 7 days first, then widen if the recent window is weak
use --recent-days <N> to widen the preferred recent window without fully disabling recency bias
use --all-history to search the full history immediately
if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session

Codex sessions after a crash or restart

If your Mac restarts and you lose the live Codex terminals, use:

f ai codex sessions
f ai codex sessions --path ~/repos/mark3labs/kit

Behavior:

lists recent Codex sessions for the current path
sorts by the last message timestamp descending
shows the stable session id plus a preview of the latest message
the numeric index matches continue, so you can reopen quickly

If you want to read or hand off a session instead of reopening it, use the native session bridge in Codex chat:

see codex in ~/repos/mark3labs/kit
see 019cd046 codex session
read 019cd046 codex session deeply

Examples:

f ai codex continue 1 --path ~/repos/mark3labs/kit
f ai codex continue 019cd046 --path ~/repos/mark3labs/kit
f ai codex sessions --path ~/repos/mark3labs/kit --json

Optional `flow.toml` resolver config

You can teach f codex open and f codex resolve to unroll repo-specific references:

[codex]
auto_resolve_references = true
prompt_context_budget_chars = 900
max_resolved_references = 1
sync_workflow_command = "./scripts/sync-safe"

[[codex.reference_resolver]]
name = "linear"
match = ["https://linear.app/*/issue/*", "https://linear.app/*/project/*"]
command = "my-linear-tool inspect {{ref}} --json"
inject_as = "linear"

Notes:

configure this in repo flow.toml or global ~/.config/flow/flow.toml
{{ref}}, {{query}}, and {{cwd}} are available in resolver commands
built-in Linear URL parsing works even without a custom resolver
resolver output is compacted before prompt injection
prompt_context_budget_chars hard-caps injected context before your request is appended
max_resolved_references prevents broad unrolling from bloating one turn
sync_workflow_command lets plain sync branch route into a repo-specific safe sync command instead of improvised Git/JJ steps

Optional runtime skill transport

Flow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.

Enable it globally with:

f codex enable-global --full
f codex doctor --path ~/docs --assert-runtime --assert-schedule

Or configure it manually with:

[codex]
runtime_skills = true

[options]
codex_bin = "~/code/flow/scripts/codex-flow-wrapper"

For the ~/code/flow repo specifically, the intended in-repo shape is:

[options]
codex_bin = "~/code/flow/scripts/codex-flow-wrapper"

[codex]
runtime_skills = true
auto_resolve_references = true
prompt_context_budget_chars = 1200
max_resolved_references = 2

[[codex.skill_source]]
name = "run-control-plane"
path = "~/run"
enabled = true

That keeps a fresh checkout Codex-first even before machine-local setup is remembered.

Current first-slice behavior:

f codex open "write plan" can attach a tiny plan-writing runtime skill
the runtime skill is exposed only for the launched Codex process
Flow keeps the generated runtime state under ~/.config/flow/codex/runtime

Inspect or clear runtime state:

f codex runtime show
f codex runtime clear
f codex log status
f codex log sync --limit 400
f codex memory status
f codex memory query --path ~/code/flow "codex control plane runtime skills"
f codex memory recent --path ~/docs
f codex doctor

Assertive health checks:

f codex doctor --path ~/docs --assert-runtime
f codex doctor --path ~/docs --assert-schedule
f codex doctor --path ~/docs --assert-learning
f codex doctor --path ~/docs --assert-autonomous

--assert-learning is intentionally strict: it fails until Flow has real logged events, grounded outcome samples, and a non-empty scorecard for that target.

Built-in plan writer:

cat <<'EOF' | f codex runtime write-plan --title "Example Plan"
# Example Plan

- item
EOF

By default this writes to today's ~/docs/plan/<day-of-month>/ bucket, for example ~/docs/plan/23/ on the 23rd day of the month.

Completed j sessions are also mirrored automatically into ~/log/.ai/docs/session-changes/ through jd, so durable home-log notes exist even when a repo-local .ai/docs/ promotion never happens.

Run-owned agent bridge

Flow can execute run-owned Codex agents directly without copying their specs or prompts into ~/code/flow.

Useful commands:

f codex agent list
f codex agent list --json
f codex agent show commit
f codex agent run planner --path ~/code/flow "make a 3 phase rollout plan"
f codex agent run commit --path ~/repos/openai/codex "review the current diff and draft a safe commit"
f codex agent run planner --json --path ~/code/flow "reply with exactly: ok"

Behavior:

Flow bridges into ~/run/scripts/agent-router.sh
the run-owned agent still executes through its own spec/runtime path in ~/run
--path controls the repo/worktree cwd used for the agent run
run returns the agent's final output plus any durable artifact/trace paths
f codex doctor --path <repo> reports whether the run-agent bridge is ready

Repo-local readiness check:

f codex doctor --path ~/code/flow --assert-runtime --assert-schedule
f codex skill-source list --path ~/code/flow
f codex agent list

Skill eval and background refresh

Flow can learn which runtime skills are actually worth injecting from local Codex usage history without replaying Codex in the hot path.

Useful commands:

f codex eval --path ~/work/example-project
f codex memory sync --limit 400
f codex memory recent --path ~/work/example-project --limit 12
f codex skill-eval show --path ~/work/example-project
f codex skill-eval run --path ~/work/example-project
f codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168
f codex telemetry status
f codex telemetry flush --limit 200
f codex trace status
f codex trace current-session --json
f codex trace inspect <trace-id> --json
f codex project-ai show --path ~/work/example-project --json
f codex project-ai recent --limit 12 --json
f codex skill-source list --path ~/work/example-project
f codex skill-source sync --path ~/work/example-project --skill find-skills
f codex agent list
f codex agent run planner --path ~/work/example-project "summarize the next rollout slice"

The Codex memory mirror:

stores durable indexed memory under the Jazz2 root (~/.jazz2/... or ~/repos/garden-co/jazz2/.jazz2/...)
mirrors Flow’s route/outcome history into SQLite with WAL enabled
extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)
adds bounded live code-path retrieval for explicit repo references, so prompts like see ~/code/flow ... can inject likely files such as src/ai.rs or docs/... without dumping raw source
indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during memory query / codex resolve
adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files
biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and src/... paths; summary/docs prompts prefer doc headings and docs paths
stays best-effort so failed memory writes do not block normal Codex coding turns

The project-ai manifest:

gives jd a bounded metadata view of repo-local .ai/ scaffolding
records counts and latest paths for skills, docs, reviews, tasks, and todos
keeps default context fill minimal by exposing only compact hints, not raw content
tracks query counts and recent repo usage so you can see whether the feature is actually being used
is refreshed again by f codex skill-eval cron, so the mirror heals even if a hot-path write is skipped
is queried automatically for explicit repo references during f codex open / f codex resolve

What cron does:

scans only recent logged Flow Codex events
syncs recent skill-eval logs into the Jazz2-backed memory mirror
skips missing/moved repo paths
rebuilds scorecards for a bounded number of recent repos
never launches Codex or replays network work in the background

For your use case, this keeps learning cheap and safe enough to run regularly.

Trace inspection for Flow-managed Codex sessions

Flow now assigns a trace envelope to all Flow-managed Codex launches, not just special workflows like check <github-pr-url>.

That means sessions started or resumed through:

j ...
k <session-id>
f codex open ...
f codex resume ...
f codex continue ...

carry FLOW_TRACE_* env vars and emit at least one compact Flow telemetry event, so the session becomes remotely inspectable.

Useful commands:

f codex trace status
f codex trace current-session --json
f codex trace inspect <trace-id> --json

Behavior:

trace status checks whether Maple MCP reads are configured and reachable
trace current-session reads the active FLOW_TRACE_ID from the current Flow-managed Codex session, flushes recent Flow telemetry once, then attempts a remote trace read
if Maple reads are partially configured but tenant access is still blocked, Flow returns the current trace metadata plus readError instead of failing without context

This keeps the workflow autonomous from inside Codex itself: once the session was started through Flow, you can inspect the current trace without manually copying ids.

f codex eval --path ... is the joined operator report:

current runtime/doctor state
recent route mix and context cost
grounded skill scorecard highlights
concrete “what to improve next” recommendations
commands to deepen or fix the current state

If jd is running, it also keeps recent completion reconciliation warm and now does a bounded background scorecard refresh, so the eval report does not go stale as quickly between manual runs.

If the native session bridge skill is installed, jd also prewarms compact handoff capsules for recent native Codex sessions whenever the Codex state DB changes. That keeps the exact handoff path cheap, so pasting 019d... codex session into another chat is usually already a warm cache hit instead of the first lookup having to build the capsule from the rollout.

Optional telemetry export follows the same local-first pattern: Flow keeps local Codex logs canonical, and if FLOW_CODEX_MAPLE_* env vars are set it can export redacted route/context/outcome spans to Maple without shipping raw prompts or full repo paths. Use:

f codex telemetry status
f codex telemetry flush --limit 200

For local-only secrets, prefer f env set --personal .... On macOS you may need f env unlock once per day for background reads. Flow-launched Codex sessions also inherit the same FLOW_CODEX_MAPLE_* values from the personal store, while explicit shell env still wins for one-off tests.

When jd is running, the daemon also performs a bounded background export pass so the external analytics view stays warm.

macOS launchd schedule for skill-eval

If you want scorecards to stay fresh automatically on macOS:

f codex-skill-eval-launchd-install
f codex-skill-eval-launchd-status
f codex-skill-eval-launchd-logs

f codex enable-global --full installs this schedule for you.

Default schedule:

every 30 minutes
scan up to 400 recent events
rebuild up to 12 recent repo scorecards
ignore repos not seen in the last 168 hours

You can tune install-time bounds:

f codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72
f codex-skill-eval-launchd-install --dry-run

Remove it with:

f codex-skill-eval-launchd-uninstall

Cursor behavior

Cursor transcripts are read-only in Flow:

f ai cursor list opens a picker and copies the selected transcript
f ai cursor copy copies the latest Cursor transcript for this repo
f ai cursor context ... copies the last N exchanges
f cursor ... is a shortcut for the same provider-specific read commands

Cross-directory resume

You can target another repo without changing directory:

f ai codex resume --path ~/work/example-project
f ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4
f ai codex continue --path ~/work/example-project

resume --path <repo> resolves the requested session against that repo instead of the current cwd
continue --path <repo> resumes the latest session for that repo
explicit full Codex IDs still work directly even when your current cwd is different

Session Selectors

resume accepts:

saved alias from .ai/sessions/claude/index.json
full session ID
ID prefix (8+ chars)
numeric index from list output (1-based)

Examples:

f ai resume my-feature
f ai resume a38cf8bf
f ai claude resume 2
f ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4
f ai cursor context 382ef1a3 /path/to/repo 2

Content Copy Commands

# Copy full conversation to clipboard
f ai copy
f ai copy <session>

# Copy last N prompt/response turns
f ai context
f ai context <session> <path> <count>

Use - as session placeholder to trigger fuzzy selection:

f ai claude context - /path/to/repo 3
f ai cursor context - /path/to/repo 3

Project Workflow (Recommended)

Start from repo root and inspect tasks: f tasks list
Resume exact session when continuing prior work: f ai claude resume <id> or f ai codex resume <id>
Keep context current: f skills sync then f skills reload
Validate through tasks: f test-related / f test
Commit through Flow gates: f commit

This keeps sessions, tasks, skills, and commit quality checks in one loop.

Everruns Bridge Mode

Flow also supports running a prompt through Everruns while routing client-side seq_* tool calls to local seqd:

f ai everruns "open Safari and take a screenshot"

Key points:

This path is additive. It does not replace f ai claude ... or f ai codex ....
Flow now reuses Seq's canonical Everruns bridge for:
- seq_* tool definitions injected into new sessions
- tool-name normalization (seq_open_app, seq.open_app, seq:open-app)
- request correlation IDs (request_id, run_id, tool_call_id)
Event transport is SSE-first (/sse) with automatic fallback to polling (/events) if SSE is unavailable.
Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when SEQ_EVERRUNS_MAPLE_* env vars are configured.
Existing Flow features remain unchanged (f seq-rpc, session resume/copy/context flows).

Setup and validation details are documented in:

docs/everruns-seq-bridge-integration.md
docs/everruns-maple-runbook.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

f ai

Quick Start

Session Sources

Resume Behavior (Important)

TTY requirement

Claude exact-ID behavior

Claude no-arg behavior

Codex behavior

Codex open and resolve

Codex connect and find

Codex sessions after a crash or restart

Optional `flow.toml` resolver config

Optional runtime skill transport

Run-owned agent bridge

Skill eval and background refresh

Trace inspection for Flow-managed Codex sessions

macOS launchd schedule for skill-eval

Cursor behavior

Cross-directory resume

Session Selectors

Content Copy Commands

Project Workflow (Recommended)

Everruns Bridge Mode

Uh oh!

FilesExpand file tree

ai.md

Latest commit

History

ai.md

File metadata and controls

f ai

Quick Start

Session Sources

Resume Behavior (Important)

TTY requirement

Claude exact-ID behavior

Claude no-arg behavior

Codex behavior

Codex open and resolve

Codex connect and find

Codex sessions after a crash or restart

Optional flow.toml resolver config

Optional runtime skill transport

Run-owned agent bridge

Skill eval and background refresh

Trace inspection for Flow-managed Codex sessions

macOS launchd schedule for skill-eval

Cursor behavior

Cross-directory resume

Session Selectors

Content Copy Commands

Project Workflow (Recommended)

Everruns Bridge Mode

Optional `flow.toml` resolver config