Before you download.

Yes. Shellby is free software under the GPL-3.0, and the app in the repository stays GPL-3.0 and free. Using Claude with him needs your own Claude Pro or Max plan; keeping him as just a desk pet needs nothing.

One day there may be paid extras alongside the free crab. That's why contributors grant x-salmon the right to also license their work commercially (why).

Your plan. Each conversation is one official Claude Code process you signed in to yourself, and usage counts against your plan's normal limits, exactly as if you'd typed the task into a terminal. No API keys, no per-token billing.

Claude Code gets the environment as it is on your PC. If ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL or a Bedrock, Vertex or Foundry switch is set, Settings warns that it may bill that instead, and Always use my Claude plan (Settings → Claude) leaves them all out.

A Claude Pro or Max plan and Claude Code 2.1+. Install it and sign in once:

> npm install -g @anthropic-ai/claude-code
> claude auth login

Shellby walks you through a two-step check on first run (CLI found ✓, signed in ✓). A nightly check runs the newest Claude Code release against Shellby, so a CLI change that needs catching up is found early.

Yes. Pick Just the crab on first run: Health, the Wardrobe, his voice, trophies and crab cards, with no Claude and no account. He still talks, plays and dresses up, digs up gifts and keeps a tank and a beach. You can add Claude Code later from Settings.

Not on its own. The spending guard stops routines and workflows before they use the share of your 5-hour window you keep for yourself, and anything that can act without asking shows what it may do before you save it. Each turn also ends with its tokens and roughly how much of your 5-hour window it took.

Yes: the official, unmodified claude CLI, driven over the same stream-json protocol the Claude Agent SDK uses. Shellby has no model of its own and isn't a fork. Your skills, agents, hooks, MCP servers, CLAUDE.md files and permission rules carry over, and anything you set up in Shellby works in your terminal too. How it drives the CLI →

Only what you've allowed. The default Ask first mode asks before every edit and command your own rules don't already permit, and the fenced-off Autonomous mode is never on unless you pick it.

A tab can work in its own copy of the repo on its own branch that only merges back when you say so, never with a force-push, and Undo puts back every file a turn changed, including what a script or npm install did.

Shellby acts on your real files with your real permissions. Read what you approve, and keep backups.

Every mode reads freely. *Smart is Claude Code's auto mode: a safety classifier approves routine steps and blocks risky ones. Plan only proposes a plan card, and nothing changes until you approve. Autonomous is bypassPermissions: behind an explicit warning, never the default, and never reachable from the shellby command. Your own allow and deny rules in ~/.claude/settings.json still apply in every mode.

No. In every mode except Autonomous, Claude Code enforces the permissions and waits for your answer; Shellby only relays it. Anything that would mean fewer prompts goes through a separate, isolated confirmation window that even a compromised panel can't click. Security →

No. Shellby has no servers, no accounts of its own, no telemetry and no analytics. Nobody behind Shellby, including its author, receives anything about you or how you use it, except a crash report you choose to send.

It checks GitHub Releases for updates, Claude Code talks to Anthropic, and other services are contacted only when you use a feature that needs them. The privacy policy lists every connection.

No. You log in to the official Claude Code CLI yourself, and Shellby only reads claude auth status to show which account and plan it's on.

Conversation history lives in %APPDATA%\Shellby\sessions. Your PC's health readings, push-to-talk audio (Windows' offline speech recognizer hears it) and the time tracker never leave your machine, and the local ports for the shellby command, the plugin, the OBS overlay and the Stream Deck keys only accept connections from 127.0.0.1.

Packs hold data only: pixels, colours, short lines of text and a few settings. There's no code, scripting, HTML or anything that loads from the internet, and Shellby checks every pack when it loads. Before a pack installs, Shellby:

• looks the id up in the official registry index
• downloads only from the registry's own origin, with a size cap
• verifies the SHA-256 checksum from the index
• shows an isolated confirmation window listing every item

Plugins from the Skill Shop are different: they're code. Claude Code installs them, and only after a confirmation window that names where they really come from.

He's on the wallpaper all day, so this is measured on every pull request. On a Ryzen 9 3950X:

• Panel closed, crab visible: about 1.6–2.1% of one core and about 495 MB.
• Panel open behind your windows: about 0.5–0.8%.
• Nobody at the desk for 5 minutes: about 0.1%.

The Health page owns up to his share too: Shellby himself: 1% CPU, 450 MB. The full numbers →

That's Microsoft SmartScreen. It warns about any app that isn't code-signed or that few people have downloaded yet, and Shellby releases aren't signed yet. Click More info → Run anyway.

To check you got the real file: every release is built by GitHub Actions from the tagged commit and lists SHA-256 checksums in SHA256SUMS.txt. Compare them with Get-FileHash. Step by step →

Yes: Windows 10 and 11 (x64). There's no macOS or Linux version. If Claude Code lives on another machine, Settings → Connections → Other computers can run conversations there over ssh, from your Windows PC.

The installed version updates itself: he checks GitHub Releases, downloads in the background, and installs when you click Restart and update or quit. Your settings carry over. The portable build can't update itself; Scoop installs update with scoop update shellby.

He can keep Claude Code current too, with Claude Code's own claude update. More →

Settings, history, logs, your Wardrobe, routines and Shellby's copies of your repositories live in %APPDATA%\Shellby; the shellby command in %LOCALAPPDATA%\Shellby.

When you uninstall, Shellby asks whether to delete your data too. No is the default and keeps it, so a reinstall picks up where you left off. A silent uninstall (/S) keeps your data unless you add --delete-app-data. Pictures\Shellby holds cards you saved, so it's always left alone. Deleting your data →

Yes. With the Shellby plugin he reacts to Claude Code in VS Code, Cursor, Windsurf, Zed, JetBrains and Windows Terminal, and sits in its status line. The shellby command starts tasks from any terminal, Continue in a terminal carries a conversation on with claude --resume, and /shellby:handoff brings a terminal session into a tab.

No. Shellby is an independent open-source project, not affiliated with, endorsed by, or sponsored by Anthropic. “Claude” and “Claude Code” are trademarks of Anthropic, PBC. Shellby only automates the official Claude Code CLI you install and sign in to yourself, and your use of it is subject to Anthropic's terms.

Yes. Read him, change him, share him, build on him. The one condition of the GPL-3.0: if you hand out a changed version, it stays open under the same licence.

The name Shellby and the crab as a mascot aren't part of that licence. Fork the code all you want, just give your crab its own name and its own critter. What's reserved →

Skins, packs, bug reports and pull requests are welcome. npm install, npm run setup and npm run dev:crab get you a dev crab that needs no Claude account.

• First time? Pick a good first issue or a pack wish.
• Made a pack? Share it in the community gallery.
• Read CONTRIBUTING.md first. You keep the copyright to what you write.

Please don't open a public issue. Use GitHub's private reporting: the repository's Security tab → Report a vulnerability. You'll get a reply within a week.