pebl / faq

Running multiple Claude Code sessions: questions and answers

The things people search for before they try running Claude Code in parallel.

What is pebl?

pebl is a free, open-source terminal orchestrator for Claude Code: it runs several Claude Code sessions side by side in one terminal window and shows at a glance which ones need you. It has a project sidebar on the left, the real claude CLI in the main pane and a status bar at the bottom. It is MIT licensed and not affiliated with Anthropic.

How do I run multiple Claude Code sessions at the same time?

Install pebl, run pebl in a project folder, and press ctrl+n for each new Claude Code session. Every session keeps running in the background; ctrl+j and ctrl+k switch between them, and ctrl+\ opens up to four side by side in columns.

How do I know which Claude Code session is waiting for input?

pebl reads Claude Code hooks, so a session that needs a permission or an answer turns orange in the sidebar within a moment. ctrl+g jumps to whichever has waited longest, ctrl+y lists everything waiting, errored or finished, and a desktop notification can take you straight there.

Can I get a notification when Claude Code needs input or finishes?

Yes. On macOS pebl sends a desktop notification when a session is waiting, errors or finishes, and clicking it opens that session. It can also play a chime, ring the terminal bell (the Linux default), send a notification through Ghostty, iTerm2, Kitty or WezTerm, or push to your phone with ntfy.sh if a session stays unanswered for two minutes.

How do I run Claude Code agents in parallel on the same repo without conflicts?

Give each one its own git worktree. In pebl, w starts a session in a new worktree on a pebl/<name> branch, and f merges it back, opens a pull request or discards it. The task queue starts queued tasks in their own worktrees, two at a time by default, and best of N runs up to four attempts at one task so you can keep the best.

How do I see how much context a Claude Code session has used?

Every session in pebl’s sidebar has a context gauge: grey normally, orange over 80% and red over 95%, so you can /compact in time. The sidebar also shows your plan usage, the 5 hour and weekly windows and when the 5 hour one resets.

How do I review what Claude Code changed before merging?

Press d on a session in pebl for a full-screen diff of its folder. Comment on any line and s sends all comments back to that session as one prompt. R starts a second, read-only Claude that reviews the diff and leaves its findings on the right lines.

Why not just use terminal tabs or plain tmux for multiple Claude Code sessions?

Tabs and tmux run the sessions but can’t tell you which one is waiting. pebl reads Claude Code’s own hooks, so every session shows running, waiting, idle or error in one sidebar, ctrl+g jumps to the one that needs you, and sessions keep running after you quit.

What should I look for in a Claude Code session manager?

Check five things: does it run the real claude CLI or a wrapper, does it know when a session is waiting for input, does it isolate parallel work in git worktrees, does it leave your Claude Code settings alone, and does it fit how you work (terminal app or desktop app). pebl is terminal-native, runs the real claude, uses hooks for status, supports worktrees and never edits your settings.

Do I need to know tmux to use pebl?

No. pebl uses tmux 3.2 or newer under the hood, on its own private tmux server, so it never touches your own tmux sessions or config. You only use pebl’s keys; tmux is just installed.

Does pebl replace Claude Code?

No. The main pane is the real claude CLI, untouched, with your own login, settings and plugins. pebl only arranges sessions, watches their status and adds the sidebar, search and notifications around them.

Does pebl change my Claude Code settings?

No. pebl never edits ~/.claude/settings.json. The hooks it needs are passed to each session it starts with the --settings flag, so plain claude runs outside pebl are unaffected.

Can I use more than one Claude account?

Yes. pebl login adds an account, pebl profile picks the default or ties a project to one, and typing /switch inside a session reopens the same conversation on another account.

Can I search and resume old Claude Code conversations?

Yes. ctrl+f searches every past Claude Code conversation on your machine, prompts and replies, and enter resumes the one you pick in a new session.

What happens to my sessions when I quit pebl?

They keep running. ctrl+q leaves pebl, and running pebl again reattaches to every session exactly where it was.

Which operating systems does pebl support, and what does it need?

macOS and Linux. It needs Rust to build, tmux 3.2 or newer, and Claude Code installed and logged in. Install with cargo install --git https://github.com/buricodes/pebl, then run pebl doctor to check everything.

Is pebl free?

Yes. pebl is free and open source under the MIT license, with the source on GitHub. You still need your own Claude Code subscription or API access.

Does pebl send any data?

Only a once-a-day usage ping with a random install id and the version number, so the website can count weekly users. No names, paths, projects or anything from Claude. Turn it off with telemetry = false in ~/.pebl/config.toml or DO_NOT_TRACK=1.

Last reviewed .

Install: cargo install --git https://github.com/buricodes/pebl · pebl home · GitHub