Documentation

Setup, trust, and support notes.

The short version of what you need before downloading Blackcrab and what to check if the local Claude Code bridge does not start cleanly.

Getting started

Install and authenticate Claude Code before opening Blackcrab.
```
npm install -g @anthropic-ai/claude-code
claude auth login --claudeai
```
Anthropic Console billing users can use the Claude Code console login flow instead.
Download the latest Blackcrab installer from GitHub Releases, then launch the app.
Confirm the setup screen shows Claude Code as installed and authenticated.
Pick a working directory, start a new session, or resume an existing session from the sidebar.
Use grid mode for up to six live panels, open local preview URLs in the side webview, and export finished sessions as Markdown.

Requirements

Released app

Blackcrab publishes desktop installers for macOS, Windows, and Linux. It expects the Claude Code CLI to be installed and signed in on the same machine.

Local development

Building from source requires Node.js 20 or newer, Rust stable with Cargo, and the Tauri 2 system dependencies for your target platform.

Experience level

The project is early and aimed at people already comfortable with Claude Code, local repositories, shells, and developer tools.

Privacy and security

Blackcrab is a local app. It does not operate a hosted backend, proxy Claude traffic, or ask for Anthropic credentials.
It reads Claude Code session JSONL files under ~/.claude/projects, selected project paths, git metadata, UI preferences, and files you explicitly attach.
Messages are sent to your local claude CLI subprocess. Network requests come from Claude Code, tools it runs, opened URLs, or commands you execute locally.
Treat exported Markdown transcripts and Claude session files as sensitive. They can contain prompts, file paths, command output, and tool results.
Blackcrab is not a sandbox. It coordinates shells, Claude subprocesses, file paths, webviews, and git commands on your local machine.

Privacy details Security model

Troubleshooting

Claude Code CLI was not found

Run claude --version in your terminal. If it fails, install Claude Code and make sure the claude executable is available from your shell path.

Claude Code is installed but not authenticated

Run claude auth status. If needed, sign in with claude auth login --claudeai or use the Console billing login flow.

Sessions are missing from the sidebar

Confirm the working directory is correct and that Claude Code has saved session files under ~/.claude/projects.

Preview URLs do not render

The preview panel can open HTTP and HTTPS URLs. Some production sites block embedded webviews; use the external browser action when a site refuses to load inside the app.

Updater or download issues

Installers and updater artifacts are published through GitHub Releases. If the in-app update fails, download the latest release manually.

Use Discussions for setup questions, ideas, and general help. Use Issues for reproducible bugs.

Ask in Discussions Open a GitHub issue

Known limitations

Blackcrab is pre-1.0 software. Expect behavior and packaging details to change.
macOS, Windows, and Linux installers are published from the release workflow. Windows and Linux builds are newer and may need extra validation across distributions and machine setups.
The app depends on a working local Claude Code installation and does not replace Claude Code authentication, billing, or CLI configuration.
Private one-on-one setup support is not part of the current project scope.
Only run Blackcrab on machines and repositories where local developer-tool access is acceptable.