Merge branch 'main' into gimli/fix-linux-portability

Author: mjenkinsx9

AGENTS.md

@@ -1,133 +1,117 @@
-# Portable Coder
+# Portable Claude Code
 
-Portable multi-provider coding CLI launcher with harness-first planning.
+A portable Claude Code launcher you can copy to any Windows computer or flash drive and run without a system-wide install.
 
-**Goal:** Run Claude Code and other AI coding CLIs from a portable folder (e.g., flash drive) without requiring installation on the host machine, while maintaining isolated auth state and the ability to access files on the local machine.
+## What it does
 
-## Current Status
-- ✅ **Cross-platform support:** Works on Linux, macOS, and Windows
-- ✅ **Portable auth state:** Auth credentials stored in portable folder, not host home directory
-- ✅ **Supported tools:** Codex CLI, Claude Code
-- Planning control-plane is established (`AGENTS.md`, `HARNESS_CHECKLIST.md`, `docs/*`)
-- Active plan: `docs/exec-plans/active/EP-001-portable-coder-foundation-and-multi-provider-mvp.md`
+- 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
 
-## Platform-Specific Behavior
+## Requirements
 
-| Platform | Default Mode | Behavior |
-|----------|-------------|----------|
-| **Linux** | `host-native` | Runs tools directly with portable auth isolation |
-| **macOS** | `host-native` | Runs tools directly with portable auth isolation |
-| **Windows** | `linux-portable` | Runs tools in bundled QEMU VM with portable auth |
-
-On **Linux/macOS**, the `--mode linux-portable` flag runs tools in "portable-native" mode, which uses isolated auth state in `state/auth/<tool>/host/` but runs the tool directly on the host. This provides true portability without requiring a VM.
+- **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`)
 
 ## Quick Start
 
-### Linux / macOS
-```bash
-# 1. Initialize settings
-./scripts/pcoder setup --init
+### First time
 
-# 2. Verify setup
-./scripts/pcoder doctor
+```bat
+REM 1. Initialize settings (creates state/settings.json)
+scripts\pcoder setup --init
 
-# 3. Run a tool (uses portable auth isolation by default)
-./scripts/pcoder run codex -- "your prompt here"
-./scripts/pcoder run claude -- "your prompt here"
-```
+REM 2. Log in with your Anthropic account (OAuth - credentials stay portable)
+scripts\pcoder auth login
 
-### Windows
-1. Bootstrap runtime payload: `scripts/runtime/windows/bootstrap-runtime.cmd`
-   - Optional launcher path: `scripts/pcoder runtime bootstrap`
-   - Optional URL overrides: `PCODER_QEMU_INSTALLER_URL`, `PCODER_QEMU_SHA512_URL`, `PCODER_UBUNTU_IMAGE_URL`
-2. Run onboarding once: `scripts/pcoder setup --init`
-3. Choose auth modes as needed:
-   - OAuth: `scripts/pcoder setup --codex-auth oauth --claude-auth oauth`
-   - API keys: `scripts/pcoder setup --codex-auth api --claude-auth api`
-4. Inject required env vars only for API mode (`OPENAI_API_KEY` and/or `ANTHROPIC_AUTH_TOKEN`)
-5. Run `scripts/pcoder doctor`
-6. Launch in VM mode: `scripts/pcoder run <tool> --mode linux-portable`
-7. Use `--no-sync-back` if you do not want VM changes copied back automatically
+REM 3. Check everything looks good
+scripts\pcoder doctor
+```
 
-On Windows, `pcoder run` defaults to `--mode linux-portable`.
+### Launch Claude Code
 
-Auth management:
-- `scripts/pcoder auth status`
-- `scripts/pcoder auth login codex`
-- `scripts/pcoder auth login claude`
-- `scripts/pcoder auth logout codex`
-- `scripts/pcoder auth logout claude`
+```bat
+REM Launch in current directory
+scripts\pcoder
 
-Windows smoke test:
-- `scripts/runtime/windows/smoke-check.cmd`
+REM Launch in a specific project
+scripts\pcoder run --project C:\path\to\my-project
 
