Install & Get Started

Install CrabCode via the installer script, sign in, and run your first session.

What it is

CrabCode ships as a native binary:

Installed to ~/.crabcode/bin/crabcode (override with the CRABCODE_HOME environment variable)
The installer script adds ~/.crabcode/bin to whichever shell startup file it detects (zsh / bash / fish)
Cross-platform: macOS (arm64 / x64), Linux (arm64 / x64), Windows (x64)

When you see this doc

First-time install
Upgrading
When doctor flags an environment issue

Install (macOS / Linux)

bash

curl -fsSL https://raw.githubusercontent.com/Acosmi/CrabCode/main/scripts/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/Acosmi/CrabCode/main/scripts/install.sh | sh

The script will:

Detect platform (OS + architecture)
Fetch the matching tarball from GitHub Releases
Verify SHA256
Unpack into ~/.crabcode/bin/
Append the directory to your shell config (.zshrc / .bashrc / config.fish)

Open a new terminal afterwards (or source your shell config).

Install (Windows)

Download the Windows x64 archive from the GitHub Releases page, extract it to any folder, and add that folder to your PATH.

Verify

bash

crabcode --version
crabcode doctor
crabcode --version
crabcode doctor

doctor prints version, platform, whether git / gh are reachable, and a summary of the bootstrap config.

First launch

bash

cd /your/project
crabcode
cd /your/project
crabcode

The first run guides you through signing in to your Acosmi account (browser-based OAuth) or pasting an API key, then drops you into the TUI.

First session

Type a prompt:

shell

delete every console.log in this file
delete every console.log in this file

The model lays out a plan and asks for Enter at each step. Useful slash commands:

Command	Use
`/help`	See all slash commands
`/init`	Generate `CRABCODE.md` at the repo root
`/memory`	Maintain cross-session memory
`/clear`	Reset the current session context
`/model`	Switch model
`/exit`	Quit (Ctrl+D also works)

Upgrade

Re-run the installer — it pulls the latest release over ~/.crabcode/bin/:

bash

curl -fsSL https://raw.githubusercontent.com/Acosmi/CrabCode/main/scripts/install.sh | sh
curl -fsSL https://raw.githubusercontent.com/Acosmi/CrabCode/main/scripts/install.sh | sh

Pin a version: export CRABCODE_VERSION=v1.2.3 before running the script
What's new: run /release-notes inside the TUI to view the CHANGELOG
Auto-update channel: autoUpdatesChannel in settings.json (latest / beta / ...) controls which release channel the background updater watches — see settings

/upgrade is the account-tier upgrade flow (move to a Max plan), not a binary upgrade. Binary upgrades go through install.sh.

Uninstall

The installer script has no uninstall sub-command — do it manually in three steps:

bash

# 1. Remove the CrabCode root (binary + cache + config + debug logs)
rm -rf ~/.crabcode

# 2. Drop ~/.crabcode/bin from PATH
# zsh:  edit ~/.zshrc
# bash: edit ~/.bashrc or ~/.bash_profile
# fish: edit ~/.config/fish/config.fish
# Find the export PATH / set -gx PATH line that mentions "crabcode" and delete it

# 3. Reload the shell config
source ~/.zshrc   # or your shell's config file
# 1. Remove the CrabCode root (binary + cache + config + debug logs)
rm -rf ~/.crabcode

# 2. Drop ~/.crabcode/bin from PATH
# zsh:  edit ~/.zshrc
# bash: edit ~/.bashrc or ~/.bash_profile
# fish: edit ~/.config/fish/config.fish
# Find the export PATH / set -gx PATH line that mentions "crabcode" and delete it

# 3. Reload the shell config
source ~/.zshrc   # or your shell's config file

If you overrode the install root via CRABCODE_HOME, replace step 1 with your actual path. If you split config out via CRABCODE_CONFIG_DIR, remove that location too.

Environment variables

Variable	Purpose
`CRABCODE_HOME`	Override the install root (default `~/.crabcode`); binary lands in `$CRABCODE_HOME/bin/`
`CRABCODE_CONFIG_DIR`	Override the settings root (default `~`); isolate multi-account / multi-env configs
`CRABCODE_VERSION`	Pin which release the installer script pulls (e.g. `v1.2.3`)
`ACOSMI_DEFAULT_MODEL`	Override the default model (built-in default is `deepseek-v4-flash`)
`CRABCODE_MAX_CONCURRENT_AGENTS`	Subagent concurrency cap (default 3; over-budget calls queue, no error)
`CRABCODE_DEBUG_LOGS_DIR`	Override the debug-log output directory (default `$CRABCODE_CONFIG_DIR/.crabcode/debug/`)
`CRABCODE_SESSIONEND_HOOKS_TIMEOUT_MS`	`SessionEnd` hook timeout cap (default 1500ms)
`HTTPS_PROXY` / `HTTP_PROXY` / `https_proxy` / `http_proxy`	Standard proxy variables; CrabCode reads these to route through a proxy

Troubleshooting

crabcode: command not found — your new shell didn't pick up the config. Run source ~/.zshrc (or the file for your shell).
Download failed — check network, or pre-set CRABCODE_VERSION=v... to skip the "latest" lookup.
SHA256 mismatch — rerun the script (usually a half-downloaded tarball).