100% local · built on QVAC SDK

A local coding agent
driven from your iPhone.

qcode reads your code, proposes changes, runs commands, and streams diffs. All inference runs on your Mac. No cloud, no API keys, no telemetry. Your code stays on your disk.

▶ watch the demo view on GitHub →
10
QVAC SDK APIs used
3
models (text, voice, vision)
0
cloud calls · API keys · trackers

01 Ship It Local · episode 01

The full walkthrough: desktop agent, iPhone takeover, voice + vision, and P2P delegated inference. Airplane mode on for the local segment. Filmed as episode one of Ship It Local, a weekly series reviewing apps built on the QVAC SDK.

6 minutes, one continuous review. Source file also available in the repo under docs/.

02 What qcode does

Local agent loop

ReAct loop with 8 tools: read, write, list, grep, bash, diff, plan, reply. Native tool calling via the SDK with Zod schemas. Multi-turn memory with a sliding window and token budget.

iPhone PWA

14 KB vanilla JS PWA, no install, no app store. Served from the Mac daemon over LAN. Voice input, camera, chat, permission approvals, model picker. All over SSE streams.

Voice (Whisper)

Tap the mic on the PWA, speak the task. Whisper Base Q8 runs on-device via the SDK. Opt-in feature, downloaded from the QVAC registry the first time you enable it.

Vision (Qwen3-VL)

Take a photo from the iPhone, send it, get back a reading of the image. Qwen3-VL 2B with its projector runs on the Mac. Paste a stack trace, hand over a whiteboard photo, point the camera at an error.

P2P delegation

Offload heavy tasks to a stronger peer over Hyperswarm. Same SDK, same agent loop. Tool execution stays on the Mac. Verified end-to-end with Qwen3 8B on a Linux peer.

Permission modes

ask (approve every write), plan-first (approve the plan, auto-run), auto-writes (trusted writes), yolo (demo mode, no prompts). Shell metacharacters are rejected; writes are sandboxed under the project root.

03 How it works

A single Express daemon on the Mac runs @qvac/sdk in-process. A capability router dispatches each prompt to the best backend: local Qwen3 1.7B for fast tasks, a P2P peer for heavy work. Tools always execute locally.

qcode architecture: iPhone PWA to your laptop daemon to local SDK and optional remote peer qcode · local refactor loop.ts plan: split runAgentLoop… ▸ read_file Your phone Safari PWA · 14 KB Express daemon · capability router @qvac/sdk Qwen3 1.7B (primary) Whisper + Qwen3-VL tools (local) read · write · grep · bash diff · plan · list_dir session store · SSE channels · shared-secret auth Your laptop macOS · Linux · Windows (Node 22+) Qwen3 8B stronger model via delegate peer-provider.mjs Remote peer VPS · home server · hotspot mesh HTTP + SSE Hyperswarm
PWA to daemon: HTTP + Server-Sent Events. Auth via shared secret in a header.
Daemon to SDK: in-process. No subprocesses, no HTTP loopback. loadModel, completion({ tools }), toolCallStream.
Daemon to peer: loadModel({ delegate: { topic, providerPublicKey } }). The SDK forwards the request over Hyperswarm. Tools still resolve locally.

04 SDK features used

SDK surface
Role in qcode
loadModel (primary)
Loads Qwen3 1.7B from the SDK registry on boot.
completion (streaming)
Consumes tokenStream for assistant text.
completion (tools)
Passes Zod schemas as ToolInput[]. SDK injects tools via Qwen3's native chat template.
toolCallStream
Reads structured { name, arguments } tool calls parsed by the SDK.
cancel
Stop button on the PWA propagates an AbortSignal.
loadModel (delegate)
Routes model loading to a P2P peer over Hyperswarm.
startQVACProvider
Runs on the peer machine. Accepts delegated loadModel + completion requests.
loadModel (Whisper)
Loads WHISPER_BASE_Q8_0 on demand when voice is enabled.
loadModel (Vision)
Loads QWEN3VL_2B_MULTIMODAL_Q4_K + projector on demand when vision is enabled.
downloadAsset
Downloads feature weights without initializing (used for projector models).
Model registry
QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M constants. SDK caches under ~/.qvac/models/.

Wider stack

TypeScript (strict) Node 22+ ESM @qvac/sdk v0.8.3 Express Zod vanilla JS PWA Inconsolata mono Hyperswarm SSE

Fully local. Fully air-gapped.

qcode was built to show what the QVAC SDK unlocks: inference, voice, vision, and delegated compute with no external services. The demo was recorded in airplane mode. No API keys, no cloud, no trackers. Your code never leaves your disk.

  • Models cached under ~/.qvac/models/
  • Shared-secret auth, timing-safe comparison
  • Writes sandboxed under $HOME
  • Shell metacharacter allowlist bypass blocked

05 Current limitations + what's next

Model ceiling on complex work

Qwen3 1.7B handles single-file edits, reads, and searches reliably. Multi-file refactors benefit from peer delegation to Qwen3 8B.

mitigated by P2P

Same-NAT P2P hairpin

When Mac and peer share a home router, Hyperswarm's hole-punch fails on routers without NAT hairpin. Workarounds: mobile hotspot, VPS peer, or Wireguard with a public relay.

network limit

LAN-scope auth

Shared-secret header is fine on a trusted LAN. Public-internet deployment would need TLS + stronger auth, intentionally out of scope for the local-first demo.

design choice

8 GB RAM budget

Context window capped at 8192 tokens with sliding-window + token-budget management. Fine for most coding tasks, but large refactors are better delegated.

hardware

Next features

→ Codebase embeddings for semantic search across files (using the SDK's embed API).
→ Multi-peer routing: use multiple delegated peers with different specializations.
→ Expo native iOS wrapper for push notifications and background audio capture.
→ RAG workspace for long-lived project context.
→ TTS reply for hands-free voice mode (SDK already supports textToSpeech).
built by

Thomas Blanc

Solo engineer, ex-SwissBorg and Galactica, now co-founder at Mithril. Built qcode as a submission for Tether's QVAC take-home, aiming to show what the SDK feels like when you push it across all of its modalities (text, voice, vision, P2P) with constrained hardware.

GitHub toblanc34@gmail.com

Read the code, run it, break it, improve it.

Everything is in the repo. Signed commits. MIT licence.

thomasblc/qcode rewatch demo