DEV Community: Eren Çolak

How to get notified when Claude Code finishes or needs permission

Eren Çolak — Wed, 11 Nov 2026 10:49:45 +0000

If you run Claude Code in the VS Code or Cursor terminal, you get no alert when it finishes or stops for a permission prompt. Claude Code sends a desktop notification on its own only in a few terminals (Ghostty, Kitty, iTerm2). In the VS Code terminal, Warp and most others it sends nothing by default.

So you keep checking the tab, or you switch away and come back twenty minutes later to a session that has been waiting for a "yes" the whole time.

Here are three fixes, from a one-line setting to a hook that tells you which session it is. Checked against Claude Code 2.1.x on macOS, Linux and Windows.

1. One line: the terminal bell

Tell Claude Code to ring the terminal bell whatever terminal you use. In ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

In VS Code and Cursor, the bell is silent until you turn on its sound. Open Settings, search for Terminal Bell (under Accessibility Signals) and set the sound to on.

Good: zero scripts. Not so good: it's a short beep, you have to be in earshot, and it doesn't say which session rang.

2. A hook that pops a desktop notification

Hooks are commands Claude Code runs at points in its lifecycle. Two events matter here:

Event	When it fires
`Stop`	Right when Claude finishes its turn
`Notification` with `permission_prompt`	Claude needs you to approve something and the prompt has waited about six seconds
`Notification` with `idle_prompt`	About 60 seconds after a finished turn, if you haven't typed since

Stop is the one you want for "it's done". idle_prompt repeats the same news a minute later, so if you hook both you get two alerts for one finished turn.

Add this to ~/.claude/settings.json (macOS shown; other systems below):

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Your turn\" with title \"Claude Code\"'",
        "async": true
      }]
    }],
    "Notification": [{
      "matcher": "permission_prompt",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Needs permission\" with title \"Claude Code\"'",
        "async": true
      }]
    }]
  }
}

