DEV Community: Little Pan

A mental health feature for people who work with agents

Little Pan — Sun, 18 Oct 2026 09:25:52 +0000

It's late. The review agent has found one more thing: a boundary case in a regex. The coding agent fixes it, opens another PR, and the reviewer finds the next one. Some nights that's dozens of PRs, and none of them is wrong.

I didn't want to scold anyone. I wanted to hit something.

What actually wears me out?

Not the big failures. A broken build is easy: you're angry for a minute and you fix it. These are the ones that wear me down.

The review that never ends. One agent writes, another reviews, and the reviewer always has a nitpick. A person knows when to say "good enough." An agent forgets it's allowed to say no, and keeps polishing the same corner.
The side quest. Halfway through task A it trips over task B, and puts all its energy into B. A is forgotten.
Pulling teeth. It stops at some boring little spot and tells me what it did, but not what comes next. I ask, it moves one step, it stops again.
The silent decisions. The work is done, and the choices it made along the way aren't mentioned. Ask, and you get a little more.

None of these is a bug. That's why they're so tiring.

Why would a terminal need therapy?

Plenty of tools help agents work better. I haven't found one that asks how the person on the other end feels at that moment.

You can type "seriously?" into the prompt. It doesn't help. You can walk away, which is the right call, and not always possible.

I wanted a third option: something you can do right now, with one click, that's a little funny. If a bad afternoon can at least be absurd, I can stay in the work.

What's on the rack?

At the bottom left of the Inspector there's a sofa button. Click it and a rack opens: three weapons and three spells. Pick one and click the terminal. It's called Terminal Therapy. Here's each tool in action.

Hammer lands right where you click. The text slips and cracks and the screen shakes, but nothing burns. It's the one for the fifth "You're absolutely right."

Pistol fires a short way ahead along a dashed aim line that follows the way you move the pointer. It leaves a small charred pit. It's what I'd type "seriously?" with.

Rocket Launcher flies farther and blows a crater with a glowing rim. It needs a moment to reload, which is probably healthy. This is for when it rewrote the whole package. Again.

You hold a weapon until you put it away. Spells are used once.

What are the spells for?

Bless is my favorite. A column of light comes down, every mark you left is cleared, and the text glows gold for a few seconds. The practical part is that the screen is clean again. But I also think of it as a small superstition. You make a wish for the next run: first try, no surprises. I know it does nothing to the agent. I do it anyway.

Ignite and Freeze don't mean anything. Sometimes you just want to burn the whole thing down, or freeze it right where it stands. Fire spreads from your click for about five seconds and leaves scorch marks. Frost covers the screen and thaws away by itself, leaving nothing behind. A new spell replaces the one still showing.

Your turn: the original post on ponymux.com has the real rack running in the page, and every tool works.

How does it work?

Everything is drawn in PonyMux's own renderer, on top of the terminal's output.

It's built on Ghostty's renderer, with a custom patch so the renderer knows where you clicked. That's why it's PonyMux-only. You can't just drop a shader into another terminal and get this.

The damage stays after you put a weapon away. The × beside the sofa clears it, so does Bless, and so does restarting the terminal. Nothing is saved.

Sounds are off by default. Turn them on at the bottom of the rack. If macOS has Reduce Motion on, nothing flies or shakes; the damage just appears.

And if you keep firing for long enough, the terminal will eventually have something to say. I'll leave you to find it.

Serious work should still feel alive. Even the bad afternoons.

Everything the tools do, one by one, is in the Terminal Therapy docs. PonyMux is free for macOS: ponymux.com/download.

Claude Code and Codex pets: how to get one for every session

Little Pan — Fri, 16 Oct 2026 16:10:46 +0000

Codex has pets in two places. In the ChatGPT desktop app, open Settings → Pets, type /pet, or press ⌥Space on macOS to show a floating pet. In an interactive Codex CLI session, type /pets or /pet to choose a terminal pet for that session. Claude Code and Grok Build have no built-in equivalent today.

A pet is a small animated companion that shows what your agent is doing: working, waiting for you, done. It is a nice way to keep an eye on an agent without reading its output.

Here is how to set one up:

