DEV Community: Little Pan

Why Grok was the next agent PonyMux supported

Little Pan — Fri, 02 Oct 2026 10:02:31 +0000

Grok Build isn't the coding agent most people run. Plenty of agents have more users. It still got PonyMux support next, for one reason: it can search X.

PonyMux 0.11.3 supports the Grok Build CLI, the grok command, the same way it supports Claude Code and Codex. Each Terminal running Grok shows its live status. Approvals mark it Waiting for you. Its conversations show up in search, and you can resume, fork, or hand them off to another agent. The Inspector shows its model and context, and the usage card shows where you are in your billing period.

Why Grok, and why now?

A lot of what I want to know about my tools never makes it into the docs. A library ships a breaking change and the first reports are on X. An API starts returning odd errors and someone has already posted the workaround. A new model comes out and the useful takes are in replies, not in blog posts.

Grok Build has an X search tool built in. It can look that up in the middle of a task, next to reading files and running commands. Claude Code and Codex can search the web, but neither ships a way to search X.

That made Grok the agent I actually wanted in my Terminal list, not just the next one on a list sorted by users.

Not the biggest agent. The one that can read X.

What works with Grok in PonyMux?

Everything that already worked for Claude Code and Codex:

Status on the Terminal row: Running, Waiting for you, Unread, Standing by, Will come back, Error.
Approvals that mark the Terminal as Waiting for you and clear as soon as you answer.
Search across your Grok conversations with ⌘K, including the feedback you type when you reject a tool call.
Resume and fork from the Inspector or the Sessions panel.
Handoff to Claude Code or Codex, and from them to Grok.
The Inspector, with model, reasoning effort, and context.
Usage on the Grok card in Agent Integrations.

Subagents count too. When a Grok subagent asks for approval, the main session's Terminal shows it.

How does PonyMux know Grok is waiting for you?

Grok sends a hook event when it asks for approval, but nothing when you answer. Without that second event, the Terminal would stay on Waiting for you after you'd already said yes.

So PonyMux reads the key you press in Grok's approval menu. Pick an option with a number key or Return, and the status changes right away.

What does the Inspector show for a Grok session?

Grok writes more about the session than the other two agents do, so the Inspector shows more. Next to the model and reasoning effort, the context line reads as used out of total, like 23k / 256k in context. For Claude Code it's only the tokens in use, and Codex sessions show no count.

The Session section has the same actions as the other agents: Resume, Fork Session, and a Handoff to… menu that lists the other two agents.

Can I hand a session from Claude Code to Grok?

Yes. Handoff works between all three agents, in any direction. Pick Handoff to… in the Inspector and choose the agent. PonyMux writes a handoff file with the session's summary and last five exchanges, then starts the other agent in the same folder with a prompt to read it. The original session stays as it was, so you can still resume it.

Where does the Grok usage number come from?

The Grok card in Agent Integrations shows one bar for your current billing period, labeled 7d or 30d. PonyMux reads the numbers Grok last wrote to its own log, so they're as fresh as your last Grok turn. It doesn't read your Grok credentials.

How do I set it up?

Install Grok Build from x.ai/cli, then select the link button at the bottom of the PonyMux sidebar and click Connect on the Grok card. PonyMux asks before it writes anything, and for Grok it adds a single file, ~/.grok/hooks/ponymux.json, without touching your other hooks. Start a new grok session in a PonyMux Terminal and its status shows up on the row.

For the details on each provider, see Agent integrations.

How to know which Claude Code or Codex agent needs you

Little Pan — Tue, 29 Sep 2026 12:18:23 +0000

You start three agents and go read something. Twenty minutes later one of them has been waiting ten minutes for approval to run npm install. Another finished long ago. The third is still working. You find out by clicking through every tab.

Both agents can tell you when they need you. The defaults just need a little help:

Claude Code: notifications come from your terminal. Pick the channel in /config, or add a Notification hook.
Codex: desktop notifications are on by default, but only while the terminal isn't in front. Tune them under [tui] in ~/.codex/config.toml.
Name the project: a short hook script puts the folder name in the notification title, so you know which agent it is.
The catch: a notification tells you something happened. It doesn't take you back to the right tab.

When do Claude Code and Codex notify you?

Claude Code sends a notification when it needs permission to use a tool, and when it has finished and you've been idle for a minute. It sends it through your terminal. In iTerm2, Ghostty, and kitty that's a desktop notification. In Apple Terminal it's the bell. Change the channel with /config inside a session. The Notifications setting offers the terminal-specific options, the bell, or off.

Codex sends a desktop notification when a turn finishes and when it asks for approval to run a command or edit files. By default it only does this while the terminal is in the background, which is usually what you want. The settings live in ~/.codex/config.toml:

[tui]
notifications = true                 # or a list, such as ["approval-requested"]
notification_condition = "unfocused" # "always" to notify even when the terminal is in front

Both work well with one agent. With four, "Claude Code needs your permission" doesn't say which of the four.

How do I see which project a notification is about?

Use a hook. Both agents can run a command on these events and pass it a JSON description that includes the working directory. This script turns that into a notification titled with the agent and folder name:

#!/bin/sh
# ~/bin/agent-notify.sh — usage: agent-notify.sh "Claude Code"
jq -r --arg agent "$1" '
  (.message // (if .hook_event_name == "PermissionRequest" then "Needs your approval" else "Finished its turn" end)) as $body
  | "display notification \($body | @json) with title \("\($agent) · \(.cwd | split("/") | last)" | @json)"
' | osascript >/dev/null

Save it and run chmod +x ~/bin/agent-notify.sh. It needs jq, which ships with macOS 15 and later.

For Claude Code, add a Notification hook to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "~/bin/agent-notify.sh 'Claude Code'" }]
      }
    ]
  }
}

For Codex, add Stop and PermissionRequest hooks to ~/.codex/hooks.json:

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/bin/agent-notify.sh Codex" }] }],
    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "~/bin/agent-notify.sh Codex" }] }]
  }
}

Codex asks you to review new hooks the next time it starts, and /hooks inside a session shows what's installed. The script prints nothing, so it doesn't change whether a permission request is approved. Now a notification reads "Claude Code · api: Claude needs your permission to use Bash", and you know where to go. If you now get two notifications for the same event, turn the built-in one off: Notifications in Claude Code's /config, or notifications = false under [tui] for Codex.