"async": true matters more than it looks. Hooks are synchronous by default: Claude waits for each one. A notification command that takes a second or three (PowerShell's startup alone is about that on Windows) slows every turn down. With async, it runs in the background.

The command for other systems:

Linux (needs a notification daemon, so not over plain SSH):

notify-send 'Claude Code' 'Your turn'

Windows (plays the system chime; a message box would block until you click it):

powershell.exe -NoProfile -Command "(New-Object Media.SoundPlayer 'C:/Windows/Media/chimes.wav').PlaySync()"

The forward slashes are on purpose: they work in Windows paths and need no escaping inside JSON. Inside settings.json, escape the double quotes as \".

Sound only, macOS:

afplay /System/Library/Sounds/Glass.aiff

If nothing shows on macOS, osascript notifications go through Script Editor. Run osascript -e 'display notification "test"' once in Terminal so Script Editor appears in System Settings > Notifications, then allow it.

3. Say which session it is

With one session, "Your turn" is enough. With three or four, you need to know which one. Every hook gets a JSON object on stdin, and it includes cwd, the folder the session runs in. Put that in the notification (macOS, needs jq):

{
  "type": "command",
  "command": "osascript -e \"display notification \\\"$(jq -r '.cwd' | xargs basename)\\\" with title \\\"Claude Code: your turn\\\"\"",
  "async": true
}

Now the notification says api or web instead of just "Claude Code". On Linux, the same idea is notify-send "Claude Code: your turn" "$(jq -r '.cwd' | xargs basename)".

Things that tripped me up

Hooks add up, they don't replace. Your user, project and local settings all contribute hooks, and they all run, in parallel. If a project's .claude/settings.json already has a Stop hook, yours runs next to it.
The permission alert is delayed on purpose. permission_prompt waits about six seconds, so a prompt you answer right away never pings you. Don't "fix" it by hooking PermissionRequest instead unless you want an alert for every single approval.
Being in the window doesn't mean you're looking. The hook can't tell whether you're watching that terminal. If the alerts get annoying while you're at your desk, keep only the permission one and drop Stop.
Some terminals show status by themselves. Terminals that support the OSC 7501 status protocol show whether each session is working or waiting, with no setup, from Claude Code 2.1.295 on. Check your terminal's docs.

When there are more than a few sessions

Past three or four sessions, notifications help but you still have to find the right tab. That's the problem I built Paneherd for: a VS Code / Cursor extension that opens each session as a terminal in a grid and labels every pane Working, Needs permission or Your turn, using the same hooks as above. Notifications and sounds are in the free version. There are other extensions for this in the Marketplace too, and for a single session the setting in step 1 is all you need.

What do you use: the bell, a hook, or something else?

11 things I learned building a tool on Claude Code hooks

Eren Çolak — Wed, 11 Nov 2026 08:19:19 +0000

I usually have four or five Claude Code sessions open at once, and my problem was never the agents. It was me: a session would sit on a permission prompt for twenty minutes in a tab I wasn't looking at, or two sessions would edit the same file and one would quietly undo the other.

So I built a VS Code / Cursor extension that runs each session as a terminal in a grid and shows, at all times, whether it is working, waiting for a permission or waiting for me. Early on I tried reading the terminal output to guess the state. It was fragile, so everything below comes from Claude Code's hooks instead.

These are the notes I wish I'd had at the start. They were checked against Claude Code 2.1.x; hook behavior changes between versions, so test against yours.

1. Give each session its own hooks with `--settings`

You don't have to touch ~/.claude/settings.json. Start a session with:

claude --settings /path/to/session-1.json

Hooks from --settings are added to the user's and the project's hooks, not swapped in for them. So each session can report to your tool, and whatever hooks the user already has keep working.

2. Use command hooks that run curl, with an args array

Each hook in my settings file is a command hook that POSTs the hook's JSON input (which arrives on stdin) to a local server:

{
  "hooks": {
    "Stop": [{ "hooks": [{
      "type": "command",
      "command": "/usr/bin/curl",
      "args": ["--silent", "--output", "/dev/null",
               "--connect-timeout", "1", "--max-time", "3",
               "--request", "POST",
               "--header", "X-My-Token: <per-window token>",
               "--header", "Content-Type: application/json",
               "--data-binary", "@-",
               "http://127.0.0.1:7777/hook/session-1/Stop"],
      "timeout": 23
    }]}]
  }
}

Passing args as an array means no shell is involved, so the same file works under Git Bash, PowerShell and sh. That saved me a whole class of Windows quoting bugs. I also tried type: "http" hooks; in my testing they did not fire for SessionStart, so I stayed with command hooks.

3. Put the routing in the URL, not the body

The URL says which session and which event: /hook/<session>/<event>. The server never has to parse the body to know who is talking. It only listens on 127.0.0.1 and rejects requests without the per-window token.

4. Be careful what reaches stdout

For some events, SessionStart and UserPromptSubmit among them, the hook's stdout becomes part of Claude's context. Picture this: the editor is closed, something else now owns your port, and its error page gets injected into the prompt.

So hooks that don't make decisions send curl's output to /dev/null (NUL on Windows). Hooks that do make decisions (PreToolUse, PermissionRequest) use --fail, so an error page never reaches Claude. The server answers everything else with an empty 204 right away.

5. Hooks are synchronous, and that is useful

Claude waits for each hook, so events reach your server in the order Claude emits them, and you never have to reorder. The cost is that slow hooks slow Claude down. Keep the connect timeout at a second and the total time at a few seconds for everything except permission decisions.

6. Waiting on PermissionRequest blocks nothing

This one surprised me. While a PermissionRequest hook is waiting, Claude is already showing its own permission dialog in the terminal. So the hook can wait a long time (mine waits up to an hour) for an answer from somewhere else, such as a sidebar inbox or a phone, and the user can still answer in the terminal. Whichever answer comes first wins.

One catch: when the prompt is answered outside the terminal, no hook event arrives until the tool finishes. Mark the session as working yourself, or it looks stuck on "needs permission".

7. Map events to states, and read the Notification type

This is the mapping that ended up working:

Event	State
`UserPromptSubmit`, `PreToolUse`, `PostToolUse`	working
`PermissionRequest`, or `Notification` with `permission_prompt`	needs permission
`Notification` with `elicitation_dialog` / `agent_needs_input`	asking a question
`Stop`	your turn
`SessionEnd` (except reason `clear`)	exited

idle_prompt deserves a note: it arrives about 60 seconds after a finished turn. Use it only as a fallback when you missed the Stop. Otherwise you alert the user a second time about something they already saw.

8. SessionStart fires before the prompt is ready

If your tool types a first prompt into a new session right after SessionStart, the Enter can get swallowed and the text just sits in the input box. No hook tells you "the prompt is ready now."

What works for me is to wait about two seconds after SessionStart. If no UserPromptSubmit follows within a couple of seconds, press Enter again, up to four times. Enter on an empty prompt does nothing, so retrying is safe.

9. Your usage limits only reach the status line

Claude Code passes rate_limits (five_hour and seven_day, each with used_percentage and resets_at) to your status line command on stdin. As far as I can tell, that is the only place they are available locally. Post the status line input to your server the same way as the hooks, and you have live limit data with no API calls.

Two more things about the status line:

It is the only place inside the terminal you can draw. Use plain ANSI colors so the user's theme decides how they look, light or dark.
Unlike exec-form hooks, the status line command runs through a shell (Git Bash, cmd or PowerShell on Windows), so quote it to mean the same in all of them.

10. Sessions outlive your tool

After a window reload or an extension update, the Claude processes are still running and still posting to the old address. So my server comes back on the same port with the same token, and per-session settings files are deleted only once the process is gone, not when the extension stops.

11. A file-conflict guard from PostToolUse + PreToolUse

To stop two sessions from silently overwriting each other:

On PostToolUse of Edit, MultiEdit and Write, record which session wrote which file. Using the post event means only edits that actually ran are counted.
On PreToolUse of a write, check whether another live session wrote the same file in the last ten minutes, after this session's own last write. If so, return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "..."}}, and Claude asks the user before writing.

The honest limitation: files changed through Bash are invisible to this. Git worktrees per session solve most of the problem anyway. The guard is for what's left.

All of this ships in Paneherd, the extension I built along the way. It's free for unlimited sessions, notifications and usage limits, and a one-time $2.99 Pro adds a shared permission inbox, the file-conflict guard and approving from your phone. It runs locally, with no telemetry.

If you're building on Claude Code hooks too, I'd like to hear what tripped you up. What did you have to learn the hard way?

How to run multiple Claude Code sessions at once

Eren Çolak — Wed, 04 Nov 2026 09:35:53 +0000

I make Paneherd, which is option 4 below. Originally published at paneherd.com.

Claude Code works best on one focused task at a time, so the way to get more done is to run several sessions in parallel: one fixes a bug, one writes tests, one updates the docs. Doing that well comes down to three things: keeping the sessions from overwriting each other, noticing when one of them is waiting for you, and not running out of usage halfway through.

Here are four ways to do it, and what each one leaves to you.

1. Separate terminals

The simplest way: open a terminal per task and run claude in each, or use split panes in tmux, Windows Terminal or your editor. It costs nothing and works everywhere.

What it leaves to you: every session asks for permission in its own terminal, so you have to look at each one to see which is stuck. If two sessions work in the same folder, they can edit the same file without knowing about each other.

2. Git worktrees

A git worktree is a second checkout of the same repository in another folder, on its own branch. Give each session that changes code its own worktree and they cannot overwrite each other; you merge their branches when they are done. Claude Code can create one for you with claude --worktree.

What it leaves to you: each worktree needs its own dependencies installed and its own dev server port, and you still watch each session separately.

3. Claude Code's agent view

Claude Code has its own view of running sessions (claude agents), and the official VS Code extension shows the status of each session. Agent view lists background sessions by state (working, needs input, completed) and, inside a git repository, moves each session into its own worktree before it edits. The extension runs several conversations in tabs and queues a message you send while Claude works. Permission prompts are still answered in each session. Check the Claude Code documentation for what your version includes.

4. A grid in VS Code or Cursor

Paneherd is an extension that opens each session as a real terminal in the editor area and lays them out in a grid. The sidebar shows each session's status from Claude Code's own hook events, counts the ones waiting for you, and jumps to the next one. On top of that:

One permission inbox (Pro): prompts from every session collect in the sidebar, with the command or file, and you answer them there.
Conflict guard (Pro): when sessions share a folder, Claude asks before editing a file another session changed in the last ten minutes.
Broadcast and queue: send one prompt to several sessions, or queue the next prompt for a busy one (queue is Pro).
Usage limits: the five-hour and weekly limits of your plan, at the top of the sidebar.

It works alongside worktrees: open a session per worktree and see them all in one window. The free version runs up to four sessions at once.

Tips that apply whichever way you choose

One task per session, stated in the first prompt. Sessions that wander are the ones that collide.
Don't let two sessions edit the same files. Split work by area, or use worktrees.
Keep permission prompts on for anything that touches the outside world. Answer them quickly so sessions don't sit idle.
Watch your limits. Parallel sessions use your plan's limits several times faster.

More on this: handling permission prompts across sessions and how parallel sessions use your usage limits.

How do you run your sessions? I'd like to hear what works for you in the comments.

Why Claude Code usage runs out so fast, and what is using it

Eren Çolak — Wed, 21 Oct 2026 12:51:50 +0000

Hitting your session or weekly limit sooner than your activity suggests is one of the most common complaints about Claude Code. The cause is usually not one big thing: a session that has been open for hours spends far more than the work you typed into it. Anthropic's cost documentation (checked 21 October 2026) lists the usual reasons. This guide goes through them, then shows how to find which one is yours.

Find out first: `/usage`

Before changing habits, look. On a Pro, Max, Team or Enterprise plan, /usage shows your plan limits and a breakdown of what counts against them:

Attribution: recent usage attributed to skills, subagents, plugins and individual MCP servers, each as a share of the total.
Behavior flags: long context or cache misses, flagged when one accounts for 10% or more of recent usage, each with a tip.
Loops: your heaviest /loop and other scheduled tasks, by total tokens (newer versions of Claude Code).

Press d or w to switch between the last 24 hours and 7 days. The figures are approximate and come from the session history on that machine, so usage from other devices or claude.ai is not in them. Newer versions also add a prompt cache line to the Session block, showing the share of input served from cache and how many misses there were.

Eight reasons usage climbs

These are the causes the documentation names for a long session using more of your limit than it seems to deserve.

1. A long conversation is re-read on every request

Claude Code sends your whole conversation with each request, and every round of tool use sends it again with the results. Prompt caching re-reads that history at the cheaper cached rate, but a one-line question at the end of a day-long session still draws on the entire conversation. Fix: run /clear when you switch to unrelated work (use /rename first and /resume later if you want to come back), and /compact with instructions about what to keep when you need continuity.

2. Cache misses after a break

Your first message after a pause longer than the cache lifetime misses the cache and reprocesses the whole context at full rate. Fix: if you know you are done with a session for a while, start fresh later rather than resuming a huge context after the break.

3. Scheduled tasks keep firing

A /loop or other session-scoped scheduled task fires on its interval even while the session is idle, sending the full context each time. Fix: check the Loops rows in /usage and stop tasks you forgot.

4. Messages from your other sessions

When another of your sessions sends a message to an idle one, it starts a new turn that sends the full context. The crossSessionInbound setting can be set to hold to keep inbound messages from being delivered.

5. Goal check-ins

While background work keeps an active goal waiting, Claude Code can start idle check-ins, each a new turn with your full context. Recent versions cap them at three per goal between your prompts; CLAUDE_CODE_GOAL_CHECKIN_MINUTES=0 turns them off.

6. Subagents and workflows

Every subagent, and every agent a workflow spawns, sends its own requests on top of the main conversation's. The attribution breakdown in /usage shows their share. Fix: give simple subagent tasks a smaller model (model: haiku in the subagent's configuration), and keep verbose work such as running tests in a subagent so only a summary returns.