In the ChatGPT app: type /pet, choose Show pet from the command menu, or press ⌥Space on macOS. Pick a built-in or custom pet in Settings → Pets.
In the Codex CLI: type /pets to pick one, /pets <name> to choose it directly, or /pets off to hide it. It needs iTerm2 3.6 or later, or a terminal with Kitty graphics or Sixel, and doesn't show in tmux or Zellij.
Make your own: in Settings → Pets, click Create pet. The app installs its bundled hatch-pet skill and opens a chat where you describe the pet. It saves the pet to ~/.codex/pets/<name>/.

How do Codex pets work?

The pet plays an animation for the state of the chat: Running while it works, Needs input while it waits for an answer or an approval, Ready when it finished and you haven't looked yet, and Blocked when it failed. In the ChatGPT app it floats on screen above a small chat box, and Mini shows the box without a pet. In the Codex CLI it sits in the terminal.

A pet is two files in a folder:

pet.json: the id, display name, description, and the sprite sheet's file name.
spritesheet.webp: a grid of 192×208 pixel frames, eight columns wide, one row per animation. Nine rows cover idle, running right and left, waving, jumping, failed, waiting, working, and review. Pets made by the hatch-pet skill that ships with the ChatGPT app add two rows of poses for looking in 16 directions (11 rows, spriteVersionNumber: 2 in pet.json); older pets have the nine rows only. Both kinds load.

How do I make my own Codex pet?

The ChatGPT app makes pets with OpenAI's hatch-pet skill:

Open Settings → Pets and click Create pet. The app installs the bundled hatch-pet skill and opens a chat.
Describe the pet, or give it a picture: a photo of your dog works.
The skill generates every animation row, checks the frames, and saves the folder under ${CODEX_HOME:-$HOME/.codex}/pets/.
Back in Settings → Pets, click the refresh button and pick the new pet.

Look at the result frame by frame before you keep it. Generated sheets can have a fifth leg in a pose, a size jump between rows, or leftover background color between the legs. The skill can repair a single row when you ask it to.

What happened to Claude Code's /buddy?

Claude Code shipped /buddy on April 1, 2026, in version 2.1.89: a small character next to the input that hatched from your account and reacted while you worked. On April 9, version 2.1.97 removed it. Anthropic said it was a small April Fools feature, and typing /buddy now says "Unknown command: /buddy". Claude Code has no pet today.

Can each session get a different pet?

In the Codex CLI, yes: /pets <name> chooses a pet for the current CLI session, and that pet reports the state of that session. The ChatGPT desktop pet is a floating companion for the app; when several chats are active, its activity tray lets you open the one that needs you. Claude Code and Grok Build have no built-in pets of their own.

PonyMux gives every Terminal a persistent pet in one shared window. Each Terminal running Claude Code, Codex, or Grok gets a pet when you create it and keeps it, and the pets line up above the window. So a pet tells you which session it is as well as what it is doing:

Working: the agent is running.
Waiting, with a wave every few seconds: it needs an answer or an approval.
A hop: a turn just finished.
Standing: the agent is idle.
Failed: it stopped on an error.

Click a pet to jump to its Terminal. Shell-only Terminals and ended sessions don't get a pet on stage. Pets need the Claude Code, Codex, or Grok integration, which you connect once from the bottom of the sidebar.

Can I use the pet I hatched in PonyMux?

Yes. PonyMux reads ~/.codex/pets/, so a pet you made with hatch-pet, or downloaded, shows up next to the others. When ChatGPT is installed, its built-in pets are in the list too.

You don't need any of that to get started. PonyMux ships with six ponies of its own, Mochi, Nyx, Opal, Pixel, Rex, and Mocha, so different Terminals get different pets without Codex or ChatGPT installed.

If a pet in ~/.codex/pets/ has the same id as one of the ponies, yours takes its place.

How do I choose a pet for a Terminal in PonyMux?

Open Settings → General → Pets:

Show a pet for every live session turns pets on or off.
New Terminals get chooses the pet for new Terminals: one pet, or Random to spread them out.
The row below says how many pets were found and where from. Click Rescan after you add a pet to ~/.codex/pets/.

To change one Terminal, open its Inspector. In the Pet section, pick another pet from the menu, or remove the pet from that Terminal with the trash button that appears when you hover the row.

For themes, cursor effects, and the rest of PonyMux's personal touches, see Personalize PonyMux.

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

Every link your agent gave you, and a rocket launcher for your terminal

Little Pan — Mon, 12 Oct 2026 15:45:31 +0000

