ClaudeCode-Portable: Run Claude Code from a USB Drive

Why ClaudeCode-Portable Exists on a USB Drive

ClaudeCode-Portable addresses a specific portability problem: installing Claude Code, its Node.js runtime, provider configuration, conversation history, attachments, caches, and logs separately on each computer. Its launcher places those app-owned components inside the project directory. A developer can therefore carry the workspace on removable media and start it on a different supported computer without performing a global installation on that machine.

The intended audience is developers who work across Windows, Linux, and macOS environments and need a coding-agent setup that follows the folder rather than the host's user directory. The project uses Anthropic's official Claude Code CLI and Agent SDK, so portability does not mean replacing Claude Code with a different agent engine. It also provides a browser-based Studio dashboard for chat, tool approvals, attachments, Markdown, code highlighting, and diagnostics.

This approach does not make the computer itself portable. The target machine still needs a compatible operating system and architecture, and each platform and architecture may require its own first-time runtime download. Portable credentials and chat data also move with the folder, so treating the drive like an unattended shared secret store would be a mistake.

How ClaudeCode-Portable Stores and Starts Its Runtimes

The launcher architecture separates application code from generated local state. `dashboard/` contains the browser interface, `lib/` holds providers, adapters, sessions, runtime management, and the agent bridge, while `tools/` contains launcher and setup utilities. Generated content remains in `data/` and `engine/`. Both directories are excluded from Git.

The `engine/` directory stores runtime copies by operating system and architecture. The README lists Node.js `24.21.0`, Claude Code `2.1.247`, Claude Agent SDK `0.3.247`, and `claude-adapter` `2.2.1` as pinned components. Windows, macOS, Linux x64, and Linux ARM64 installations can coexist on the same drive. After the compatible runtime has been downloaded, later launches reuse that copy.

Cloud-backed providers still require a network connection after setup. The exception is a locally installed Ollama model, provided that Ollama or the relevant local model service is already available. Custom adapters bind only to `127.0.0.1` and receive a fresh local token for each run, according to the README. That restriction limits network exposure, but it does not remove the need to protect the portable folder.

Installing ClaudeCode-Portable and Opening Studio

On Windows, open PowerShell in the project directory and run the included launcher. The first launch downloads a checksum-verified Node.js runtime and installs the pinned official Claude Code packages under `engine/`.

.\START.bat

On Linux or macOS, make the launcher executable once, then start it:

chmod +x start.sh
./start.sh

The menu offers the Studio dashboard, the Claude Code terminal, provider configuration, local model setup, runtime repair or update, and runtime rollback. Pressing Enter selects the dashboard. Cloud provider configuration still requires credentials and internet access. The first setup also needs internet before the portable runtime is available.

The main menu includes these maintenance actions:

1  Open studio dashboard
2  Launch Claude Code terminal
3  Configure providers
4  Set up local models
5  Repair / update pinned runtime
6  Roll back runtime

The README also includes `RESUME.bat` and `resume.sh` for resuming Claude sessions on their respective platforms. It describes Studio and terminal conversations as using Claude Code conversation IDs, which allows the GUI and terminal paths to resume shared Claude history.

Configuring Ollama or LM Studio for Local Models

ClaudeCode-Portable supports two documented local-model paths, but it does not manage every component of local inference. Ollama has an interactive portable setup command on both operating-system families.

On Linux or macOS, this enters the repository's local model setup:

bash start.sh local-setup

On Windows, the equivalent command is:

.\START.bat local-setup

The README warns that local inference depends on available RAM or VRAM, a useful context window, and a model that supports tool calling. Downloads can consume several gigabytes. These are hardware and model requirements, not promises of particular response speed or model quality.

LM Studio follows a different boundary. The developer downloads a tool-capable model, opens `Developer → Local Server`, starts that server, and then configures ClaudeCode-Portable to connect to it. The documented default address is:

http://127.0.0.1:1234

The dashboard then discovers the loaded model or accepts its exact identifier. LM Studio remains managed by its own application. ClaudeCode-Portable is the client and coding workspace, not a replacement for the LM Studio server or model runtime.

Provider Coverage and Claude Feature Boundaries

The project documents nine provider profiles: NVIDIA NIM, DeepSeek, OpenRouter, Google Gemini, Anthropic Claude, OpenAI, Ollama, LM Studio, and Custom API. Native Anthropic access uses the Messages API or terminal login. Several other providers are described as Anthropic-compatible endpoints or use Chat Completions, while the custom provider can use either Chat Completions or the Responses API.

This variety is useful when a development machine lacks access to the intended provider or when a local model is available. The cost is feature consistency. The README explicitly states that non-Claude models are experimental and unsupported by Anthropic. Tool calling, image handling, context limits, and conversation resume behavior depend on the selected model and provider.

The built-in custom adapter supports streaming Chat Completions, tools, and images. The external `claude-adapter` offers native or XML tool modes and optional aliases, but no image support. The Responses API mode supports `/responses`, incremental text, and streamed tool arguments. These are different compatibility surfaces, not identical Claude Code environments. A provider accepting a request is therefore weaker evidence than documentation showing the required tool and resume behavior for that specific model.

ClaudeCode-Portable Versus Native and Host-Level Claude Installations

ClaudeCode-Portable instead carries app-owned settings, credentials, chats, attachments, caches, and logs in the project folder, then selects a compatible runtime beneath `engine/`.

The alternative is Claude Code through Anthropic's terminal login path, without this wrapper's Studio dashboard or provider-switching layer. ClaudeCode-Portable adds a local launch menu, a graphical interface, multiple adapters, shared Claude conversation IDs, and portable runtime management. It also adds experimental compatibility paths whose behavior is controlled by third-party providers.

The portable approach is therefore most useful when device independence is the immediate requirement. Native installation is the cleaner choice when persistent host configuration is acceptable and consistently supported Anthropic behavior matters more than carrying a full workspace on removable media.

Upgrade Cost, Repository Activity, and MIT Terms

Runtime maintenance is built into the launcher through repair, update, and rollback actions. The repository has no GitHub releases, so version discovery through GitHub release notes is unavailable. The package manifest identifies the project version as `2.0.0`, while the README separately lists pinned runtime component versions. Users therefore need to distinguish the application version from the bundled Node.js, Claude Code, Agent SDK, and adapter versions.

The last push was on 2026-09-12. The repository is not archived. There are no published GitHub releases, and the README does not describe an automatic release schedule. First-time downloads, storage for multiple operating-system runtimes, local model downloads, and provider-specific configuration all contribute to operational cost.

The repository declares an MIT license. That permits use, modification, distribution, and sublicensing subject to the license text and notice conditions. The generated `data/` directory can contain credentials, conversation history, attachments, and logs, so anyone adopting the project should determine how they will protect or encrypt that directory and which removable media they use. This is an operational review rather than legal advice.

Editorial conclusion

Developers who routinely move between computers and want Claude Code without a global installation should verify provider support, local hardware requirements, and the security of portable credential storage before adoption. People who need uniformly supported Claude behavior across every provider should stay with Anthropic's native integration because the README explicitly describes non-Claude models as experimental.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. techjarves/ClaudeCode-Portable on GitHub