7. Agent teams

Each active teammate keeps its own context window and keeps consuming tokens until it exits. The documentation says teams use roughly seven times the tokens of a standard session when teammates run in plan mode. Fix: keep teams small, give them focused tasks and shut teammates down when their work is done.

8. Compaction is a big request too

/compact has to read the conversation it summarizes, so compacting a large context is itself a large request. When you want a clean start rather than continuity, /clear costs nothing.

Smaller levers

Model and effort. Sonnet handles most coding tasks for less than Opus; switch with /model. Lower the effort level with /effort for simple tasks.
MCP servers. Run /context to see what fills your context and /mcp to disable servers you are not using.
A big CLAUDE.md. It loads at the start of every session. Anthropic suggests moving workflow-specific instructions into skills, which load only when used, and keeping CLAUDE.md under 200 lines.
Vague prompts. "Improve this codebase" triggers broad scanning; naming the file and the change does not.
Plan mode and early course-correction. Press Shift+Tab for plan mode before big changes, and Esc as soon as Claude heads the wrong way.

When you run several sessions

Every session draws on the same allowance, each with its own conversation, so four sessions spend it faster than one, and a long-lived one spends more than a fresh one. /usage works per machine, not per session. Paneherd shows the five-hour and weekly figures at the top of its sidebar and estimates each open pane's approximate share of the current window from its transcript, so the heavy session stands out. It also flags a pane that repeats the same failing call, which spends usage and gets nothing done. The shares are an estimate based on Paneherd's own weights, not Anthropic's accounting. More in how parallel sessions use your usage limits.