Why does a notification still leave me hunting for the tab?

Because it comes from the agent, not from the window it runs in. Clicking a display notification banner opens Script Editor. Clicking the terminal's own notification brings the terminal forward, but not necessarily the right tab. With several agents per window, you still scan tabs for the one with the prompt.

A hook can't fix this, and neither can the terminal settings. What's missing is a place that tracks each agent's state next to the terminal it runs in.

Can I see every agent's status at a glance?

That's what PonyMux does. Each Terminal running Claude Code or Codex shows the agent's state on its row in the Terminal list:

Waiting for you: approval or an answer is needed.
Running: the agent is working.
Unread: it finished something you haven't looked at yet.
Standing by: ready for the next prompt.
Will come back: the agent is idle, but background work or a subagent it started is still running.
Error: it stopped because something went wrong.

Agent status on each Terminal row: running, waiting for you, standing by, unread, and will come back.

When any Terminal in the list has a status, a badge at the bottom of the list shows the count. Click it to jump to the next one, and click again to cycle through the rest. The list order doesn't change.

To see only the agents, select Agents in the sidebar. It lists every Terminal where Claude Code or Codex is running right now, plus the ones whose agent was still active when you last quit PonyMux, so four agents spread across different projects and Lists show up in one place. Running agents come first, then the ones left from your last quit, each group in your usual Terminal order. It isn't a folder you manage: Terminals join and leave it as their agents start and stop.

The Agents collection in the sidebar lists the Terminals running Claude Code or Codex, across every project and List.

PonyMux also sends its own notifications for finished turns, permission requests, input requests, and errors, and you can set each kind to Off, Silent, or Sound in Settings → General. Clicking a notification opens PonyMux on the Terminal it's about, which is the step a hook can't do. Agent status needs the Claude Code or Codex integration, which you connect once from the bottom of the sidebar.

For every status and notification setting, see Agent Status and Notifications.

Originally published on ponymux.com, where the demos are interactive.

How to pick up Claude Code and Codex sessions after a restart

Little Pan — Tue, 29 Sep 2026 12:15:24 +0000

On Friday you had four agents going: one on the API, one on the docs, a Codex session running tests, and one you'd parked halfway through a refactor. Over the weekend macOS installed an update and restarted. On Monday the tabs are gone, and you don't remember which session was in which folder.

The conversations aren't lost. What stopped is the processes:

What's saved: every message up to the moment the agent stopped. Claude Code and Codex write the transcript as they go.
What isn't: a reply that was still being written, and the running process itself.
Bring one back: in the project folder, run claude --continue or codex resume --last.
Bring several back: list your most recent sessions with their folders, pick the ones you were using, and resume each. There's a command below that prints them for you.

What happens to a running agent when I close the terminal or restart?

Closing a terminal window, quitting the terminal app, logging out, and restarting all end the processes inside, including Claude Code and Codex. Whatever the agent had already written to its transcript stays on disk. A turn that was halfway through is cut off.

Sleep is different. When the Mac sleeps, processes pause and pick up where they were when it wakes. A request that was in flight to the model can fail while the network is down. If the agent reports an error after wake, tell it to continue.

Some terminal apps reopen your windows after a restart, with the same folders and scrollback. That looks like the session is back, but it's a fresh shell. The agent isn't running in it.

How do I resume the last session in a project?

Open a terminal in the project folder and run:

# Claude Code
claude --continue

# Codex
codex resume --last

Both pick the most recent session from the current directory. If you ran more than one session in that folder, use the picker instead: claude --resume or codex resume. The folder matters. Run the same command from your home directory and you get a different session, or none.

How do I bring several sessions back at once?

When several agents were running in different folders, you need each session's folder and ID. The transcripts don't record whether a session was still running, but the ones you were using before the restart are usually the most recently written. These commands print one ready-to-run line per recent session, most recently active first:

# Claude Code: the 10 most recent sessions
ls -t ~/.claude/projects/*/*.jsonl | head -10 | while read -r f; do
  jq -r 'select(.cwd) | "cd \(.cwd | @sh) && claude --resume \(.sessionId)"' "$f" | head -1
done

# Codex: the 10 most recent sessions
ls -t ~/.codex/sessions/*/*/*/*.jsonl | head -10 | while read -r f; do
  jq -r 'select(.type == "session_meta") | "cd \(.payload.cwd | @sh) && codex resume \(.payload.id)"' "$f" | head -1
done

Each line looks like cd '/Users/you/code/api' && claude --resume 8e539d93-…. Pick the ones you were working on, open a tab per session, and paste its line. A session that sat idle for a long time can fall below newer ones, so raise head -10 if one is missing. Skip lines whose folder no longer exists, such as a worktree you've since removed.

Both commands read each tool's transcript files directly. That format is internal and can change between releases, so treat these as a convenience, not an interface. If you turned on Codex's experimental compression, older sessions are .jsonl.zst files and won't show up in the list. Both commands need jq, which ships with macOS 15 and later. The pickers work too: press Ctrl+A in claude --resume to see every project, or run codex resume --all. The list above is faster when you want several sessions back at once.

How do I keep an agent running while I'm away?

Two different problems, two different tools.

The Mac going to sleep. An idle Mac sleeps, and the agent pauses with it. caffeinate keeps the system awake for as long as the command inside it runs:

caffeinate -i claude

-i prevents idle sleep. It doesn't stop sleep when you close the lid or choose Sleep yourself.

The terminal closing. A terminal multiplexer such as tmux keeps processes running after the window closes:

tmux new -s api      # start a session, then run claude or codex inside it
tmux attach -t api   # later, from any terminal window

tmux survives closing the terminal and quitting the terminal app. It doesn't survive a restart or a logout. After a restart you're back to resuming sessions.

Can I skip looking up folders and session IDs?

In PonyMux, each Terminal is a saved record: its name, folder, List, and the sessions that ran in it. Quitting PonyMux or restarting the Mac ends the processes, but the Terminals stay where you left them. They come back sleeping, marked with a zzz badge.

Select a sleeping Terminal that had an agent conversation, and PonyMux shows the last exchange from that session, so you can see where it stopped. With automatic resume on, a short countdown starts. When it runs out, PonyMux resumes that exact session in the Terminal's folder. You can resume right away, pause the countdown, or choose Shell Only for a plain shell instead.

A sleeping Terminal after a restart. The last exchange is on screen, and Resume counts down before it reopens the session.

That replaces the list-and-paste step above: each Terminal already knows its folder and session, so bringing four agents back is four clicks. Automatic resume can be turned off in Settings → General. If the transcript is gone, for example after Claude Code's 30-day cleanup, the Terminal says so and offers a shell instead.

For the idle-sleep problem, the coffee-cup Keep Awake button at the bottom of the sidebar prevents idle sleep and App Nap while it's on. Like caffeinate -i, it doesn't override closing the lid.

The Keep Awake button in the PonyMux sidebar footer.

For how sleeping and waking work, see Terminal Lifecycle. To find an older session by what was said in it, see Claude Code conversation history.

Originally published on ponymux.com, where the demos are interactive.

How to fork a Claude Code or Codex session to try another approach

Little Pan — Tue, 29 Sep 2026 12:08:26 +0000

The agent has a plan, and it's halfway through. You want to see what the other approach looks like, the one you talked it out of an hour ago. If you ask in the same session, you pollute the context it has built up. If you start a new session, you lose that context.

A fork gives you both. It copies the conversation so far into a new session, and the original stays exactly where it was:

Claude Code, inside a session: /branch. You're moved into the copy, and the original can be resumed later.
Claude Code, from the shell: claude --resume <session-id> --fork-session.
Codex, inside a session: /fork. From the shell: codex fork <session-id>, or codex fork --last.
The catch: a fork copies the conversation, not your files. Two sessions editing the same checkout will step on each other. Give the fork its own git worktree.

When should I fork instead of just continuing?

Fork when you want to keep the current thread intact:

Trying a different approach. The fork explores the alternative. If it doesn't work out, the original session still has the plan it was following, untouched.
Comparing two approaches. Fork, then let each session build its version in its own worktree. Compare the diffs, not the arguments.
Asking a side question. A tangent that isn't worth keeping in the main context: how some library works, or a quick review of one file.

If you just want to undo the last few steps, you don't need a fork. Claude Code's /rewind (also /checkpoint) restores the conversation, the code, or both to an earlier message.

How do I fork a Claude Code session?

Inside a running session, type:

/branch try-event-queue

Claude Code copies the conversation into a new session and switches you into it. The name is optional. The fork's title ends in "(Branch)", so it's easy to tell apart in /resume. The confirmation message includes the command to get back to the original, claude -r <original-session-id>.

From the shell, add --fork-session to a resume:

# Fork the most recent session in this directory
claude --continue --fork-session

# Fork a specific session
claude --resume <session-id> --fork-session

Without --fork-session, both commands reopen the original session and keep adding to it.

How do I fork a Codex session?

Inside a running session, type /fork. From the shell:

# Pick a session to fork from a list
codex fork

# Fork the most recent session in this directory
codex fork --last

# Fork a specific session
codex fork <session-id>

Like codex resume, the picker and --last only look at sessions from the current directory. Add --all to see every directory.

Codex has two more ways to branch. Press Esc twice to step back through your earlier prompts, pick one, and press Enter. Codex forks the conversation just before that prompt and puts the prompt back in the composer for you to edit. The original session keeps the full history. For a quick tangent, /side starts a side conversation in a temporary fork.

Does forking a session copy my code?

No. A fork copies the conversation. Both sessions still work in the same directory, on the same files. If the original agent is editing src/queue.ts while the fork rewrites it, you get a mess that neither of them planned.

Give the fork its own git worktree. A new worktree starts from your last commit, not from the files on disk, so uncommitted edits and new files don't come along. If the agent has been working for a while, commit first:

git add -A && git commit -m "wip: before fork"

You can squash or amend that commit later. Without it, the fork remembers changes that its worktree doesn't have. If you've used claude --worktree in this repo before, add .claude/worktrees/ to .gitignore first, or git add -A will pick up those worktree folders too.

Then fork into a worktree. Both CLIs can create one for you:

# Claude Code: fork into a new worktree under .claude/worktrees/try-event-queue
claude --worktree try-event-queue --resume <session-id> --fork-session

# Codex: fork into a new worktree under ~/.codex/worktrees
codex fork --worktree <session-id>

Claude Code puts its worktree on a new branch named worktree-<name>. Codex needs an explicit session ID here, since --last doesn't work with --worktree, and its worktree starts on a detached HEAD, so create a branch there (git switch -c try-event-queue) before you commit anything you want to keep.

Or create the worktree yourself and fork from inside it:

git worktree add ../myapp-event-queue -b try-event-queue
cd ../myapp-event-queue
claude --resume <session-id> --fork-session

The fork still has the whole conversation, even though it now runs in a different directory. When one approach wins, merge its branch and remove the other worktree by path, for example git worktree remove ../myapp-event-queue. git worktree list shows the paths, including the ones Claude Code and Codex created.

How do I keep track of which session is which?

Forks look alike in a session list, since they start from the same conversation. Name them when you create them:

Claude Code: /branch <name>, or /rename inside any session.
Codex: /rename inside the session.

A name that says what the fork is trying, such as "event queue" or "keep polling", makes the right session easy to find in claude --resume or codex resume a day later.

Can I fork without typing session IDs?

Yes. In PonyMux, select a Terminal that's running Claude Code or Codex, open the Inspector, and click Fork Session in the Session section. The same action is in each session's ⋯ menu in the Sessions panel.

The Inspector's Session section for a Claude Code session. Fork Session is right above Handoff.

PonyMux asks where to put the fork:

Here ends whatever is running in the current Terminal and starts the fork in its place.
New Terminal opens the fork next to the original, in the same list.

It runs claude --resume … --fork-session or codex fork … for you, in the session's working directory. A Terminal that holds a fork shows an Origin section in the Inspector, with Go to Source Session to jump back to the conversation it came from.

PonyMux doesn't create a worktree for the fork, and it always starts the fork in the original session's working directory. If the two sessions will edit files, commit first as described above, create the worktree yourself, open a Terminal in it, and run claude --resume <session-id> --fork-session there, or use codex fork --worktree. A session needs at least one saved exchange before it can be forked.

You also don't need to remember which session was which. Each PonyMux Terminal keeps a timeline of every Claude Code and Codex session that has run in it. Open the Sessions panel to see them, with their titles, recaps, and when each was last used. Click Resume on any row to go back to that exact session, not just the most recent one.

The Sessions panel lists every conversation that has run in this Terminal. Resume reopens the one you pick.

Resume needs the agent's transcript to still be on disk. Claude Code deletes transcripts after 30 days by default; see Claude Code conversation history for how to keep them longer.

For the details of Resume, Fork, and Handoff, see the Sessions docs. To move a task to the other agent instead of copying it, see How to hand off a task from Claude Code to Codex.

Originally published on ponymux.com, where the demos are interactive.

How to hand off a task from Claude Code to Codex (and back)

Little Pan — Tue, 29 Sep 2026 12:04:25 +0000

Claude Code and Codex are good at different parts of the same task. A split that works well: Claude Code writes the code, then Codex runs the smoke test. Codex has a Computer Use plugin that can open the built app on your Mac, click through it, and report what broke. For that to work, Codex has to know what was just built and what to check, without you explaining the whole task again.

The same goes for other reasons to switch: a usage limit halfway through a refactor, or a second opinion on a design.

Neither tool can open the other's conversations. What you can move is the context:

Write a handoff note. Ask the current agent to put the goal, what's done, what's left, and the decisions so far into HANDOFF.md.
Start the other agent from it. In the same directory, run codex "Read HANDOFF.md and continue the work described there.", or the same with claude.
Share project instructions. Claude Code reads CLAUDE.md and Codex reads AGENTS.md. Put @AGENTS.md in CLAUDE.md so both see the same rules.
The catch: the new agent starts a new session. It knows what the note says, not everything the first agent saw.

Why can't Codex just open my Claude Code conversation?

Each tool writes its own transcript format to its own folder. Claude Code uses ~/.claude/projects/, and Codex uses ~/.codex/sessions/. claude --resume only lists Claude Code sessions, and codex resume only lists Codex sessions. There is no import command in either direction.

So a handoff is never a transfer of the conversation. It's a new session that starts with enough context to keep going. The quality of the handoff comes down to what you put in front of the next agent.

What does the next agent need to know?

Less than the whole transcript, and more than the last message. A useful handoff answers five questions:

What's the goal, in one or two sentences?
What's done, and how was it checked?
What's left, in order?
Which decisions were made, and why? These are the ones the next agent would otherwise undo.
Which files matter, and what's still uncommitted?

The files themselves don't need to be in the note. Both agents work on the same directory, so the next one can read the code. What it can't read is your reasoning.

How do I write a handoff note?

Ask the agent that has the context to write it. It saw the dead ends and knows why things are the way they are. Paste this into the current session:

Write a handoff note to HANDOFF.md for another coding agent that will continue this work.
Include: the goal, what is done and how it was verified, what is left in order,
decisions we made and why, the files that matter, and anything uncommitted.
Be specific. Skip anything the next agent can read from the code.

For a smoke-test handoff, ask for the testing details too: how to build and launch the app, which flows changed, and what "working" looks like for each one. Then start Codex with a prompt that says what to do with the note, such as codex "Read HANDOFF.md and smoke-test the changes it describes."

Read the note before you hand it off. It's short, and it's the only thing the next agent knows about the conversation, so fix anything that's wrong or missing.

Commit HANDOFF.md or add it to .gitignore. Either is fine, as long as it doesn't slip into an unrelated commit.

How do I start Codex or Claude Code from the note?

Open a terminal in the same directory and pass the note as the first prompt:

# Claude Code → Codex
codex "Read HANDOFF.md and continue the work described there."

# Codex → Claude Code
claude "Read HANDOFF.md and continue the work described there."

Both CLIs take an initial prompt as an argument and start an interactive session with it. The new agent reads the note, looks at the files it names, and carries on. Watch the first few steps. If it starts redoing something the note says is finished, the note needs another line.

Stay in the same working directory. Both agents load project instructions and resolve paths from there, and a different checkout means different files.

Can the next agent read the full transcript instead?

It can, and sometimes that's useful for one detail the note left out. Tell it where the file is:

Claude Code: ~/.claude/projects/<project>/<session-id>.jsonl
Codex: ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl

Don't make it the main handoff. Transcripts are mostly tool output and metadata, they get large quickly, and the format is internal to each tool. A long session can fill much of the next agent's context before it does any work.

Claude Code's /export writes the current conversation as plain text. Pass a filename and it saves there, with the extension changed to .txt. That's easier for another agent to read than the JSONL, but it's still the whole conversation, not a summary.

How do I make both agents follow the same project rules?

Keep one file and point the other tool at it.

Option 1: import AGENTS.md from CLAUDE.md. Claude Code supports @path imports in CLAUDE.md. A CLAUDE.md that contains only this line makes Claude Code read your AGENTS.md:

@AGENTS.md

Option 2: let Codex read CLAUDE.md. If your rules already live in CLAUDE.md, add this to ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

Codex then uses CLAUDE.md in any directory that has no AGENTS.md. Without this setting, Codex doesn't see CLAUDE.md at startup.

What doesn't carry over in a handoff?

The conversation. The next agent has the note, not the transcript. Anything it needs has to be in the note or in the code.
Permissions and approvals. Each tool has its own settings. What you allowed in Claude Code isn't allowed in Codex.
Tools and integrations. MCP servers, skills, hooks, and custom commands are configured per tool. Set them up on both sides if the task depends on them.
The original session. It stays where it was. You can still resume it in its own tool, and you can hand off back later with a new note.

Can I hand off without writing the note myself?

Yes. PonyMux has a Handoff action on Claude Code and Codex sessions that have saved at least one exchange. With a Terminal selected, open the Inspector and click Handoff to Codex (or Handoff to Claude) in the Session section. The same action is also in each session's ⋯ menu in the Sessions panel.

The Inspector's Session section for a Claude Code session. Handoff to Codex sits under Fork Session.

PonyMux reads the session's transcript and writes a Markdown handoff file with:

the session title and working directory
a summary, when the session has one
the last five exchanges, with a one-line note for each command, file read, or edit
the path to the full transcript

It then starts the other agent in the session's working directory with a prompt to read that file. You choose where: Here ends whatever is running in the current Terminal and starts the new agent in its place. New Terminal opens one next to it in the same list and leaves the current one alone. The source session isn't changed, so you can still resume it.

It saves the copy-paste, not the judgment. The file holds recent turns, not a note written for the next agent, so for a long task it's still worth asking the agent for a proper handoff note first. Codex sessions saved in compressed .jsonl.zst form can't be handed off yet.

For the details of Resume, Fork, and Handoff, see the Sessions docs.

Originally published on ponymux.com, where the demos are interactive.

Claude Code conversation history: where it lives, how to search it, how to get it back

Little Pan — Tue, 29 Sep 2026 11:21:53 +0000

You closed the terminal. The conversation where you and the agent worked out the migration plan is gone from the screen, and now you need it back.

It isn't gone. Claude Code writes every conversation to your disk as it happens:

Where it lives: ~/.claude/projects/<project>/<session-id>.jsonl, one folder per working directory.
Reopen the last one here: claude --continue.
Pick an older one: claude --resume, or /resume inside a running session. Press Ctrl+A in the picker to see every project.
Search what was said: the transcripts are JSONL, so jq plus awk works. There's a command below.
The catch: Claude Code deletes transcripts older than 30 days by default. Raise cleanupPeriodDays in ~/.claude/settings.json if you want to keep them longer.

Codex and Grok Build work the same way with different paths and commands. Each has its own section below.

Where does Claude Code store conversation history?

Each conversation is a file at ~/.claude/projects/<project>/<session-id>.jsonl. The <project> folder name is your working directory with every non-alphanumeric character turned into -, so a session started in /Users/you/code/api lands in ~/.claude/projects/-Users-you-code-api/.

Each line in the file is one JSON object: a message you sent, a reply, a tool call, or some metadata. The format is internal to Claude Code and changes between releases, so treat it as something to read, not something to build on. For a readable copy of the current conversation, run /export.

There's one more file worth knowing about: ~/.claude/history.jsonl. It holds every prompt you've typed, with the project and time. It's what the up arrow and Ctrl+R read from, and the 30-day cleanup doesn't touch it.

How do I reopen a closed Claude Code conversation?

Command	Use it when
`claude --continue`	You want the most recent conversation in this directory
`claude --resume`	You want to pick from a list
`claude --resume <name>`	You named the session with `claude -n` or `/rename`
`claude --resume <session-id>`	You have the ID. Works from any directory as of v2.1.223
`/resume`	You're already in a session and want to switch

The picker shows sessions from the current directory first. Press Ctrl+A to widen it to every project on this machine, Space to preview a session before opening it, and start typing to filter the list. Ctrl+R renames the highlighted session, which makes it easier to find next time.

If you pick a session from another project, Claude Code copies a cd and resume command to your clipboard instead of opening it in the wrong directory.

After a restart, when several sessions in different folders need to come back at once, see How to pick up Claude Code and Codex sessions after a restart.

How do I search inside past Claude Code conversations?

The picker works when you remember roughly which session it was. When all you remember is something that was said, search the files. This prints the date, who said it, and the start of each matching message. It needs jq, which comes with macOS 15 and later. On older macOS, run brew install jq; on Debian or Ubuntu, sudo apt install jq.

q="migration"
for f in ~/.claude/projects/*/*.jsonl; do
  jq -r '
    select(.type == "user" or .type == "assistant")
    | (.message.content
       | if type == "string" then .
         else map(select(.type == "text") | .text) | join(" ")
         end) as $text
    | "\(.timestamp[0:10])  \(.type): \t\($text | split("\n") | join(" "))"
  ' "$f" | q="$q" awk '
    { i = index($0, "\t") }
    index(tolower(substr($0, i + 1)), tolower(ENVIRON["q"])) {
      print substr($0, 1, i - 1) substr($0, i + 1)
    }
  ' | cut -c1-160 | sed "s|^|$(basename "$f" .jsonl)  |"