-## CI
-- GitHub Actions workflow: `.github/workflows/ci.yml`
-- Runner target: Blacksmith runner label `blacksmith-2vcpu-ubuntu-2404`
+REM Pass args directly to claude
+scripts\pcoder -- --help
+```
 
-## Claude PR Runner
-- Workflow: `.github/workflows/claude-pr-runner.yml`
-- Trigger: mention `@claude` in PR comments/reviews (or run manually via `workflow_dispatch`)
-- Runner target: Blacksmith runner label `blacksmith-2vcpu-ubuntu-2404`
-- Configure one auth secret:
-  - `ANTHROPIC_API_KEY` (API key mode), or
-  - `CLAUDE_CODE_OAUTH_TOKEN` (OAuth mode)
+### API key mode (skip OAuth)
 
-Supported tool IDs:
-- `codex`
-- `claude`
+```bat
+REM Switch to API key mode
+scripts\pcoder setup --claude-auth api
 
-## How It Works
+REM Set your key before launching
+set ANTHROPIC_API_KEY=sk-ant-...
+scripts\pcoder
+```
 
-Portable Coder provides **portable auth isolation** - running AI coding tools with their configuration and credentials stored in the portable folder rather than the host's home directory.
+## Windows: VM vs Host-Native
 
-### Key Concepts
+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.
 
-- **Portable Auth State**: When using OAuth mode, auth tokens are stored in `state/auth/<tool>/host/home/` instead of `~/.claude` or `~/.openai`. This allows you to copy the portable folder to another machine and remain authenticated.
+**VM mode (default on Windows)**
+```bat
+REM Bootstrap the VM runtime first (one-time download)
+scripts\pcoder runtime bootstrap
 
-- **Execution Modes**:
-  - `host-native`: Runs the tool directly on the host using the portable auth state
-  - `linux-portable`: On Windows, runs the tool inside a bundled QEMU VM for full Linux isolation; on Linux/macOS, falls back to portable-native execution
+REM Then just run normally
+scripts\pcoder
+```
 
-- **No Secrets in Bundle**: API keys are never stored in the portable folder. In API mode, keys are injected via environment variables at runtime.
+**Host-native mode** (if claude is installed directly on Windows)
+```bat
+scripts\pcoder setup --windows-mode host-native
+scripts\pcoder
+```
 
-### Directory Structure
+## Commands
+
+| Command | Description |
+|---|---|
+| `pcoder` | Launch Claude Code in current directory |
+| `pcoder doctor` | Check environment health |
+| `pcoder setup --init` | Initialize settings |
+| `pcoder setup --show` | Show current settings |
+| `pcoder setup --claude-auth <oauth|api>` | Change auth mode |
+| `pcoder setup --windows-mode <linux-portable|host-native>` | Change Windows run mode |
+| `pcoder auth status` | Show auth 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 <path>] [--mode <mode>] [-- <claude args>]` | Run with options |
+
+## File Layout
 
 ```
 PortableCoder/
-├── apps/              # Provider tool wrappers and configs
-├── profiles/          # User/provider profiles and model routing
-│   ├── defaults/      # Default profile templates
-│   └── profiles.json  # Profile definitions
-├── runtime/           # Bundled dependencies (QEMU, Linux VM on Windows)
-│   └── linux/        # Linux runtime assets (VM image, cloud-init)
-├── scripts/          # Launchers and scripts
-│   ├── adapters/     # Tool adapter catalog
-│   ├── pcoder        # Main POSIX launcher
-│   ├── pcoder.cmd    # Main Windows launcher
-│   ├── pcoder.cjs    # Core launcher logic
-│   └── runtime/      # Platform-specific runtime scripts
-├── state/            # Local state (gitignored - portable!)
-│   ├── auth/         # Isolated auth credentials
-│   │   ├── claude/host/home/  # Claude OAuth state
-│   │   └── codex/host/home/    # Codex OAuth state
-│   ├── active-profile.txt
-│   └── settings.json
-└── docs/             # Planning and governance artifacts
+  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
 ```
 
-## Testing
-
-Run the smoke test on Linux/macOS:
-```bash
-./scripts/pcoder doctor
-./scripts/pcoder run codex --mode linux-portable -- --version
-./scripts/pcoder run claude --mode linux-portable -- --version
-```
+## Portability Notes
 
-## Planning Workflow
-Read in order:
-1. `AGENTS.md`
-2. `HARNESS_CHECKLIST.md`
-3. `docs/PLANS.md`
-4. active ExecPlan in `docs/exec-plans/active/`
+- 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)