Manage your Claude Code sessions from the command line: list, restart, pause, resume, follow, and find them.
You run Claude Code sessions in the background (claude --bg), and
claude agents lists them. Then Claude Code updates, and every running session
stays on the old version until it restarts. Or you reboot, and every session
dies with whatever it was doing. Agent view acts on one session at a time, and a
plain restart drops the turn a session was in the middle of.
claudes does those jobs in one command, without losing work:
$ claudes restart --outdated --ping --dry-run
Restarting 2 session(s):
ID STATUS DIR NAME NOTE
034d46b9 busy ~/src/api-refactor api-refactor will be pinged
51572bb7 idle ~/src/docs docs
Dry run: nothing was changed.
Pinned, not restarted: release-notes. Name a session, or add --pinned, to include it.
$ claudes restart --outdated --ping
Restarting 2 session(s):
ID STATUS DIR NAME NOTE
034d46b9 busy ~/src/api-refactor api-refactor will be pinged
51572bb7 idle ~/src/docs docs
restarted api-refactor and pinged
restarted docsapi-refactor was mid-turn, so claudes stopped it, resumed it on the new Claude
Code, and sent it a prompt to pick up where it left off. The pinned session
stayed as it was. claudes also finds every past session, running or not, and
resumes or moves it from any directory. Anything it doesn't handle goes straight
to claude agents.
$ claudes ls
ID PINNED KIND STATE STATUS AGENTS AGE VERSION DIR NAME
3ec56511 yes bg working busy lead+2, 3 3h 2.1.325 ~/src/api api-refactor
ff78d735 - bg done idle - 5h 2.1.325 ~/src/claudes claudes-mvp
e89ec2c4 - tty - idle - 20m - ~/src/claudes e89ec2c4AGENTS shows the agent team a session leads, as lead+2, and the subagents it
runs now, as 3. claudes ls --wide adds its background shells, tokens, pull
requests, and what it's doing.
claudes # open agent view, as claude agents does
claudes ls plan # sessions with "plan" in the name
claudes ls -a # finished background sessions too
claudes restart --outdated --ping --dry-run # see what an update restart does
claudes restart --outdated --ping # then do it
claudes ping api "run the tests" # send one session a message
claudes logs -f api # follow a session's prompts, replies, and tools
claudes stop api # stop one session
claudes session ls --since 2d # every session from the last two days, past too
claudes session resume api # resume a past session in its own directory
claudes cd api # jump to a session's directory (see Shell setup)
claudes doctor # check claudes against the installed Claude Coderestart, pause, resume, and gc take --dry-run to show their plan
first. ping, stop, pin, and unpin act on the sessions you name.
claudes pause --dry-run # see what will be parked, and what won't
claudes pause # stop and park background sessions
# reboot
claudes resume --dry-run
claudes resume --ping # bring them back; mid-turn ones carry onpause leaves out pinned sessions, interactive ones, and leads of an agent
team, and a reboot ends them too. To keep them, name them
(claudes pause api notes) or add --interactive. After the reboot,
claudes resume NAME brings back any stopped background session, parked or not,
and the resume commands pause printed bring back interactive ones.
claudes needs Claude Code with claude agents on PATH. It is tested with
Claude Code 2.1.325, and claudes doctor says whether yours works with it.
macOS and Linux:
curl -fsSL https://github.com/uvw/claudes/releases/latest/download/install.sh | shWindows, in PowerShell:
irm https://github.com/uvw/claudes/releases/latest/download/install.ps1 | iexThe script checks the download against the release's checksums and, with the
GitHub CLI signed in, its build provenance, then
installs into ~/.local/bin, or %LOCALAPPDATA%\Programs\claudes on Windows.
Run claudes upgrade later to move to a newer release.
With Homebrew on macOS or Linux, winget on Windows (once Microsoft has approved its first version), or Go:
brew install uvw/tap/claudes
winget install uvw.claudes
go install github.com/uvw/claudes/cmd/claudes@latestInstalling claudes
covers picking a version or a directory, installing by hand, checking a
download, and uninstalling. Then run claudes doctor.
claudes init adds the shell function behind claudes cd NAME, and
claudes completion adds tab completion that offers session names. Add the
init line for your shell to its profile:
eval "$(claudes init zsh)" # ~/.zshrc
eval "$(claudes init bash)" # ~/.bashrc
claudes init fish | source # ~/.config/fish/config.fish
claudes init pwsh | Out-String | Invoke-Expression # $PROFILEShell setup
has the completion lines for each shell, and zsh's noglob alias, which keeps a
pattern such as plan* away from the shell.
A skill teaches a coding agent to use claudes, so you can ask it to "pin the docs session" or "restart my agents after the update". It carries the install steps too, so an agent can set claudes up itself.
claudes skill --install # install or update it for Claude Code
npx skills add uvw/claudes # or install it from the repository
claudes skill # print itclaudes with no command runs claude agents, and so does anything that is not
a claudes command. claudes COMMAND --help describes each command's flags, and
Using claudes explains
how they act and keep work safe.
Running sessions, as agent view lists them, plus finished background ones with
-a:
| Command | What it does |
|---|---|
ls [TARGET...] |
List them: pinned first, then busy, then newest |
where TARGET... |
Print the directories of the sessions that match |
pin, unpin |
Pin or unpin background sessions, as Ctrl+T does in agent view |
restart [TARGET...] |
Restart named sessions, or all but pinned ones |
pause [TARGET...] |
Stop sessions and park them for resume |
resume [TARGET...] |
Bring back parked sessions, or a stopped one |
ping TARGET [MSG] |
Stop a background session and resume it with MSG |
stop TARGET... |
Stop sessions; claudes resume brings a background one back |
logs TARGET[/MATE] |
Recent output; -f follows the transcript |
attach TARGET |
claude attach, by name |
gc [TARGET...] |
Take sessions finished over 7 days ago off the list |
team ls [LEAD...] |
Agent teams at work, with teammates and tasks |
Every session with a transcript, past or running (claudes s and
claudes sessions are short for claudes session):
| Command | What it does |
|---|---|
session ls [TARGET...] |
List them, newest activity first, with their size |
session search QUERY... |
Find them by their prompts, replies, and tool calls |
session show TARGET |
Directory, branch, version, times, size, and last prompt |
session where TARGET... |
Print their directories |
session resume TARGET [PROMPT] |
Resume one in its own directory, from anywhere |
session mv TARGET DIR |
Copy one to another directory, so it resumes there |
session du |
Disk space by directory; --top N for the biggest |
session triage |
Sort them into remove, review, and keep |
session gc [TARGET...] |
Move empty, copied, and leftover sessions to the trash |
cd TARGET |
Change to a session's directory (needs init) |
Setup and diagnostics:
| Command | What it does |
|---|---|
config |
Show or change settings in config.yaml |
mcp ls [TARGET] |
List a session's MCP servers, and whether each is on |
mcp profiles |
List the MCP profiles in config.yaml |
doctor |
Check the installed Claude Code against claudes |
doctor env |
Print versions, file locations, and the variables |
init bash|zsh|fish|pwsh |
Print the shell function behind claudes cd |
skill |
Print or install the agent skill |
completion SHELL |
Print the completion script for bash, zsh, fish, powershell |
upgrade |
Install the latest release in place of this claudes |
| Document | What it covers |
|---|---|
| Installing claudes | Every way to install, shell setup, the agent skill, and uninstalling |
| Using claudes | Naming sessions, flags, safety, past sessions, teams, logs, and MCP |
| Reference | Output, exit codes, troubleshooting, configuration, and files |
| Agent skill | How a coding agent uses claudes, as a skill |
| Security | Reporting a problem, and checking a download |
| Contributing | Rules for changes, the checks, and releases |
| Agents | What coding agents need on top of the contributing guide |
| Decisions | Each settled choice, why, and the alternatives |
| Releasing | How releases happen, recovering one, and repo settings |
| Changelog | What each release changed |
| Handoffs | Work one machine leaves for another, and a resume prompt |
| Third-party notices | The licenses of the Go modules built into the binary |
You need Go at the version go.mod names; with GOTOOLCHAIN=auto, the default,
go fetches it.
docs/contributing.md
lists the checks to run before a commit.
go test ./...
goreleaser build --snapshot --cleanclaudes is a tool: a pocketknife for the Claude Code command line. Its goals:
- Handle the jobs around running Claude Code sessions: restarting, pausing, resuming, finding, moving, and cleaning up after them.
- Act through the
claudecommand and the files Claude Code keeps, and pass anything else toclaude agents. - Stay safe to run against live work, as one small binary with no service behind it.
Its non-goals:
- Growing into an agent orchestrator or a multi-agent platform. claudes does not plan work, split it across agents, or decide what a session does next.
- Other coding agents, such as Copilot, Codex, or Pi. claudes manages Claude Code only.
Decision 29 says why.