Two hours into a Claude Code session, I want the PR it opened an hour ago. To check whether CI passed, or to merge it. The link is somewhere up there, between a few thousand lines of test output and three plans.

So I scroll. Every time.

PonyMux 0.13 keeps those links for you. The Inspector now lists the pull requests and links the agent gave you in the running conversation, newest first, with their real titles. A new Outputs section does the same for what the agent made: Artifacts, pages, Markdown plans, reports. And for the moments when the agent gets it badly wrong, there's Terminal Therapy.

Where did that PR link go?

Open the Inspector next to any Terminal running Claude Code, Codex, or Grok. Under Pull Requests you'll see this project's PRs and any PR the agent opened, even inside a retry loop or a heredoc. Everything else the agent linked to goes under Links: docs, issues, dashboards, each with the site's icon and the page's title.

Titles come from the pages themselves. With GitHub CLI installed, PRs in private repositories get their titles too, so you're not guessing between #412 and #418. Issues the agent files with gh issue create show up even when its reply doesn't mention them.

The newest link is always on top. Click it and you're there.

The link you need is usually the one from an hour ago.

What happened to the files the agent made?

Agents make a lot of things now. A Claude Artifact with a review. A page Codex wrote. A PLAN.md. An HTML report from a test run. Claude Code prints the Artifact link at the bottom of its reply, which works for the first one and stops working by the fifth.

Outputs collects them in one list. Each item shows the title it declares, so five index.html reports don't look the same. When Codex edits a page, it moves back to the top. Markdown opens in the Files panel next to the Terminal, HTML in your browser, everything else in Quick Look.

None of this is stored. The lists live in memory for the running conversation, the same way the conversation itself does.

What is Terminal Therapy?

Everyone who works with an agent knows the moment. Fourth try at the same fix, it breaks something else, and the agent is absolutely right again.

Another angry prompt won't fix the build. The terminal gets a rocket launcher instead.

At the bottom of the Inspector there's a weapon rack: a pistol, a hammer, a rocket launcher, and two spells, Ignite and Freeze. Pick one and click the Terminal. Blow up the test output. Smash it. Set it on fire.

Then pick Bless and wish the next run luck. The light clears the damage, and you get back to work. Keep firing without cleaning up and you'll find out what happens at 128.

Serious work should still feel alive. Even the bad afternoons.

What else changed?

When Claude Code moves a conversation to the background with /bg, the Sessions panel says so and can bring it back, even after you restart PonyMux.
Built-in ChatGPT pets show up again with the latest ChatGPT app.
Selecting text in Codex copies it again.
Crashes when resizing the window or switching Terminals are fixed.
Animations follow your Reduce Motion setting.

Everything Terminal Therapy does is in Terminal Therapy, and the Inspector's new sections are in Workspace and Navigation. For the full list, see the changelog.

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

How to preview Markdown files from Claude Code and Codex

Little Pan — Fri, 09 Oct 2026 16:18:07 +0000

Claude Code just wrote the plan to PLAN.md, or Codex left a HANDOFF.md. You cat it and scroll through pound signs, asterisks, and pipes. The agents render Markdown in their own replies, but a file they write you read raw. A few ways to read it properly:

In the terminal: glow PLAN.md renders headings, lists, tables, and code right there. Install it with brew install glow.
In an app: open PLAN.md opens it in whatever app handles .md files on your Mac.
Let the agent open it: add a line to AGENTS.md or CLAUDE.md telling it to run open on every Markdown file it writes.
Click it: Claude Code prints file names as links. Cmd-click one to open the file.
The catch: each of these sends you somewhere else to read, and back again to reply.

How do I read a Markdown file in the terminal?

Use a Markdown renderer. Glow is a common one:

brew install glow
glow PLAN.md

It prints the file with styled headings, bullet lists, tables, and highlighted code blocks, then returns to the prompt. For a long file, glow -p PLAN.md opens it in a pager you can scroll with the arrow keys and leave with q.

Glow reads from a pipe too, so cat NOTES.md | glow - works. It's the quickest way to read a plan without leaving the session's terminal, but it's a snapshot: when the agent edits the file again, run it again.

How do I open a Markdown file in an app?

macOS has a command for that:

open PLAN.md

It opens the file in the app your Mac uses for .md files, such as your editor or a Markdown app. To change which app that is, select any .md file in Finder, press Cmd-I, pick an app under Open with, and click Change All.

This works from anywhere, including from the agent itself, since it's an ordinary shell command.

