How to Run Open-Source Claude Code (Claude Code OSS): Complete Developer Guide 2026

Anthropic's Claude Code — the agentic CLI that lives in your terminal, reads your codebase, and drives git workflows through natural language — is now open source. The agent layer is on GitHub at anthropics/claude-code, which means you can read the full TypeScript source, fork it, audit it, and build from it. But before you spin up a self-hosted instance expecting zero API bills, there is one thing to get straight: the source code is open, but the model is not. This guide walks through everything you need to know about Claude Code open source — what it actually contains, how to install it, how to configure it, and how to extend it with BYOK and alternative auth backends.

What Is Claude Code Open Source (OSS)?

Claude Code is an agentic coding assistant — a CLI that takes natural-language instructions and executes real actions: editing files, running tests, managing git, scaffolding projects. The open-source release means Anthropic has made the TypeScript agent layer publicly available on GitHub. You can inspect the tool routing logic, the context management pipeline, the permission system, and all the plumbing that ties user commands to model calls.

What you do not get in the repo: model weights. Claude Code is not a self-contained LLM. The repo is the agent shell; every inference request still goes to Anthropic's API (or an alternative backend you configure — more on that in the BYOK section below).

The OSS Release — What Actually Happened

The source code became publicly available on March 31, 2026. The exact circumstances are disputed across sources — some attribute this to an accidental .map file inclusion in the published npm package that exposed unobfuscated TypeScript source, while others describe it as an intentional Anthropic decision. Either way, the code is now at github.com/anthropics/claude-code and Anthropic has continued shipping updates through the public repo. Verify the current license terms in the repo's LICENSE file before forking for commercial use.

Can You Run It Without Paying?

Short answer: no, not in the traditional "self-hosted" sense. Claude Code requires a live model backend, and by default that backend is Anthropic's API. To use it you need one of:

• A Claude Pro subscription ($20/month)
• A Claude Max subscription ($100–$200/month)
• A Teams or Enterprise plan
• An Anthropic Console API key (pay-per-token)

However, you can route it through alternative providers — Amazon Bedrock, Google Vertex AI, or a LiteLLM proxy pointing at any OpenAI-compatible model — which may reduce cost or remove the direct Anthropic subscription requirement depending on your setup. That path is covered in the BYOK section.

Anthropic also runs a Claude for Open Source program that gives qualifying OSS maintainers and contributors six months of Claude Max at no cost. If you maintain an active open-source project, that is worth checking before paying out of pocket.

Claude Code OSS vs. Paid Claude Code: Key Differences

• Agent source code: OSS — fully readable and forkable. Paid subscription — same binary, source not normally visible.
• Model access: OSS — requires separate auth and billing. Paid — included in subscription.
• Security audit: OSS — you can inspect every tool call in source. Paid — no direct source inspection.
• Custom forks: OSS — yes, build from source with modifications. Paid — not permitted.
• Alternative LLM backends: Both support Bedrock, Vertex AI, and LiteLLM via env vars.
• Auto-updates: OSS — manual, you manage the build. Paid — automatic via native installer.
• Cost: OSS — free to download; model calls billed separately. Paid — subscription plus usage within plan limits.

The practical takeaway: if you just want to use Claude Code, install the native binary and authenticate with your Anthropic account. If you want to audit, fork, or extend the agent layer, the open-source repo gives you the full picture.

Prerequisites

• Operating system: macOS 13.0 (Ventura) or later; Ubuntu 20.04+ or Debian 10+; Windows 10 (v1809+) with native installer or WSL
• RAM: 4 GB minimum, 8 GB recommended for large codebases
• Node.js: Required only if installing via npm. The native installer bundles its own runtime.
• Anthropic account: Claude Pro, Max, Teams, Enterprise, or a Console API key. Free-tier accounts do not include Claude Code access.
• Internet connection: Required for all model inference; Claude Code has no offline mode.

Installing Claude Code

There are three paths to a running Claude Code installation: the native installer (recommended), the legacy npm package, and building directly from the GitHub source.

Native Installer (Recommended)

The native installer bundles a self-contained runtime, handles background auto-updates, and requires no pre-installed Node.js.

macOS and Linux:

curl -fsSL https://claude.ai/install.sh | sh

Windows (PowerShell, run as Administrator):

irm https://claude.ai/install.ps1 | iex

After the script completes, the claude command is available system-wide. Verify with claude --version.

