BitMagic.ClaudeBox.Cli 0.3.2

ClaudeBox

cb runs Claude Code sessions in named, colour-coded Windows Terminal tabs, keeps track of them, and brings back the ones that were running after a reboot.

Install

dotnet tool install -g BitMagic.ClaudeBox.Cli

Needs the .NET 10 runtime, Claude Code and Windows Terminal.

To update, run dotnet tool update -g BitMagic.ClaudeBox.Cli (see Updating).

Quick start

cb                                  start a session here, in a new tab, called "Claude"
cb new "Login bug" --work hotfix    start a named session with a red tab
cb ls                               see what you've got
cb restore                          after a reboot, reopen what was running

cb -? shows every command with examples; cb <command> -? shows all of a command's options.

Sessions can be given by name, the start of a name, their number in cb ls, or the start of their id. Commands that launch Claude open a new tab in the current Windows Terminal window; add --here to use the current tab instead. A --here session keeps the current tab's colours: Windows Terminal can't change a tab's colour or scheme once it's open, so only the title is set.

Commands

cb

Starts a session in the current folder, named from defaultName in the config (Claude, then Claude 2, ...).

cb new <name> [-- <claude args>]

Starts a new named session. Anything after -- is passed to claude, e.g. cb new "Spike" -- --model opus.

If the name is taken, cb asks whether to resume it, delete it and start again, or use a different name (see nameClash in the config).

cb resume <session>

Reopens a saved session with its conversation, in its own folder. Refuses if it's already running.

cb ls

Lists sessions with their work type (in its colour), status, when they were last active and their folder.

cb restore

Reopens sessions in tabs, all in one go. On its own it reopens only sessions that were interrupted (by a reboot, crash or shutdown); ones you closed yourself stay closed.

cb startup

Shows whether cb restore runs when you log in. cb startup enable turns it on and cb startup disable turns it off. It's added to your Startup apps (the per-user Run key), and opens a new Windows Terminal window with the restored sessions as tabs.

cb set <session>

Changes a session's details. Changes to an open session's tab show the next time it's opened.

cb rename <session> <new name>

Same as cb set <session> --name <new name>.

cb rm [<session>]

Forgets sessions. Claude's transcripts are kept unless you ask otherwise, and running sessions are never removed. Removing several lists them and asks first.

cb adopt [<session-id>]

Adds a Claude session that was started outside cb, then resumes it in a tab (unless it's still running somewhere else; see below). Without a session ID it lists the recent Claude sessions in this folder for you to pick from; with one (or the start of one) it finds that session in any folder. It's named after the name you gave it in Claude, or else the conversation's title.

A session that's still running somewhere else is only added, not opened a second time. It shows as running in cb ls until you close it, then cb resume carries it on in a cb tab. cb finds running sessions from a file Claude Code keeps for each one (~/.claude/sessions); that isn't a documented file, so if a Claude update changes it, cb can't tell which outside sessions are running.

cb config

Shows your settings and where the file is. Values are checked before they're saved, so a typo can't leave a config that won't load.

To pass something to Claude in every session, such as turning on Remote Control, set claudeArgs:

cb config set claudeArgs --remote-control
cb config set claudeArgs "--remote-control --model opus"
cb config unset claudeArgs

Setting it replaces what was there, so give every argument you want each time. Put quotes round the whole value when there's more than one argument, and round any single argument that has spaces in it ("--append-system-prompt \"be brief\""). These arguments are used on every launch, including resumes and restores, and go before any you gave a session with cb new <name> -- <claude args>.

cb work

Lists the work types, their colours, Claude arguments, and which is the default.

Sessions keep the colour they were given, so changing a work type doesn't recolour existing sessions; use cb set <session> --work <type> for that. Claude arguments are different: they're read each time a session opens, so a change applies to the type's existing sessions the next time they're opened.

A work type's Claude arguments go after the global claudeArgs (see cb config) and before a session's own, so the more specific one comes last. Setting them replaces what the type had. For example:

cb work add research --claude-args "--permission-mode plan"     research sessions plan rather than edit
cb work add hotfix --claude-args "--model opus"                 hotfixes use Opus
cb work add query --colour teal --claude-args "--model haiku"   a new type for quick questions
cb work add hotfix --claude-args none                           back to no extra arguments

cb alias

Lists your aliases: shortcuts for cb commands you use a lot. With "c": "rm --exited --yes", cb c runs cb rm --exited --yes, and anything you type after the alias is added to the end.

An alias is one word and can't be the name of a cb command. Its command is what you'd type after cb, with quotes around parts that have spaces, and it can't use another alias.

Statuses

Config

%APPDATA%\claudebox\config.json is created on first run. Change it from the command line with cb config, cb work and cb alias, or edit it by hand (cb config rewrites the file, so comments you add are lost). Command-line options override it for a single command.

{
  "claudePath": null,
  "claudeArgs": [],
  "defaultWork": "general",
  "defaultName": "Claude",
  "nameClash": { "action": "ask", "nonInteractive": "fail", "renamePattern": "{name} {n}" },
  "work": {
    "general":  {},
    "hotfix":   { "colour": "red" },
    "feature":  { "colour": "green" },
    "research": { "colour": "blue" }
  },
  "aliases": {}
}

Colours can be a name or hex (#RRGGBB or #RGB), and names are saved as names rather than converted to hex. red, orange, amber, yellow, green, teal, blue, purple, pink and grey are picked to look good as tab colours; any other standard web colour name works too (crimson, navy, darkorange, ...). Spaces and case don't matter, so Dark Orange is darkorange.

How it works

cb starts claude with a session ID it chooses and passes some hooks with --settings, so your own Claude settings aren't touched. The hooks keep the session ID up to date after /clear and track whether Claude is busy or waiting. Exiting Claude or closing its tab marks the session as ended; a shutdown or crash leaves it open, which is how cb restore knows what to bring back.

Sessions are kept in %APPDATA%\claudebox\sessions.json.

Updating

dotnet tool update -g BitMagic.ClaudeBox.Cli

Tabs run a private copy of cb (in %APPDATA%\claudebox\bin), so you can update while sessions are open; old copies are removed once nothing is using them. A session started with --here runs from the installed tool itself, so close those before updating.

Building from source

dotnet build
dotnet test
install-local-build.bat

install-local-build.bat installs your build as the global tool, numbered <next version>-local.<timestamp>, and install-from-nuget.bat switches back to the latest release. Both uninstall first and install an exact version from a single source, so it doesn't matter which one is numbered higher.

Releases are published to NuGet by pushing a v* tag (e.g. v0.2.0), or by running the Release workflow on GitHub.

Licence

GPL-3.0. See LICENSE.