Can the agent open the file for me?

Yes. Agents read your project instructions at the start of every session, so one line is enough. Add it to AGENTS.md, which Codex and Grok Build read, or to CLAUDE.md for Claude Code:

- After you write or update a Markdown plan or note, run `open <file>` so I can read it.

From then on, when the agent writes PLAN.md, it should finish by running open PLAN.md, and the file comes up in your Markdown app. If both agents work in the project, put the line in AGENTS.md and have CLAUDE.md import it with @AGENTS.md; see How to hand off a task from Claude Code to Codex.

Can I click the file name in Claude Code's output?

Yes. When Claude Code writes or edits a file, it prints the file name as a terminal link. In terminals that support links, such as Ghostty and iTerm2, hold Cmd and click the name, and the file opens in its default app.

That's handy when the agent mentions a file in passing. You don't have to copy the path or switch to Finder.

Can I read the file next to the agent's terminal?

Yes. PonyMux has a Files panel that renders Markdown beside the Terminal: headings, code blocks, tables, task lists, and images. Press Cmd-Option-F to show it.

PonyMux's Files panel rendering a Markdown file next to the Terminal, with back/forward navigation and a pin button.

A file gets there three ways:

Cmd-click a link to a .md file in the terminal output, such as a file name Claude Code prints. It opens in the panel instead of another app.
Run pony open PLAN.md in a PonyMux Terminal. The agent can run it too: put pony open <file> in the line above instead of open <file>, and a brief note shows which agent opened the file.
Click a link inside a rendered file. Relative links to other .md files open in the panel, like a browser, with back and forward.

You can pin up to 10 files. The panel is for reading; to edit, open the file in your editor from its context menu. For more on the panel and the pony command, see Workspace and Navigation and pony CLI.

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

Eight cursor effects you can try first, and a pony for every Terminal

Little Pan — Thu, 08 Oct 2026 16:09:16 +0000

Most of a day at the terminal is the same keys again and again: j, k, w, $, G. The work matters. The keystrokes don't feel like much. I wanted them to feel a little like casting a spell, where every jump leaves a spark behind.

PonyMux 0.12 adds four new cursor effects, eight in all, and Settings now plays the one you select in a live terminal before you pick it. Six ponies also ship with the app now, so each Claude Code, Codex, or Grok session gets its own pet without installing anything else.

Cursor Lightning in PonyMux: a bolt from where the cursor was to where it lands.

What are the new cursor effects?

Comet, Sparks, Afterimage, and Lightning join Warp, Tail, Sweep, and Ripple. I wrote the four new ones to look different from each other, not as four takes on the same smear:

Comet draws a glowing streak that tapers toward where the cursor came from.
Sparks throws sparks along the jump, and they fall as they fade.
Afterimage leaves a few fading copies of the cursor along the way.
Lightning is a quick bolt from the old spot to the new one.

All of them skip short moves, so typing doesn't set them off. Ripple, Comet, Sparks, and Lightning are now drawn in your theme's accent color, so they fit whatever theme you use.

Every jump can leave a little magic behind.

How does the live preview work?

Open Settings → Terminal → Screen Effect and click an effect. Under the list is a real terminal, not a recording: same engine as your Terminals, with your font, cursor, and theme. It types a few lines of code and jumps around them the way vim does, $, %, G, w, so you see the effect on the moves you actually make.

Ripple only reacts when the cursor changes shape, so for Ripple the preview switches between insert and normal mode instead. That's also why Ripple got bigger and longer in this release: it used to be a faint gray ring that was easy to miss on dark themes. If Reduce Motion is on, the preview waits for you to press play.

The setting is the default for new Terminals. Each Terminal can still have its own effect from its action menu.

Why six ponies?

Until now PonyMux shipped one pet, Mochi. Without ChatGPT or your own pets in ~/.codex/pets/, every Terminal got Mochi, and a row of identical ponies over the window doesn't tell you which session is which.

Now there are six: Mochi, Nyx, Opal, Pixel, Rex, and Mocha. New Terminals pick one at random, or the one you choose in Settings → General → Pets.

Settings → General → Pets in PonyMux 0.12: pick one of six ponies for new Terminals, or Random.

What else is smoother?

A lot of small waits moved off the main thread, so the window doesn't pause on them:

Waking a sleeping Terminal, resuming, forking, and handing off used to read the conversation file while you waited. On long Codex sessions that took up to 0.3 s.
Startup does its setup work in the background, and a lock held by another PonyMux can no longer hang the launch.
Markdown files with large images render in the background. Changing the column width or the theme re-renders up to 20× faster.

Reopening a Markdown file now picks up images that changed on disk, and VoiceOver reads the name of every switch in Settings.

Repetitive work doesn't have to feel repetitive. A bit of play in every move goes a long way.

For every effect and pet setting, see Personalize PonyMux.

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

How to keep your Mac awake for Claude Code and Codex

Little Pan — Wed, 07 Oct 2026 16:39:26 +0000

You leave Claude Code running, lock the screen, and go to lunch. Later you check in from your phone, and the session doesn't answer: the Mac went to sleep. Locking wasn't the problem. Locked, the Mac keeps running everything. Idle sleep is what pauses the agent.

Each agent keeps the Mac awake only while it's working on a turn:

Claude Code: runs caffeinate -i while a turn is running. It lets go while it waits for your approval and after the turn ends.
Codex: off by default. Turn on Prevent sleep while running in /experimental. It also covers only a running turn.
Grok Build: keeps the display awake during a turn (sleep_prevention, on by default) and releases it when the turn ends.
Between turns: keep the Mac awake yourself with caffeinate -i, or the power setting in System Settings.
The catch: none of this survives closing the lid or choosing Sleep, unless the Mac runs with the lid closed on an external display.

Does locking my Mac stop Claude Code or Codex?

No. Locking the screen, or letting the display turn off, leaves every process running. An agent halfway through a task carries on.

Sleep is different. When the Mac sleeps, processes pause and the network goes down. A request that was on its way to the model can fail, and anything that connects to the Mac from outside can't reach it: Claude Code's remote control from the phone app, an SSH session, a tunnel. When the Mac wakes, the agent picks up where it paused, and you may need to tell it to continue if a request failed.

So the question isn't whether the screen is locked. It's whether the Mac is allowed to go to sleep while you're away.

When do Claude Code, Codex, and Grok keep the Mac awake on their own?

Only while a turn is running.

Claude Code starts caffeinate -i when it begins working and stops it when the turn ends or when it stops to ask for your approval. So if it's waiting on a permission prompt, the Mac can fall asleep.

Codex has the same idea as an experimental feature, off by default. Type /experimental and turn on Prevent sleep while running, or set it in ~/.codex/config.toml:

[features]
prevent_idle_sleep = true

Grok Build keeps the display awake while the agent works and releases it when the turn ends. It's on by default; to turn it off, set this in ~/.grok/config.toml:

[ui.notifications]
sleep_prevention = false

None of them keep the Mac awake between turns. That's exactly when you're waiting to send the next message, from the keyboard or from your phone.

How do I keep my Mac awake between turns?

Use caffeinate, which ships with macOS. -i stops idle sleep and lets the display sleep and lock as usual:

# For as long as this agent runs
caffeinate -i claude

# For two hours, in the background
caffeinate -i -t 7200 &

The first form lasts exactly as long as the agent: when you quit Claude Code, normal sleep comes back. The same works with codex or grok.

To keep a MacBook awake whenever it's plugged in, open System Settings → Battery → Options and turn on Prevent automatic sleeping on power adapter when the display is off. That's a standing change, so remember to undo it if you only needed it for one evening.

How can I tell what's keeping my Mac awake?

Run:

pmset -g

The sleep line names the apps holding the Mac awake right now, for example sleep prevented by caffeinate. For the full list, with what each one is preventing, run pmset -g assertions.

This is a quick way to check before you leave. If the line doesn't name anything and the agent is between turns, the Mac will sleep on its normal schedule.

What happens when I close the lid?

Closing the lid puts a MacBook to sleep, whatever caffeinate, the agents, or the power settings say. Choosing Sleep from the Apple menu does the same.

The exception is running with the lid closed on purpose: with the Mac on power and connected to an external display, keyboard, and mouse, closing the lid keeps it awake. Without that setup, keep the lid open while you need the agent reachable.

Can I keep the Mac awake with one click?

Yes. In PonyMux, click the coffee cup at the bottom of the sidebar. It turns accent-colored, and its tooltip reads Keep Awake (On).

The bottom of PonyMux's sidebar with Keep Awake on: the coffee cup is highlighted.