Install via npm (Legacy Method)

The npm package still works but is deprecated — Anthropic has moved to the native installer as the forward path. Use this only if you have a specific reason to manage Claude Code through your Node package manager:

npm install -g @anthropic-ai/claude-code

You will see a deprecation notice. It can safely be ignored for now, but plan to migrate to the native installer before the package is eventually removed.

Build and Run from the GitHub Source

This path is for developers who want to inspect, modify, or contribute to the agent layer itself. Check the repo's package.json for the canonical build scripts — commands may evolve across releases.

git clone https://github.com/anthropics/claude-code.git
cd claude-code
npm install
npm run build
node dist/cli.js

If the repo has migrated to a Bun build pipeline (check package.json scripts):

bun install
bun run build
bun dist/cli.js

For development iteration, most TypeScript repos support npm run dev or bun --watch for live-reload without a full rebuild on each change.

First Run and Authentication

The first time you run claude, it opens your default browser and prompts you to sign in to your Anthropic account:

claude

Complete the OAuth flow in the browser. Claude Code stores the resulting token locally and reuses it on subsequent launches. For non-interactive environments — CI/CD, Docker containers, remote servers — use an API key instead:

export ANTHROPIC_API_KEY=sk-ant-api03-...
claude

For CI/CD pipelines, store the key as a repository secret and inject it into the environment at runtime. Never hardcode it in workflow files or committed configuration.

Configuring Claude Code for Your Project

Two files drive Claude Code's behavior at the project level: CLAUDE.md (project context injected into the model's system prompt) and .claude/settings.json (tool permissions controlling what the agent can do autonomously).

CLAUDE.md — Your Project's Memory

Drop a CLAUDE.md file in your project root. Claude reads it at the start of every session. Use it to declare the project's purpose, conventions, safe commands, and off-limits areas. A global ~/.claude/CLAUDE.md applies across all projects — useful for personal preferences and tool defaults.

# Project: API Gateway Service
## Stack
- Node.js 22 + TypeScript
- PostgreSQL via Prisma
- Deployed on AWS Lambda

## Coding conventions
- snake_case for database columns, camelCase for TypeScript
- Async functions must use explicit error handling — no empty catch blocks
- Tests live in __tests__/ adjacent to source files

## Commands Claude may run without asking
- npm test
- npm run lint
- prisma migrate status

## Do not modify
- infrastructure/   (Terraform-managed, changes break prod)
- .env files        (secrets managed separately)

The more specific your CLAUDE.md, the less time Claude spends on wrong-framework suggestions or convention mismatches. Treat it as onboarding documentation for an engineer who never attended a sprint planning session.

settings.json — Controlling What Claude Can Do

The .claude/settings.json file controls which tools Claude can invoke autonomously versus which require human approval. The exact schema evolves with Claude Code releases — verify field names against the official docs or the TypeScript types in the source repo. A typical permission structure looks like:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(rm -rf*)"
    ]
  }
}

In shared team environments, commit a conservative settings.json that requires approval for all shell commands and restricts writes to src/. Individual developers can maintain personal overrides in ~/.claude/settings.json for higher autonomy on their own machines.

Core Workflows and Essential Commands

Once authenticated and configured, the most useful Claude Code interaction patterns for daily development:

• Interactive chat mode: Run claude and type requests in natural language. Claude maintains context across turns within the session.
• One-shot task: claude "add error handling to src/api/users.ts" — executes and exits.
• File-scoped task: claude --file src/api/users.ts "refactor this to use the repository pattern"
• Git workflow: claude "write a commit message for the staged changes" or claude "create a PR for this feature branch"
• /compact: Summarizes conversation history when the context window fills. Run proactively on long sessions.
• /clear: Resets context. Use between unrelated tasks to prevent context bleed.
• /help: Lists all available slash commands for the current version.

Claude Code is also available as a VS Code extension, a JetBrains plugin, a desktop app, and a web interface — the same commands and CLAUDE.md context apply across all surfaces. For IDE-specific workflow patterns, see the guide on using Claude with Cursor and Windsurf.

Using Custom API Providers (BYOK)

Claude Code's default auth points at Anthropic's API, but you can redirect it to any OpenAI-compatible backend. This is useful if you already have Bedrock or Vertex AI credits through an enterprise agreement, want to route through a LiteLLM proxy for centralized logging, or want to experiment with non-Anthropic models through the same CLI interface.

