From 061a67f9edd99ed77bd75536d78b8ee5c575e03a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 15:39:33 +0000 Subject: [PATCH 1/2] Initial plan From 5a0732d3aca3c6eb763f1721317689e05c6892f8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 15:43:26 +0000 Subject: [PATCH 2/2] docs: rewrite README.md to reflect current codebase state Agent-Logs-Url: https://github.com/Mike-Jenkins-Org/PortableCoder/sessions/9ca10a35-d512-4abd-bb3a-2262d7e54abf Co-authored-by: mjenkinsx9 <238907794+mjenkinsx9@users.noreply.github.com> --- README.md | 213 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 157 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index a760d27..e6fb823 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,218 @@ # Portable Claude Code -A portable Claude Code launcher you can copy to any Windows computer or flash drive and run without a system-wide install. +A portable [Claude Code](https://docs.anthropic.com/en/docs/claude-code) launcher you can copy to any Windows, macOS, or Linux computer — or put on a flash drive — and run without a system-wide install. ## What it does -- Launches [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI with your local filesystem accessible -- Stores OAuth credentials portably inside the repo's `state/` folder (no registry or system config pollution) -- On Windows: runs Claude Code inside a bundled QEMU Linux VM (no WSL required) -- Supports API key mode if you prefer to skip OAuth +- Launches Claude Code CLI with your project files accessible +- Stores OAuth credentials portably inside `state/auth/` — no registry writes, no system config files +- **Windows (default):** runs Claude Code inside a bundled QEMU Linux VM (no WSL required) +- **Linux / macOS:** runs Claude Code directly on the host with isolated, portable auth state +- Supports API key mode as an alternative to OAuth ## Requirements -- **Node.js** — either bundled in `runtime/node/` or installed on the host -- **Claude Code** — either installed globally (`npm install -g @anthropic-ai/claude-code`) or bundled in `runtime/` -- **Windows VM mode only**: QEMU runtime (download with `pcoder runtime bootstrap`) +| Requirement | Notes | +|---|---| +| **Node.js** | Bundled in `runtime/node/` or installed on the host | +| **Claude Code** (`claude`) | Required for host-native mode. Install with `npm install -g @anthropic-ai/claude-code` | +| **QEMU** *(Windows VM mode only)* | Downloaded automatically by `pcoder runtime bootstrap` | ## Quick Start -### First time +### 1 — Initialize (first time only) +**Windows** ```bat -REM 1. Initialize settings (creates state/settings.json) +REM Create state/settings.json with defaults scripts\pcoder setup --init -REM 2. Log in with your Anthropic account (OAuth - credentials stay portable) +REM Log in with your Anthropic account (credentials stay in state/auth/) scripts\pcoder auth login -REM 3. Check everything looks good +REM Confirm everything is ready scripts\pcoder doctor ``` -### Launch Claude Code +**Linux / macOS** +```bash +# Create state/settings.json with defaults +scripts/pcoder setup --init + +# Log in with your Anthropic account (credentials stay in state/auth/) +scripts/pcoder auth login + +# Confirm everything is ready +scripts/pcoder doctor +``` + +### 2 — Launch Claude Code +**Windows** ```bat -REM Launch in current directory +REM Launch in the current directory scripts\pcoder -REM Launch in a specific project +REM Launch in a specific project folder scripts\pcoder run --project C:\path\to\my-project -REM Pass args directly to claude +REM Pass extra arguments directly to claude scripts\pcoder -- --help +scripts\pcoder -- --resume ``` -### API key mode (skip OAuth) +**Linux / macOS** +```bash +# Launch in the current directory +scripts/pcoder -```bat -REM Switch to API key mode -scripts\pcoder setup --claude-auth api +# Launch in a specific project folder +scripts/pcoder run --project /path/to/my-project -REM Set your key before launching -set ANTHROPIC_API_KEY=sk-ant-... -scripts\pcoder +# Pass extra arguments directly to claude +scripts/pcoder -- --help ``` -## Windows: VM vs Host-Native +## Windows: VM Mode vs Host-Native Mode + +On Windows the default run mode is **`linux-portable`** — Claude Code runs inside a +self-contained QEMU Linux VM so you do not need WSL or a Windows build of Claude Code. + +### VM mode (default on Windows) -By default on Windows, Claude runs inside a bundled portable Linux VM (QEMU). This gives full Linux compatibility without requiring WSL or any host configuration. +> **Note:** Claude Code runs *inside* the VM — you do not need it installed on the Windows host. -**VM mode (default on Windows)** ```bat -REM Bootstrap the VM runtime first (one-time download) +REM One-time setup: download QEMU + Ubuntu image (~1 GB) scripts\pcoder runtime bootstrap -REM Then just run normally +REM Run normally after bootstrap scripts\pcoder ``` -**Host-native mode** (if claude is installed directly on Windows) +### Host-native mode (optional — requires claude installed on Windows) + ```bat scripts\pcoder setup --windows-mode host-native scripts\pcoder ``` -## Commands +> On Linux and macOS, the launcher always uses **host-native** execution with isolated portable +> auth state — no VM is required. + +## Authentication + +### OAuth (default) + +OAuth credentials are written to `state/auth/claude/host/` and travel with the folder. +No credentials are stored in system directories. + +```bat +REM Open browser for OAuth +scripts\pcoder auth login +REM Show current auth state +scripts\pcoder auth status +REM Remove stored credentials +scripts\pcoder auth logout +``` + +### API key mode + +```bat +REM Switch to API key mode +scripts\pcoder setup --claude-auth api + +REM Set your key each session before launching +set ANTHROPIC_API_KEY=sk-ant-... +scripts\pcoder +``` + +On Linux / macOS: +```bash +export ANTHROPIC_API_KEY=sk-ant-... +scripts/pcoder +``` + +> `ANTHROPIC_AUTH_TOKEN` is also accepted as an alias for `ANTHROPIC_API_KEY`. + +## All Commands | Command | Description | |---|---| -| `pcoder` | Launch Claude Code in current directory | +| `pcoder` | Launch Claude Code in the current directory | +| `pcoder [-- ]` | Launch and pass extra args directly to claude | | `pcoder doctor` | Check environment health | -| `pcoder setup --init` | Initialize settings | -| `pcoder setup --show` | Show current settings | -| `pcoder setup --claude-auth ` | Change auth mode | -| `pcoder setup --windows-mode ` | Change Windows run mode | -| `pcoder auth status` | Show auth status | +| `pcoder setup --init` | Initialize `state/settings.json` with defaults | +| `pcoder setup --show` | Print current settings | +| `pcoder setup --claude-auth ` | Change authentication mode | +| `pcoder setup --windows-mode ` | Change Windows run mode | +| `pcoder setup --sync-back ` | Control whether VM files sync back after a run | +| `pcoder auth status` | Show authentication status | | `pcoder auth login` | Log in via OAuth | -| `pcoder auth logout` | Log out | -| `pcoder runtime probe` | Show available runtimes | -| `pcoder runtime bootstrap` | Download Windows VM runtime (QEMU + Ubuntu) | -| `pcoder run [--project ] [--mode ] [-- ]` | Run with options | +| `pcoder auth logout` | Log out and clear stored credentials | +| `pcoder runtime probe` | Show available runtime backends | +| `pcoder runtime bootstrap [--force]` | Download Windows VM runtime (QEMU + Ubuntu) | +| `pcoder run [--project ]` | Run in a specific project directory | +| `pcoder run [--mode ]` | Override run mode for one session | +| `pcoder run [--no-sync-back]` | Skip syncing VM files back after this run | +| `pcoder run [-- ]` | Pass extra arguments directly to claude | ## File Layout ``` PortableCoder/ scripts/ - pcoder.cmd <- Windows launcher (double-click or run from cmd) - pcoder <- Linux/macOS launcher - pcoder.cjs <- Main launcher logic (Node.js) - runtime/windows/ <- Windows VM helper scripts - runtime/ - node/ <- (optional) bundled Node.js - linux/ <- VM image and SSH key (after bootstrap) - qemu/ <- QEMU binaries (after bootstrap) - state/ - settings.json <- Your settings (auto-created) - auth/ <- Portable OAuth credentials (stays with the drive) -profiles/ - profiles.json <- Anthropic profile config + pcoder.cmd <- Windows entry point (run from cmd.exe or double-click) + pcoder <- Linux / macOS entry point + pcoder.cjs <- Main launcher logic (Node.js, cross-platform) + adapters/ + catalog.json <- Tool adapter definitions (claude, pwsh, …) + runtime/ + windows/ <- Windows VM helper scripts (bootstrap, start, stop, smoke-check) + linux/ + smoke-check.sh <- Linux smoke test + runtime/ <- Runtime binaries (large files, not committed to git) + node/ <- (optional) bundled portable Node.js + qemu/ <- QEMU binaries (populated by `runtime bootstrap`) + linux/ + images/ <- Ubuntu VM image (populated by `runtime bootstrap`) + ssh/ <- Generated SSH keypair for VM access + vm-manifest.json <- VM configuration (backend, image path, acceleration policy) + cloud-init/ <- Cloud-init configuration for first-boot VM provisioning + state/ <- Runtime state (gitignored, travels with the folder) + settings.json <- Your settings (created by `setup --init`) + auth/ + claude/host/ <- Portable OAuth credentials + vm/ <- VM runtime state (PID, SSH port, logs) + tmp/ <- Temporary working files + profiles/ + profiles.json <- Environment profile definitions + defaults/ <- Default secrets policy documentation + local/ <- Local .env overrides (gitignored) + apps/ <- (reserved) local app bundles ``` +## Environment Variables + +| Variable | Purpose | +|---|---| +| `ANTHROPIC_API_KEY` | API key (api auth mode) | +| `ANTHROPIC_AUTH_TOKEN` | Alias for `ANTHROPIC_API_KEY` | +| `ANTHROPIC_BASE_URL` | Override the Anthropic API base URL | +| `PCODER_CLAUDE_CMD` | Override the path/command used to run claude | +| `PCODER_VM_SSH_TIMEOUT_SECONDS` | Max seconds to wait for VM SSH (default: 300) | +| `PCODER_VM_HOST` | VM SSH hostname (default: `127.0.0.1`) | +| `PCODER_VM_USER` | VM SSH username (default: `portable`) | +| `PCODER_VM_SSH_KEY` | Path to VM SSH private key | +| `PCODER_VM_PROJECTS_ROOT` | Remote path for synced projects (default: `/home/portable/projects`) | +| `PCODER_SSH_CMD` | Override SSH client path | +| `PCODER_SCP_CMD` | Override SCP client path | +| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | Proxy settings forwarded into the VM | + ## Portability Notes -- Copy the entire `PortableCoder/` folder to a flash drive or another machine and it works -- OAuth credentials are stored in `state/auth/` so they travel with the folder -- No registry writes, no system PATH changes, no admin rights required (VM mode may need Hyper-V or software TCG fallback) +- Copy the entire `PortableCoder/` folder to a flash drive or new machine and it works +- OAuth credentials live in `state/auth/` and travel with the folder +- No registry writes, no system PATH changes, no admin rights required +- Windows VM mode may use Hyper-V hardware acceleration (WHPX) when available, and automatically falls back to software emulation (TCG) if not +- Settings are stored in `state/settings.json` (gitignored so your personal config never gets committed)