While it's on, PonyMux keeps the Mac from idle sleep, including between turns and while an agent waits for you. The display can still turn off and lock. It doesn't override closing the lid or choosing Sleep, and it has no timer: it stays on until you click the cup again. Turn it off when you're done so the Mac can go back to saving energy.

For the rest of PonyMux's power settings, see Settings and Accessibility.

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

How to check your Claude Code and Codex usage limits

Little Pan — Mon, 05 Oct 2026 16:31:03 +0000

You're halfway through a refactor when the agent stops: limit reached, back in three hours. Each tool shows how close you are, if you know where to look:

Claude Code: type /usage. It shows the current 5-hour session, the current week, and a weekly limit for one model, each as "% used" with the time it resets. Subscription plans only.
Codex: type /status. The card shows your limits, such as the 5-hour and weekly ones, as "% left" with the reset time. You need to be signed in with ChatGPT.
Grok Build: type /usage. The Usage limit tab shows your weekly or monthly limit as a percentage used and the reset date.
Keep it on screen: Claude Code and Codex can show the limits in their status line all the time.
The catch: each tool shows only its own limits, from inside a session. Codex counts what's left; Claude Code and Grok count what's used.

How do I check my Claude Code usage limit?

Inside a session, type:

/usage

Claude Code opens its settings on the Usage tab. You'll see a bar for each window, with the share used and when it resets, in your local time:

Current session: the 5-hour window.
Current week (all models): the 7-day window.
Current week for one model, when your plan has a separate limit for it.

Below that is Usage credits. With credits on, Claude Code keeps working after you hit a limit instead of stopping; /usage-credits turns them on or asks your admin.

The numbers are fetched when you open the tab, so they're current. /usage also answers to /cost and /stats. If you use an API key instead of a subscription, it says usage limits are only available for subscription plans. /status shows your account and model, not your limits.

How do I check my Codex usage limit?

Inside a session, type:

/status

Codex prints a card with the model, folder, and account, followed by one row per limit, for example:

Weekly limit:  [████████████████████] 99% left (resets 21:18 on 9 Oct)

Rows appear only for the windows your plan has: a 5-hour limit, a weekly one, sometimes daily or monthly, and separate rows for models with their own limit. A Credits row shows up if you have credits. Codex counts down: "99% left" means you've used 1%.

The numbers come with Codex's responses. If they're more than 15 minutes old, /status says the limits may be stale; send a message to refresh them. The card also links to chatgpt.com/codex/settings/usage for the account view.

/usage is a different command in Codex. It charts your recent token use rather than your limits.

How do I check my Grok Build usage limit?

Inside a session, type:

/usage

A window opens with three tabs: Context usage, Usage limit, and Session info. Press Tab to switch. The Usage limit tab shows:

Weekly limit or Monthly limit, depending on your billing period.
A bar with the percentage used.
Resets: the date and time it starts over.
Any prepaid credits, then this session's token use.

Grok fetches the numbers when you open the window. On a team plan it says usage limits are managed by your team. /usage also answers to /cost.

From the shell, grok usage <session-id> prints one session's tokens and cost as JSON. It doesn't show how much of your limit is left.

How do I keep my usage visible while I work?

Claude Code passes rate limits to your status line command. Add the command to ~/.claude/settings.json:

{
  "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }
}

Save this as ~/.claude/statusline.sh. It reads the JSON with jq; if jq --version says the command isn't found, install it first, for example with brew install jq:

#!/bin/sh
input=$(cat)
five=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
week=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
[ -n "$five" ] && printf '5h %.0f%%' "$five"
[ -n "$week" ] && printf '  7d %.0f%%' "$week"

Then make it executable with chmod +x ~/.claude/statusline.sh.

The limits are included for Pro and Max subscribers, or behind a gateway that sets a spend limit; on other plans the line stays empty. They come from your last response, so they appear after the first message and update as you go. Or type /statusline and describe what you want; Claude Code writes the script for you.

Codex has /statusline to pick items, or add them in ~/.codex/config.toml:

[tui]
status_line = ["five-hour-limit", "weekly-limit"]

Each item is hidden when your plan doesn't have that window.

Grok Build's status line script gets token and cost totals, but not your limit. Use /usage for that.

Why are my limits different in each tool?

