code-stick

Plug in a USB. Get an offline AI coding agent on any laptop. One stick. Six targets — Windows (x64 + ARM64), macOS (Apple Silicon + Intel), Linux (x64 + ARM64). Zero install on the host.

npx code-stick install

Why

You want an AI coding agent that works on:

• Airgapped or restricted machines — banks, defense, hospitals, lab VMs.
• Shared / borrowed laptops — internships, school computers, client sites.
• Spotty wifi — flights, trains, cafes, conferences.
• Privacy-sensitive code — closed-source clients, NDAs, personal projects.

Cloud agents won't work. Installing Ollama + a 5 GB model on every machine you touch won't either. code-stick is the in-between: install once on a USB, then run the agent from the stick on whatever laptop is in front of you. Host stays clean.

Under the hood it's opencode (terminal coding agent) talking to Ollama (local model runner), both pre-built for every target, both serving from the USB on 127.0.0.1:11434. Quit the agent, the Ollama process dies, the host has no residue.

Install + first launch

npx code-stick install            # auto-detects USB; pick a model interactively

Plug the stick into any supported machine, double-click the launcher for that OS:

• start-windows.bat
• start-mac.command
• start-linux.sh

opencode runs in the terminal talking to a USB-local Ollama on 127.0.0.1:11434. Quitting opencode kills the Ollama process. Nothing is left behind on the host.

Models

The recommended default is Qwen2.5-Coder 7B — fits a 32 GB stick, runs on 8 GB RAM, best all-rounder for code. Other curated options scale up to 32B for serious refactors on larger sticks.

| Model | Size | Stick / RAM | Best for | | ------------------- | ------- | -------------- | --------------------------------- | | Qwen2.5-Coder 7B ⭐ | ~4.7 GB | 32 GB / 8 GB | All-rounder for coding | | Qwen2.5-Coder 14B | ~9.0 GB | 64 GB / 16 GB | Stronger reasoning + multi-file | | Qwen2.5-Coder 32B | ~20 GB | 128 GB / 32 GB | Top-tier OSS coder, near-frontier | | Phi-3 Mini 3.8B | ~2.2 GB | 32 GB / 4 GB | Lightweight, low-spec hardware |

Full curated list, BYO Ollama tag instructions, and per-model context windows: docs/MODELS.md.

⚠ USB 2.0 sticks are unusable for models >7B. ~30 MB/s read means a 20 GB model takes ~11 minutes just to warm up. Use USB 3.0 or better for anything bigger than 7B.

⚠ First-prompt latency on large models can be 30–90 s — Ollama is mmap'ing the weights off the USB. Subsequent prompts are fast once the OS page-caches the blob.

⚠ macOS first-launch: Gatekeeper will block the unsigned launcher (notarization is on the roadmap). Right-click start-mac.command → Open → Open. Details: docs/TROUBLESHOOTING.md.

Commands

| Command | Description | | ---------------------------------- | -------------------------------------------------------------------------- | | code-stick install | Set up code-stick on a USB | | code-stick start | Start opencode + Ollama from a USB | | code-stick status | Show what's installed | | code-stick doctor | Live audit (port + Ollama + opencode + model store) | | code-stick prune | Run ollama prune on the USB model store to reclaim orphaned blobs | | code-stick update | Refresh launcher scripts and manifest timestamp | | code-stick upgrade-engine | Re-download Ollama + opencode without nuking the model store | | code-stick add-model [id] | Pull another model onto the stick | | code-stick remove-model [id] | Remove a model from the stick | | code-stick add-targets [list] | Add OS targets to a stick installed with --targets (restore portability) | | code-stick uninstall | Wipe code-stick from the stick |

Full flag reference, install modes (Fast vs Direct), and --targets trimming: docs/COMMANDS.md.

Requirements

• USB free space: 8+ GB only with --targets host (see docs/STORAGE.md); 16+ GB for full portability with small models; 32+ GB (recommended default + Qwen 7B); 64+ GB (medium), 128+ GB (large).
• USB format: exFAT or NTFS. FAT32's 4 GB file limit blocks models above ~4 GB; the installer detects FAT32 and bails clearly.
• Install machine: Node 20+. Target machines need nothing.
• Target laptop RAM: rule of thumb is model size × 1.2. See the per-model column in docs/MODELS.md.

Status

v0.2.1 — opencode v1.x, per-model num_ctx bake. Full install flow on Windows (x64 + ARM64), macOS, Linux (x64 + ARM64) — tested manually per target. Surface Pro / Snapdragon X laptops boot natively (ARM64) with x64-via-Prism fallback if only the x64 target is staged. Docker-based Linux smoke test in CI. No telemetry, no background HTTP. Bug reports are local-only and redacted before write.

Known gaps: macOS not yet notarized, no Windows/macOS CI runners.

File an issue or open a PR if you hit anything: github.com/MuhammadUsmanGM/code-stick/issues.

Documentation

• docs/STORAGE.md — USB sizing, default 6-target download (~5–7 GB binaries), 8 GB + --targets host
• docs/TROUBLESHOOTING.md — hallucinations, Gatekeeper, MAX_PATH, port conflicts, bug reports
• docs/MODELS.md — full model catalog, BYO Ollama tags, quantization, context windows
• docs/COMMANDS.md — every subcommand and flag, Fast vs Direct, --targets
• docs/ARCHITECTURE.md — stick layout, runtime behavior, process isolation
• docs/SECURITY.md — trust model, threat boundaries
• docs/TRUST.md — supply-chain provenance

Development

npm install
npm run typecheck     # tsc --noEmit
npm test              # vitest run (unit + launcher snapshot tests)
npm run build         # tsup → dist/cli.js
npm run smoke:docker  # full end-to-end install + launch in Linux Docker

License

MIT — Muhammad Usman (github.com/MuhammadUsmanGM)