For developers interested in running Claude Code against a locally-hosted model, the walkthrough on pairing Qwen3.5 with Claude Code covers the local inference BYOK path in detail.

BYOK with LiteLLM Proxy

LiteLLM acts as an OpenAI-compatible proxy in front of any model provider. Install it, configure your providers in a YAML file, and point Claude Code at your local proxy.

# Install LiteLLM
pip install "litellm[proxy]"

# litellm_config.yaml
model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: anthropic/claude-sonnet-4-6
      api_key: sk-ant-...
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: sk-...

# Start the proxy
litellm --config litellm_config.yaml --port 4000

Then configure Claude Code to use the proxy:

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=anything
claude

Amazon Bedrock and Google Vertex AI

Claude Code supports Bedrock and Vertex AI natively via environment variables. Verify the exact variable names against the current repo source, as they may be updated across releases.

Amazon Bedrock:

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
claude

Google Vertex AI:

export CLAUDE_CODE_USE_VERTEX=1
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
export CLOUD_ML_REGION=us-east5
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
claude

When routing through Bedrock or Vertex, billing flows through your AWS or GCP account rather than Anthropic directly — useful if you have pre-committed cloud spend or need cost allocation at the team level.

Troubleshooting Common Issues

• 401 Unauthorized: Token expired or API key invalid. Run claude /logout then claude /login, or re-export ANTHROPIC_API_KEY.
• npm deprecation warning on install: Expected — the npm package is deprecated. Switch to the native installer: curl -fsSL https://claude.ai/install.sh | sh.
• "Command not found: claude" after native install: The install script may not have updated your PATH. Add ~/.local/bin (Linux) or /usr/local/bin (macOS) to your shell config, then reload: source ~/.zshrc or source ~/.bashrc.
• Context window full errors: Run /compact to summarize history, or /clear to start fresh.
• Permission denied on shell commands: The command is not in your settings.json allow list. Add it explicitly or approve interactively when Claude Code prompts.
• TypeScript build errors from source: Ensure Node.js 22+ is installed (node --version). Older Node versions may fail to compile the TypeScript source.
• LiteLLM proxy connection refused: Confirm the proxy process is running (lsof -i :4000) and that ANTHROPIC_BASE_URL matches the proxy port exactly.

Tips for Power Users: MCP Servers, GitHub Actions, and Sub-Agents

Claude Code's capabilities extend well beyond single-session coding tasks once you wire in external tools and automation.

MCP Servers: The Model Context Protocol lets Claude Code call external tools through a standardized interface — databases, APIs, web search, file systems, and more. Attach an MCP server to give Claude persistent memory across sessions or direct access to your production database with appropriate guards. For a curated starting list, see the best free open-source MCP servers. For architectural patterns around building agentic systems with MCP, MCP servers for agentic development platforms is a comprehensive reference.

GitHub Actions Integration: Run /install-github-app inside Claude Code to walk through the GitHub app setup and required secrets. Once active, mention @claude in any PR comment or issue to trigger a Claude Code run that can read context, suggest or implement fixes, and push commits directly to the branch.

Sub-Agents and Multi-Project Setups: Run multiple Claude Code instances with different CLAUDE.md contexts in parallel — useful for monorepos where different packages have different conventions and build systems. Point each instance at a subdirectory with its own CLAUDE.md and settings.json.

Claude for Open Source Program: If you maintain an active open-source project, apply at claude.com/contact-sales/claude-for-oss. Approved maintainers get Claude Max free for six months. Applications are reviewed on a rolling basis until June 30, 2026.

Conclusion

The open-source release of Claude Code is significant not because it makes the tool free to run — it doesn't — but because it makes the agent layer auditable, forkable, and extensible. You can now inspect every tool call, build on the TypeScript source, route inference to any backend you trust via BYOK or cloud provider integration, and contribute improvements back upstream.

For most developers, the native installer plus an Anthropic subscription remains the fastest path to a working setup. For teams with enterprise cloud commitments, Bedrock and Vertex AI integrations keep billing inside your existing AWS or GCP account. And for security-conscious organizations, the open-source code gives your team the visibility needed to approve Claude Code for sensitive production workflows.

Start with the native installer, drop a CLAUDE.md in your project root describing your stack and conventions, and run claude. Once you have a feel for the defaults, explore the LiteLLM BYOK path and MCP server extensions — that is where Claude Code's real leverage as an open, programmable agent starts to show.