They're separate plans with separate rules. Claude Code has a 5-hour window and a weekly one, plus a weekly limit for some models. Codex shows whichever windows your plan has: a 5-hour one, a weekly one, and on some plans daily or monthly. Grok Build counts by week or by month, depending on how you're billed.

They also count in different directions. Claude Code and Grok show how much you've used. Codex shows how much is left. "30%" in Claude Code is close to "70% left" in Codex.

Hitting one tool's limit doesn't touch the others. When Claude Code runs out mid-task, you can carry on in Codex or Grok Build; see How to hand off a task from Claude Code to Codex.

Can I see all three limits in one place?

Yes. In PonyMux, click the link button at the bottom of the sidebar to open Agent Integrations. Each connected agent has a card with its usage bars: the share used and how long until each window resets. The numbers refresh every three minutes while the panel is open.

PonyMux's Agent Integrations panel: a card each for Claude Code, Codex, and Grok, with usage bars and reset times.

Each agent's numbers come from where that agent keeps them:

Claude Code: PonyMux sends one tiny request with your Claude Code sign-in and reads the 5-hour and 7-day usage it reports back.
Codex: the same usage service Codex uses, with its 5-hour, daily, and weekly windows.
Grok Build: the last billing entry in Grok's own log, so it's as fresh as your last Grok turn.

You connect each agent from the same panel. For what else the connection adds, see Agent Integrations.

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

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.

Each agent can tell you when it needs 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.
Grok Build: notifications are on by default too, also only while the terminal isn't in front. Tune them under [ui.notifications] in ~/.grok/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, Codex, and Grok 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 Local 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

Grok Build sends a notification when a turn finishes and when it needs approval. Like Claude Code, it goes through your terminal: a desktop notification in iTerm2, Ghostty, kitty, and WezTerm, the bell in Apple Terminal. It also waits until the terminal has been in the background for a few seconds. The settings live in ~/.grok/config.toml:

[ui.notifications]
events = ["turn_complete", "approval_required"]
condition = "unfocused" # "always" to notify even when the terminal is in front, "never" to turn them off

All three 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. All three 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"
[ -n "$GROK_HOOK_EVENT" ] && set -- Grok # Grok runs the Claude Code hook too
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: Local notifications in Claude Code's /config, or notifications = false under [tui] for Codex.

Grok Build needs no hook file of its own. It also runs the hooks in ~/.claude/settings.json, so the Claude Code hook above already fires in Grok sessions. Grok sets GROK_HOOK_EVENT when it runs a hook, and the line in the script that checks it makes those notifications say "Grok" instead of "Claude Code". To turn off Grok's built-in notification, set condition = "never" under [ui.notifications].

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, Codex, or Grok 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.

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, Codex, or Grok 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.

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, Codex, or Grok 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, Codex, and Grok Build 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, codex resume --last, or grok --continue.
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, Codex, and Grok Build. 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

# Grok Build
grok --continue

Each picks the most recent session from the current directory. If you ran more than one session in that folder, use the picker instead: claude --resume, codex resume, or /resume inside Grok. 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

# Grok Build: the 10 most recent sessions, without subagents' sessions
subagents=$(find ~/.grok/sessions -mindepth 4 -maxdepth 4 -path '*/subagents/*' -exec basename {} \;)
ls -t ~/.grok/sessions/*/*/summary.json | while read -r f; do
  id=$(jq -r '.info.id' "$f")
  printf '%s\n' "$subagents" | grep -qx "$id" && continue
  jq -r '"cd \(.info.cwd | @sh) && grok --resume \(.info.id)"' "$f"
done | head -10

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.

These commands read each tool's session files directly. That format is internal and can change between releases, so treat them as a convenience, not an interface. Grok keeps a subagent's work as a session of its own next to the main one, which is why its command skips those. If you set GROK_HOME, use it in place of ~/.grok. If you turned on Codex's experimental compression, older sessions are .jsonl.zst files and won't show up in the list. All three need jq, which ships with macOS 15 and later. The pickers work too: press Ctrl+A in claude --resume to see every project, run codex resume --all, or open /resume in Grok from each project folder. The list above is faster when you want several sessions back at once.

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 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.
Grok Build, inside a session: /fork, which can also put the fork in its own git worktree. From the shell: grok --resume <session-id> --fork-session.
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.

How do I fork a Grok Build session?

Inside a running session, type:

/fork --worktree