Keep the numbers in view

If you only want the limits in front of you, without a sidebar or panes, the free Claude Code & Codex Usage Meter puts the five-hour and weekly percentages, and Codex's, in the VS Code status bar and warns at 85% by default. It reads what Claude Code and Codex already report on your computer and sends nothing anywhere.

Install Paneherd free

Originally published at paneherd.com/guides/claude-code-usage-running-out-fast. I make Paneherd, a VS Code extension for running coding agents side by side.

How to control Claude Code and Codex from your phone

Eren Çolak — Wed, 21 Oct 2026 11:50:59 +0000

A coding agent that needs you while you are away from your desk just waits: for a permission, an answer, or its next prompt. There are now several ways to reach it from your phone. They differ in which agents they cover, what the phone can do, and what they ask of your setup. In every one of them the agent keeps running on your computer, so your computer has to stay on and awake.

1. Claude Code Remote Control

Anthropic's own option. Remote Control connects the Claude app on iOS or Android, or claude.ai/code, to a Claude Code session on your machine. There are three ways to start it:

claude remote-control runs a server in the current folder that you start sessions from on the phone. Press the spacebar to show a QR code.
claude --remote-control starts an ordinary interactive session that the phone can join too.
/remote-control (or /rc) connects a session that is already running, including in the Claude Code extension for VS Code.