done

The first column is the session ID, so claude --resume <session-id> takes you straight back. jq turns each message into one line of plain text, and awk looks for your query in that text only, ignoring case. The date and role columns aren't searched, so q="user" finds messages that mention "user", not every message you sent. The awk on macOS also ignores case for accented letters. On Debian and Ubuntu, the default awk is mawk, which ignores case only for ASCII letters, so type accented words the way they were written. Searching the raw files directly returns whole lines full of tool output and metadata, and misses queries with quotes or backslashes because JSON escapes them.

If the transcript is already gone, you can still search your own prompts:

jq -r '.display' ~/.claude/history.jsonl | grep -Fi -- "migration"

Why did my Claude Code history disappear?

Claude Code deletes transcripts, and a few related files, once they're older than cleanupPeriodDays. The default is 30 days. The minimum is 1, and 0 is rejected as invalid.

To keep conversations longer, set it in ~/.claude/settings.json:

{
  "cleanupPeriodDays": 365
}

It only protects conversations that haven't been deleted yet. Once a transcript is swept, Claude Code has no copy of it. A backup of your home folder, such as Time Machine, is the only way to get it back.

Two other things look like lost history but aren't. The picker only shows the current directory until you press Ctrl+A. And sessions started with claude -p or the Agent SDK are left out of the picker; you can still open one with claude --resume <session-id>.

