Install & Get Started

Install CrabCode TUI, fix PATH, sign in, and run your first session.

What it is

CrabCode TUI is the terminal entry point. Once the crabcode command is installed, run it inside a project directory and CrabCode treats that directory as the workspace: it reads code, edits files, runs commands, manages sessions, and asks for confirmation when an operation crosses a permission boundary.

There are two main public install entries; the exact program directory depends on region and platform:

Path	Best for	Program directory
`/downloads` page	Most users; copy the region/platform command	See the platform notes below
Release `install.sh`	macOS / Linux users who want mirror-first downloads and fail-closed checksum validation	`${CRABCODE_HOME:-$HOME/.crabcode}/bin`

On the downloads page:

macOS / Linux international direct blocks commonly use ~/.local/share/crabcode.
macOS / Linux mirror scripts commonly use ~/.crabcode/bin.
Windows CN mirror scripts install to %LOCALAPPDATA%\CrabCode, or %CRABCODE_HOME% if it was set.
Windows international direct blocks install to %LOCALAPPDATA%\crabcode\crabcode-<version>-win-x64.

Login, settings, sessions, memory, and plugins default to ~/.crabcode. Upgrading or removing program files does not remove that data.

Install

Start from /downloads, choose your region and platform, and copy the current command. The downloads page follows the stable release channel at runtime.

macOS / Linux can also use the mirror installer:

bash

curl -fsSL https://updates.acosmi.com/crabcode/install.sh | sh
curl -fsSL https://updates.acosmi.com/crabcode/install.sh | sh

The installer script:

Detects OS and CPU architecture.
Reads the latest version from the mirror first, then falls back to GitHub Releases.
Downloads the matching tarball and checksums-sha256.txt.
Verifies SHA256 and refuses to install if validation fails.
Installs crabcode, the embedded runtime, App Server, cron daemon, memory orchestrator, and runtime files.
Prints the PATH line needed by your shell.

Windows users should use the PowerShell block for their region on /downloads. The CN mirror script installs to %LOCALAPPDATA%\CrabCode or %CRABCODE_HOME% and writes that directory to the user Path. The international direct block extracts to %LOCALAPPDATA%\crabcode\crabcode-<version>-win-x64 and writes the versioned directory to the user Path.

Verify

Open a new terminal or PowerShell:

bash

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

doctor prints version, platform, whether git / gh are reachable, and bootstrap/runtime status.

If you see crabcode: command not found or Windows cannot locate the command, see Install, PATH, and uninstall.

First launch

bash

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

The first run guides you through Acosmi sign-in. Then you can type natural-language tasks directly in the TUI.

First session

Type a prompt:

shell

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

CrabCode explains what it plans to do. File writes, shell commands, external tools, and permission-boundary crossings ask for confirmation.

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
`/doctor`	Run diagnostics inside the TUI
`/release-notes`	View current release notes
`/exit`	Quit (Ctrl+D also works)

Upgrade

Re-run the same install method. Upgrading replaces program files only; it does not delete login, settings, sessions, memory, or plugins under ~/.crabcode.

bash

curl -fsSL https://updates.acosmi.com/crabcode/install.sh | sh
curl -fsSL https://updates.acosmi.com/crabcode/install.sh | sh

To pin a version:

bash

curl -fsSL https://updates.acosmi.com/crabcode/install.sh | CRABCODE_VERSION=v1.2.3 sh
curl -fsSL https://updates.acosmi.com/crabcode/install.sh | CRABCODE_VERSION=v1.2.3 sh

You can also try:

bash

crabcode update
crabcode update

Trust crabcode --help for the subcommands available on your build. /upgrade is an account-tier upgrade, not a binary upgrade.

Uninstall

There is no dedicated crabcode uninstall TUI subcommand. Choose the cleanup level:

Goal	What to do
Remove program files, keep login/history/memory	Delete the actual program directory and remove the PATH line
Fully clear local state	After removing program files, also delete `~/.crabcode` and `~/.crabcode.json`

See exact commands in Install, PATH, and uninstall.

Environment variables

Variable	Purpose
`CRABCODE_HOME`	Change the installer script's home base; binaries default to `${CRABCODE_HOME}/bin`
`CRABCODE_CONFIG_DIR`	Change the config root for account/session/memory/settings isolation
`CRABCODE_VERSION`	Pin the installer script to a version such as `v1.2.3`
`CRABCODE_MAX_CONCURRENT_AGENTS`	Subagent concurrency cap; default is 3 and excess work queues
`CRABCODE_DEBUG_LOGS_DIR`	Override debug-log output directory
`CRABCODE_DISABLE_CRON`	Set to `1` to disable the cron daemon
`HTTPS_PROXY` / `HTTP_PROXY` / `https_proxy` / `http_proxy`	Standard proxy variables used by network requests

CRABCODE_CONFIG_DIR does not fix PATH. If the command will not open, first confirm that the program directory is on PATH.

Troubleshooting

Symptom	Fix
`crabcode: command not found`	See Install, PATH, and uninstall; confirm the real program directory and shell config
`crabcode --version` still shows an old version	Run `command -v crabcode` and remove stale PATH entries that appear earlier
`doctor` reports missing `git` or `gh`	Install Git / GitHub CLI and reopen the terminal
Download failed	Use the mirror installer, or set `CRABCODE_VERSION` to a known version
SHA256 mismatch	Do not bypass it; remove the partial download and rerun install
Keep history but remove the app	Delete only the program directory, not `~/.crabcode`