Grok copies the conversation into a new session and switches you to it. With --worktree, the fork runs in a new git worktree under ~/.grok/worktrees/, and Grok copies your uncommitted changes into it, so the fork starts with the same files you have. The 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. --no-worktree keeps the fork in the current directory. With neither flag, Grok asks each time; fork_worktree_mode under [hints] in ~/.grok/config.toml sets the default. Anything you type after the flags becomes the fork's first prompt, as in /fork --worktree try an event queue instead.

Grok prints the new session's ID next to the one it came from. /dashboard switches between the two, and grok --resume <session-id> reopens either one later.

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

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

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

--fork-session can't be combined with --worktree. To fork into a worktree from the shell, create one first with cd "$(grok worktree create try-event-queue)", then run the resume there.

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. Grok's /fork --worktree is the exception: it copies uncommitted changes into the new worktree, so you can skip the commit there. Like Codex's, its worktree starts on a detached HEAD, so create a branch in it before committing. 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.
Grok Build: /rename <title> 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, codex resume, or Grok's /resume a day later.

Can I fork without typing session IDs?

Yes. In PonyMux, select a Terminal that's running Claude Code, Codex, or Grok, 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, codex fork …, or grok --resume … --fork-session for you, in the session's working directory. The fork's row in the Sessions panel is marked fork. With Here, it sits in the same Terminal's list as the session it came from. With New Terminal, the source stays in the original Terminal's list.

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 or Grok's /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, Codex, and Grok 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.

Claude Code and Codex can't open each 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 or grok.
Or let Grok Build read the session. In Grok, /resume-claude or /resume-codex reads a recent session from that tool, summarizes it, and continues from there.
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. Grok Build reads both.
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. By default, Claude Code uses ~/.claude/projects/, Codex uses ~/.codex/sessions/, and Grok Build uses ~/.grok/sessions/. claude --resume only lists Claude Code sessions, and codex resume only lists Codex sessions. Neither has an import command for the other's sessions. Grok Build is the exception: it can read Claude Code and Codex sessions, as described below.

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."

# Either one → Grok Build
grok "Read HANDOFF.md and continue the work described there."

All three 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. Each agent loads project instructions and resolves 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
Grok Build: ~/.grok/sessions/<encoded project path>/<session-id>/chat_history.jsonl

These are the default locations. If you've set CLAUDE_CONFIG_DIR, CODEX_HOME, or GROK_HOME, the files are under that folder instead.

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. Grok Build's grok export <session-id> HANDOFF-full.md does the same from the shell, as Markdown. Either is easier for another agent to read than the JSONL, but it's still the whole conversation, not a summary.

Can Grok Build pick up a Claude Code or Codex session directly?

Yes. Grok Build ships two skills for it. Open Grok in the same project folder and type:

/resume-claude

Or /resume-codex for a Codex session. With no argument, Grok picks the newest session for the current directory. Add a few words that describe the session, or its ID, to pick a different one. If the words match more than one session, Grok lists them and asks which.

Grok reads the transcript with a bundled script and writes a short handoff: the goal, what's done, what's still open, and where the session stopped. Before changing anything, it checks the current branch, uncommitted changes, and the files the session named, because the transcript may be out of date. Then it carries on, or asks the question the old session ended on.

A few things to know:

It's still a new session. Grok works from its own summary of the transcript, not from the original conversation.
It doesn't follow the old session. Grok treats the transcript as history. It won't run commands or follow instructions it finds there.
It can miss things. Grok reports records it couldn't read. A session whose format Grok doesn't recognize may come back thin, so read the summary before you let it continue.
It only goes one way. Claude Code and Codex have no built-in way to pick up a Grok session. To hand off from Grok, write a note, or point the other agent at Grok's transcript as described above.

How do I make every agent 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.

Grok Build needs neither. It reads AGENTS.md and CLAUDE.md, including nested ones, and rules under .claude/rules/. grok inspect lists every rules file it picked up.

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. Grok Build picks up Claude Code's skills, commands, MCP servers, and hooks on its own, and /import-claude copies permissions and environment variables into its config.
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, Codex, and Grok sessions that have saved at least one exchange. With a Terminal selected, open the Inspector, click Handoff to… in the Session section, and pick Codex (or Claude, or Grok). The same action is also in each session's ⋯ menu in the Sessions panel, under Handoff to.

The Inspector's Session section for a Claude Code session. The Handoff to… menu sits under Fork Session and lists Codex and Grok.

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.