Where is Codex CLI conversation history, and how do I search it?

Codex stores each session as ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl. Sessions you archive with codex archive move to ~/.codex/archived_sessions/, and codex unarchive brings them back. Your prompts are also in ~/.codex/history.jsonl. Codex doesn't delete old sessions on a schedule.

Command	Use it when
`codex resume --last`	You want the most recent session in this directory
`codex resume --last --all`	You want the most recent session from any directory
`codex resume`	You want to pick from a list of sessions in this directory
`codex resume --all`	You want the list across every directory
`codex resume <id-or-name>`	You know which one
`codex fork`	You want a copy to try another approach

This searches messages in both folders. Codex logs grow large, so it takes longer than the Claude Code search; on about 7 GB of sessions it runs in roughly a minute:

q="migration"
find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' | while read -r f; do
  jq -r '
    select(.type == "response_item" and .payload.type == "message")
    | select(.payload.role == "user" or .payload.role == "assistant")
    | (.payload.content | map(.text // empty) | join(" ")) as $text
    | "\(.timestamp[0:10])  \(.payload.role): \t\($text | split("\n") | join(" "))"
  ' "$f" | q="$q" awk '
    { i = index($0, "\t") }
    index(tolower(substr($0, i + 1)), tolower(ENVIRON["q"])) {
      print substr($0, 1, i - 1) substr($0, i + 1)
    }
  ' | cut -c1-160 | sed "s|^|$(basename "$f" .jsonl)  |"
done

Codex also saves context it adds for the agent as user messages, such as your AGENTS.md and environment details. A word that appears in your AGENTS.md can therefore match once in every session. Claude Code does the same with background task notifications. Skip those rows when you read the results.

Codex has an experimental option that compresses sessions older than a week into .jsonl.zst. It's off by default. If you turned it on, read those files with zstd -dc <file> before piping them to jq.

Where is Grok Build conversation history, and how do I search it?

Grok Build keeps each session in its own folder at ~/.grok/sessions/<folder>/<session-id>/. The folder name is your working directory, URL-encoded, so /Users/you/code/api becomes %2FUsers%2Fyou%2Fcode%2Fapi. Inside a session, updates.jsonl is the conversation log and summary.json holds the generated title and timestamps. If you set GROK_HOME, sessions live under that folder instead of ~/.grok.

Command	Use it when
`grok --resume`	You want the most recent session in this directory
`grok --resume <id-or-title>`	You know which one. Titles match without regard to case, so `/rename` a session you'll want again
`/resume`	You're already in Grok and want to pick from this directory's sessions
`grok sessions list`	You want the IDs, dates, and titles of this directory's sessions

Grok has search built in, in two places. In the /resume picker, start typing: it filters by title and also searches what was said, with content matches under Extended search results. From the shell, grok sessions search "migration" matches titles and first prompts only, and only for the current directory.

Grok doesn't delete old sessions on a schedule. A session stays until you remove it with /delete or grok sessions delete.

Can I search Claude Code, Codex, and Grok history without leaving the terminal?

Yes, if the search lives where you already run the agents. The commands above work, and I used them for a while. What I kept wanting was to search while I was already in the terminal, and to jump from a result straight back into the session.

That's what transcript search in PonyMux does. Press ⌘K, type what you remember, and the Transcripts filter shows matching messages from Claude Code, Codex, and Grok together, with your search terms highlighted. Pick a result and resume that exact session, not just the latest one in that directory.

It searches what's on your disk, so the same limits apply. A transcript that Claude Code's cleanup already deleted can't be found, and raising cleanupPeriodDays is still worth doing.

For scopes, ranking, and managing the index, see the Search docs.

Originally published on ponymux.com, where the demos are interactive.

How to Search Your Claude Code Conversation History

Little Pan — Tue, 22 Sep 2026 01:22:54 +0000

You talked through an approach with your agent a few days ago. The agent explained the tradeoffs, you picked a direction, and it wrote the code. Now you need that reasoning again — maybe for a code review, maybe because you're hitting an edge case the original conversation anticipated.

You know it's somewhere. Claude Code saves every conversation as JSONL under ~/.claude/projects/. Codex groups them by date under ~/.codex/sessions/. The full record is on your disk — your prompts, the agent's reasoning, every tool call. The problem isn't storage. It's retrieval.

What you can do today

Claude Code's --resume flag opens a session picker. You can scroll through recent sessions and select one to continue. It works when you remember roughly when the conversation happened and can recognize it in a list.

It doesn't search content. If you're looking for "that conversation where we discussed the migration" and it happened across three sessions over two days, --resume won't find it by topic.

The common workaround is grep:

grep -r "migration" ~/.claude/projects/

This works, technically. It also returns raw JSONL with tool-call metadata, system prompts, base64-encoded images, and content blocks nested several levels deep. Finding the actual conversation inside that output is its own project.

There are third-party tools that index these files — CLI searchers, desktop apps, VS Code extensions. They're useful, but they all live outside the terminal where the conversations happened.

The conversations are on your disk. The search isn't.

What if search lived where you work?

PonyMux 0.10 added full-text search across your Claude Code and Codex conversation history, built into the same Cmd+K search you already use to find Terminals.

Press Cmd+K, type a keyword, and results appear in two layers. The first layer matches Terminal names and metadata — the same search from 0.9. The second layer searches conversation content: every prompt you've typed, every response the agent gave, every tool it used. Both layers share one search bar and one set of scope pills.

The Transcripts pill filters to just conversation matches. Each result shows the session title, a matched snippet, the agent type, and when it was last active. Select one and the right side shows the matched messages with your search terms highlighted.

How the index works

The first time you launch 0.10, PonyMux builds a full-text index from your transcript files. It takes around 10–30 seconds depending on how many conversations you have. After that, new conversations are picked up within seconds via filesystem events.

The index uses FTS5 with trigram tokenization, which means it handles substring matches and CJK text without special configuration. A search for "migrat" finds "migration", "migrating", and "migrate". Chinese and Japanese terms match the same way.

The index is a separate SQLite database (search.db). It doesn't touch your metadata or your Terminals — you can rebuild it, pause it, or turn it off entirely from Settings → Advanced without affecting anything else.

Your agents have been keeping a complete record of every conversation. Now you can actually use it.

What changes about ended Terminals

This one is a side effect that turned out to matter more than I expected.

Before 0.10, selecting a sleeping Terminal showed a static screen capture — a frozen frame of whatever the terminal surface looked like when the process exited. It told you what was on screen, but not what the agent was thinking or what you'd asked it to do.

Now it shows the last conversation. The actual messages — your prompt, the agent's response, the tools it called — rendered directly in the Terminal area. You can read the exchange, decide whether to resume, and choose Resume or Shell Only.

The difference sounds small until you use it. A screenshot of a terminal says "the cursor was here." A conversation says "here's what we were working on and here's where we stopped."

Resume finds the right session

One more thing that fell out of transcript search: when you find a Terminal through search and hit Resume, PonyMux targets the matched session, not the most recent one. If search found a conversation from three days ago, that's what resumes.

A banner at the top shows the session name and date so you're never guessing which conversation you're about to continue.

The state of agent conversation search

This is still early. Claude Code deletes transcripts older than 30 days by default, so the search window has a built-in limit. Codex compresses older files to .zst, which PonyMux can't index. And the index itself is local — there's no cloud sync or cross-machine search.

But for the conversations that are on your disk right now, having them searchable from the same place you run your agents changes the daily workflow more than I expected. I stopped grep-ing JSONL files on day two.

For the full details — scopes, ranking, index management — see the Search docs.

Finding the right terminal in a room full of agents

Little Pan — Mon, 21 Sep 2026 01:25:08 +0000

I don't lose terminals when they're running. I lose them when I come back.

An hour ago I had five agents working on different things. Now I'm staring at a sidebar of names, trying to remember which one was refactoring the middleware and which one was writing tests. The agent that needs my approval is somewhere in there. So is the one I forgot about entirely.

PonyMux 0.9.0 is mostly about that moment. The moment you return. It adds ⌘K search to find the right Terminal by keyword, wake summaries that show what a sleeping Terminal was doing before you resume it, and cross-provider handoff to continue a conversation from Claude Code in Codex or vice versa.

What does search actually find?

Press ⌘K and the sidebar switches to a search view. Type a word — or several — and PonyMux filters your Terminals by name, prompt, recap, and the agent's last reply. Every word has to match somewhere across those fields.

The scoping is deliberate. Three pills at the top — All, Terminals, Archive — let you narrow where you're looking. Trashed Terminals don't appear. And only the latest session per Terminal is searched, not the full history.

That last part is a conscious tradeoff. Searching every historical session would return more results, but most of them would be stale. When I'm trying to find something, I almost always mean "the thing that's happening now," not "something an agent said three days ago." If I need the history, the Sessions panel is still there.

Results are ranked by where the match lands — title first, then prompt, then recap — and boosted by recency.

The result rows show matched text in context: title with highlights, a snippet from the matched field, the provider, the list path, and how long ago the session was active. Enough to recognize the right one without opening it first.

Press Escape and you're back where you were. No state changed.

What was that terminal doing again?

Before 0.9.0, waking a sleeping Terminal was a small leap of faith. You'd see the last captured screen — a frozen frame of wherever the agent left off — and either resume immediately or type to start fresh.

Now the empty area shows a short summary before you commit: the agent name, what it was working on, and when it was last active. If the transcript is still on disk, PonyMux can tell you what will resume before you press anything.

If the transcript is gone — deleted, compressed, or moved — the Terminal says so and offers Shell Only instead of pretending everything is fine.

The point isn't automation. It's not having to wake something up just to find out what it was.

A related change: agents that were running when you quit PonyMux now appear in the Agents sidebar after restart. Previously, quitting cleared the Agents list and you had to scroll through All Terminals to find them. Now they're where you left them.

Can I continue this in a different agent?

Sometimes the right move is to switch providers. You started a task in Claude Code, realized it needs a different model, and want to pick it up in Codex. Or the other way around.

Handoff does that. From the Sessions panel or the Inspector, select Handoff and PonyMux extracts the recent conversation — up to five turns, tool summaries, and a recap if one exists — into a Markdown file, then launches the target CLI with that file as context.

The source session is untouched. You can still Resume it in its original provider. Handoff creates a new session, not a migration.

It's intentionally lightweight. The handoff file is readable Markdown, not a binary blob or an API call. The target agent gets enough context to pick up the thread. It doesn't get the full transcript — that stays with the source provider — but it gets the shape of the conversation.

What else shipped

A few smaller things in 0.9.0 that don't need their own section:

Quieter updates. Sparkle no longer interrupts with a modal dialog. A sidebar button appears when a new version is ready.
Help menu. Documentation links, a feedback entry point, and a What's New item that links to the changelog.

The theme

These features don't share a category. Search is navigation, wake summary is lifecycle, handoff is session management. But they share a user moment: you were away, and now you need to find your place again.

That moment gets more frequent as agents get better. The better they are at working independently, the more time you spend away from them, and the harder it is to come back. The terminal that helps you return — not just the terminal that helps you start — is the one that scales with more agents.

For details on search, see the Search section in the docs. For session operations, see Sessions.

A markdown viewer, not a file browser

Little Pan — Sat, 12 Sep 2026 15:42:02 +0000

Agents write a lot of markdown. Plans, architecture decisions, handoff notes, CLAUDE.md. Most of the time I end up cat-ing these files or switching to VS Code just to glance at one. The file never needed editing. I just needed to read it.

So PonyMux added a markdown viewer to the Side Panel — read-only, scoped to .md files, rendered through the terminal itself. Not a file browser. Not a step toward becoming an editor. A place to glance at the documents that coordinate work between you and your agents, without leaving the terminal.

The distinction matters more than it sounds.

Why not a file browser?

The obvious feature request is a file tree. Several terminal products are heading that way — sidebar file explorers, inline previews, built-in editors. It's a natural direction. It's also a step toward becoming VS Code.

That's the tension. Every feature like that makes a terminal more capable and more complicated. At some point you're not improving the terminal anymore. You're building a second development environment inside it.

PonyMux has a principle called Stay small: a feature belongs here when it makes terminal sessions easier to find, understand, continue, or enjoy. Otherwise, it probably belongs somewhere else.

A file browser didn't pass that test. But there's a more interesting question underneath it: do you actually need to browse source code in your terminal mux?

Agents are increasingly the ones reading and writing code. They navigate files, they make changes, they run tests. What humans need to see more often are the documents that sit above the code — the plan the agent is following, the decision log it should respect, the README it just updated.

Markdown is the handshake format between you and your agent.

That's the file type worth supporting well. Not all files. This one.

What does the viewer actually do?

It's a read-only Markdown renderer that lives in the Side Panel, next to Sessions. Press ⌥⌘F or click the toolbar button. It renders .md files with styled headings, code blocks, tables, task lists, and inline images.

There are three ways to open a file:

Click a file:// link in terminal output — if it points to a .md file, PonyMux opens it in the viewer instead of Finder.
pony open <path> from a script or agent — pushes the file into the panel programmatically.
The file picker in the panel itself — standard open dialog, filtered to .md.

Editing stays in your editor. This is for reading and confirming. The context menu has "Open with Default App" and "Reveal in Finder" for when you need to go deeper.

Agents are doing more of the writing. What you need more of is a place to read.

Can agents open files for you?

This is the part I'm most interested in. The viewer isn't just something you open manually — agents can push files into it.

When an agent finishes writing a plan, it can run pony open plan.md and the file appears in your Side Panel. A small toast shows who sent it — "Opened by Claude Code" or "Opened by Codex" — so you know why the panel popped up.

The same thing happens with file:// links. If an agent prints a path to a markdown file in its output and you click it, the viewer catches it. No Finder window. No editor launch. Just the rendered file, right there beside the terminal.

This flips the usual direction. Instead of you going to find the file, the file comes to you. The agent produces a document, and it shows up where you're already looking.

It's a small workflow change. But after using it for a few days, going back to cat DECISIONS.md feels like a step backwards.

How does it stay light?

The viewer borrows a few ideas from a browser without trying to become one.

Back and forward navigation works within the panel. Click a relative .md link inside a rendered file and it navigates in place — no new window, no stack of tabs. The chevrons in the header track where you've been.

You can pin up to ten files for quick access. Pinned files and recent files show up in the empty state when nothing is open. Each terminal maintains its own browsing history, so switching terminals swaps the context.

The history is deliberately ephemeral. Quit PonyMux and it clears. The viewer doesn't track what you've read across sessions or build a project model out of your file visits. It's browsing state, not persistent data.

One detail I like: the viewer renders through the terminal's own surface. Same font, same theme, same copy behavior. If you change your terminal theme, the viewer changes with it. It doesn't look like a different app was embedded beside your terminal — because it wasn't. File watching keeps it current: edit the file in your editor, the viewer refreshes automatically.

Just enough, not everything

There's a version of this feature that supports every file type, has syntax highlighting for source code, and lets you edit inline. That version would be genuinely useful. It would also mean PonyMux is now competing with the editor you already have.

I'd rather keep the boundary. Agents are getting better at reading and writing code. The part where humans still need to look carefully is the coordination layer — the plans, the decisions, the context documents that tell the agent what to do and tell you what it did.

A read-only markdown viewer is a small, specific answer to that. It doesn't try to replace your editor. It doesn't try to show you everything. It shows you the one format that matters most for the way agents and humans work together right now.

For the full details — keyboard shortcuts, pinning, and how pony open works from scripts — see the Files section in the docs.

One icon, three signals

Little Pan — Sat, 12 Sep 2026 05:13:05 +0000

Everyone's been talking about the iPhone Duo. The hinge, the cover screen, the price. But the detail that stuck with me was much smaller than all of that.

In the corner of the cover screen, the three status bar icons that have lived side by side for almost twenty years—Wi-Fi, cellular, battery—got folded into one small circle. Outer ring for battery. Wi-Fi fan in the center. Four dots at the bottom for signal strength.

The first wave of reactions was mostly "that's clever," and it is. But then the designers started arguing about whether it was actually readable. That's where it got interesting.

Why it works

The reason the combined icon doesn't look like a mess is that the three signals use three different kinds of shape. Battery is a continuous arc. Wi-Fi is a symbol. Cellular is a row of dots. Arc, symbol, dots—they look fundamentally different from each other, so your eye can pick them apart even when they're sharing the same space.

Apple didn't just make three icons smaller and cram them together. They found three visual channels that don't interfere, and layered them. The unfold animation makes this explicit: the circle splits apart, each piece stretches back into its original shape, and you can see exactly what was packed together. As someone put it: "the way the animation explains the design."

The trick isn't making things smaller. It's finding the channels that don't collide.

What it costs

The criticism that followed is worth taking seriously. A battery silhouette with a fill level is self-explanatory—you see the charge. A notched arc is a gauge you have to learn. Same with cellular: "three out of four bars" reads instantly, "three out of four dots" less so.

Then there's the failure state. When all three signals are low, the arcs thin out, the dots get sparse, and the whole thing collapses into one vague shape. With separate icons you can see at a glance which one is in trouble. With the combined icon you have to look closer.

But here's the part most coverage skipped: the combined icon only appears on the 5.4-inch cover screen. Unfold the phone, and iOS 27 reverts to the classic three. Control Center shows them separately too. Apple isn't proposing a new universal language—they're acknowledging a specific constraint, and accepting the tradeoff there while keeping the old solution everywhere else.

That's actually the most interesting design decision in the whole thing.

The best design decision here wasn't the combined icon. It was choosing not to use it on the bigger screen.

A small related story

I've been thinking about all of this because I ran into a version of the same problem while building PonyMux. Much smaller scale, totally different product, but the question was the same.

PonyMux has a sidebar with a list of terminal sessions. Each row needs to tell you three things: an emoji the user picked to label the session (like 🚀 or ✓), the runtime status (running, waiting, error), and whether the session is hibernating.

The first version had all three, but in three different places. The emoji sat on the left. The status spinner sat on the trailing edge. And "zzz" for hibernation was inline in the subtitle, right after the process name.

The first consolidation: the emoji got a proper circular home on the left side, and the status indicator moved from the trailing edge into a corner badge on that same circle. The row went from three locations to two. But zzz was still sitting in the subtitle.

Then zzz moved into the same corner badge spot. This worked because a sleeping session has no active status—the badge is always free when zzz needs it. They take turns. Never collide.

Three things, one 24-pixel circle. Each step was just asking: does this really need its own spot? And each time the answer was no, the row got quieter without losing anything.

The reason this was easier than Apple's problem: the emoji is self-explanatory (the user chose it), and the corner badge dimensions are mutually exclusive—no "bad day" scenario where everything degrades at once. Different constraints, lower stakes. But the underlying question was the same.

One more thought

The iOS 27 icon is a good design. The criticism of it is also good criticism. That's not a contradiction—it's just how real tradeoffs work.

Combining signals into one shape isn't always better than keeping them apart. It depends on the space, the signals, and the ways they can fail. On the cover screen, Apple decided the density was worth it. On the unfolded display, they decided it wasn't.

Density doesn't come from compression. It comes from discovering that your signals were never competing for the same visual channel in the first place.

Arc reads as quantity. Symbol reads as identity. Dots read as count. Three different questions your eye answers in three different ways—that's why they can share a circle. That's the part worth remembering: not the specific solution, but knowing how to look for channels that were already complementary.

Originally published at ponymux.com