From the phone you can send messages, attach photos and files, and answer permission prompts. With Push when actions required turned on in /config, the Claude app notifies you when a session needs a decision. It needs a Pro, Max, Team or Enterprise plan and a claude.ai login: it does not work with an API key, or with ANTHROPIC_BASE_URL pointing at a gateway. On Team and Enterprise an Owner has to turn it on first.

Best for: Claude Code on a Claude subscription. It is the most complete option for Claude, and it is built in.

2. Codex in the ChatGPT app

OpenAI added Codex control to the ChatGPT app for iPhone and Android in 2026. You pair the phone with Codex on your computer by scanning a QR code shown by the Codex app, then start tasks, follow their progress and approve commands from the phone. Newer Codex CLI versions also have an experimental codex remote-control command for machines without the desktop app. Which plans, regions and host systems are covered has changed during the rollout, so check OpenAI's current documentation before you count on it.

Best for: Codex on a ChatGPT plan.

3. Happy, an open-source app for both

Happy is an open-source mobile and web client for Claude Code and Codex. You start the agent through its wrapper (happy claude or happy codex) instead of the bare command, and switch to the phone when you leave. Its makers say the connection is end-to-end encrypted, and it notifies you when the agent needs permission. Sessions you start without the wrapper are not covered.

Best for: one app for Claude Code and Codex, if you are happy to launch them through it.

4. SSH and tmux

The tool-independent way. Run your agents inside tmux on your computer and attach to the same tmux session from an SSH app on the phone (Termius, Blink and others), usually over a VPN such as Tailscale so the computer is not exposed to the internet. You see the real terminal of any agent, whatever its maker. A phone keyboard is a hard place to drive a terminal UI, though, and nothing tells you when an agent starts waiting.

Best for: people who already work in tmux, and agents no app supports.

5. Paneherd's phone remote, for every pane in your editor

If you run several agents of different kinds side by side in VS Code or Cursor, Paneherd runs each one as a pane in an editor grid, and its phone remote shows all of them on one page. Run Pair a Phone…, scan the QR code and click Allow in the editor. Your phone opens paneherd.com/remote in the browser, with no app to install, and lists every editor window's panes with their status: working, waiting for permission, asking a question, or done. You can send a prompt to one pane or to several at once. With Pro you also answer Claude Code's permission prompts from the phone (Allow, Always, Deny).

It works for Claude Code, Codex, Copilot, Gemini and Cursor panes alike (Gemini and Cursor panes take prompts but report no status), whatever plan or API key each one uses, because it talks to the editor rather than to Anthropic or OpenAI. Messages go through Paneherd's relay sealed with a key only your phone and your editor have, so the relay cannot read them. It only covers agents running as Paneherd panes.

Best for: a mixed herd of agents in your editor, seen and prompted from one page.

Side by side

	Agents	On the phone	Needs
Claude Code Remote Control	Claude Code	Claude app or browser	Pro, Max, Team or Enterprise; no API keys
Codex in ChatGPT	Codex	ChatGPT app	A ChatGPT plan; Codex app on the host
Happy	Claude Code, Codex	Happy app or browser	Starting agents through its wrapper
SSH and tmux	Any	An SSH app	tmux, SSH access, usually a VPN
Paneherd phone remote	Claude Code, Codex, Copilot, Gemini, Cursor	Browser	VS Code or Cursor with Paneherd

Which one to pick

Mostly Claude Code on a subscription: use Remote Control, it is built in. Mostly Codex: use the ChatGPT app. Several kinds of agents at once in your editor: Paneherd's phone remote shows them together, and you can still turn on Remote Control in a Claude pane when you want the Claude app's full view of that one session. The options do not exclude each other.

Originally published at paneherd.com/guides/control-claude-code-codex-from-phone. I make Paneherd, a VS Code extension for running coding agents side by side.