# Wheelie quickstart Agent docs index: /llms.txt This is the launch-preview, one-afternoon path: install `wheelie`, start from an existing checkout or a publicly cloneable GitHub repo, bring the coding harness you already trust, and ask it to turn one issue into a reviewable diff with typed work/source/validation/change state. Use the installed CLI as the normal automation surface for coding agents, local harnesses, scripts, source/candidate/change operations, validation, submit, and watch. Wheelie over SSH is the zero-install human onboarding/demo/recovery path and a constrained read/status fallback, not the preferred agent-control surface. Some steps are allowlist-, adapter-, or preview-gated; they must report `support_state`, `reason`, and `next_action` instead of pretending the full live onboarding-to-PR loop is generally available. The goal is not “migrate your whole SDLC today.” The goal is a small, useful loop a technical founder can try in an afternoon: verify the CLI, connect only the access needed for one repo/task, hand a working copy to Pi/Claude/Codex when support is present, review the diff, run the smallest validation lane that answers the change, and keep submit/watch/checkpoint as typed support-state branches rather than broad availability claims. The current public claim is intentionally narrow: clean public stable exposes harness commands as typed support probes until a richer Wheelie package or project adapter provides the actual projection installer. Claude Code and Codex remain projection/BYO paths, and Flue is deferred adapter research, not a public launch-picker or preinstalled-harness claim. Do not treat hosted model access, managed-workspace materialization, agent-run start, validation from a clean non-checkout environment, provider-backed PR submit/watch, checkpoint writes, strong workspace durability, public named-workspace lifecycle/durability timing, private/non-public GitHub repository attach, self-serve billing, harness projection mutation from clean public stable, or broad performance/capacity/pricing/prod-parity numbers as green. Strong workspace durability is out of this launch scope: source snapshots are authoritative for source truth and project-memory summaries are authoritative only for remembered same-project context; VM/session continuity across reboot, stop/start, base-image update, host loss, reconnect, or partial-run recovery stays preview/adapter-gated until Wheelie returns live named-workspace receipts. Do not publish warm-resume/cold-boot/first-setup p50/p95/p99, same-session reconnect, preview/share URL continuity, process/log continuity, cleanup SLO, host-loss, or dirty partial-run auto-recovery claims until a public/customer-facing named-workspace cohort supports them. Private-preview billing is manual invoice or contract only; see [private-preview billing](./billing.md). Private/non-public GitHub repos remain launch-deferred until Wheelie returns a mediated source-provider adapter or allowlist receipt for the selected repo. Broad performance/capacity/pricing/prod-parity claims stay outside the next public launch scope; only narrow, bounded staging proof-wave facts may be cited with their stated limits. Wheelie should never ask you to paste raw provider tokens, cookies, SSH keys, private transcripts, source dumps, or secrets into prompts, command arguments, logs, receipts, or shared artifacts. For model/API keys and developer secrets, read the [BYOK and secrets guide](./byok-secrets.md) and check whether the selected path reports mediated, short-lived, or raw env/file projection. For private and other non-public GitHub repositories, read [Private and non-public GitHub repositories](./private-repos.md); the launch flow below intentionally uses a public sample repo. ## One-afternoon wedge Use this sequence when you want the shortest honest path to value: 1. Choose one small issue in an existing checkout or a public GitHub repo. 2. Run Wheelie status commands to label auth, source, harness, validation, and resource support. 3. Bring your own harness if clean public stable reports `requires_adapter` for projection install; do not wait for a one-click managed harness unless the command returns a live receipt. 4. Produce a reviewable working-copy diff and validation/TAP evidence for that one issue. 5. Stop or ask support when private repos, hosted workspaces, model credentials, submit/watch, checkpoint stores, or capacity return `allowlist`, `requires_adapter`, `preview`, or `unsupported`. ## Prerequisites - macOS or Linux on `darwin/arm64`, `darwin/amd64`, `linux/arm64`, or `linux/amd64`. - A Wheelie account with access to the repository you want to work on. - A GitHub connection or another supported source adapter for that repository. - A supported model credential mode for the harness you plan to use; clean public installs may report `requires_adapter` until a model/project adapter is attached. BYOK credentials are encrypted/write-only, but some launch paths use explicitly labeled raw env/file projection into trusted single-user workspaces. - Enough managed-workspace capacity for the requested profile; clean public installs may report `allowlist`, `requires_adapter`, or `capacity_limited` before provisioning. ## 1. Install Wheelie If you first paired or authenticated through `ssh wheelie.dev`, use that as the human zero-install bridge, then install the local CLI before handing work to an agent or script. ```bash curl -fsSL https://get.wheelie.dev | sh export PATH="$HOME/.wheelie/bin:$PATH" wheelie version --json wheelie doctor --json ``` Expected `wheelie version --json` shape: ```json { "schema_version": "wheelie_version/v1", "version": "v2026.05.14.1", "channel": "stable", "artifact_digest": "sha256:...", "update": { "status": "current", "update_available": false } } ``` Expected `wheelie doctor --json` shape: ```json { "schema_version": "wheelie_doctor/v1", "success": true, "checks": [ { "id": "command_projection", "status": "passed" } ] } ``` If `wheelie` is not found in a fresh shell, re-run the `export PATH=...` line or add `$HOME/.wheelie/bin` to your shell profile. ## 2. Sign in and connect integrations ```bash wheelie auth login wheelie auth status --json wheelie integration connect github --repo octocat/Hello-World --json wheelie source status --repo octocat/Hello-World --json wheelie models status --credential-mode subscription --json wheelie models list --credential-mode subscription --json wheelie auth login --provider ``` `wheelie models status` is a native taxonomy/posture check; `models list` may return `requires_adapter` until a model/project adapter is attached. See [Command taxonomy](./command-taxonomy.md) for the `app` / `instant` / `agent` / `agent-run` / `models` boundary. ### Preview access During the launch preview, clean public installs may be allowlisted before they can use browser/device auth or the approved GitHub sample-repo adapter path. In that case the commands return `support_state: "allowlist"`, `reason: "preview_access_required"`, and a `request_url` instead of asking for private endpoints, raw tokens, or local provider credentials. Expected unauthenticated status before login: ```json { "schemaVersion": "wheelie_auth_status/v1", "authenticated": false, "api_url": "", "credential_path": ".../wheelie/auth.json" } ``` Expected after login when access is enabled: `authenticated: true`, the signed-in account, expiry times, and credential-storage metadata. Raw access tokens are not printed. Expected launch-preview auth gate: ```json { "schema_version": "wheelie_auth_access_gate/v1", "support_state": "allowlist", "reason": "preview_access_required", "request_url": "https://wheelie.dev/docs/wheelie/quickstart.md#preview-access" } ``` If a clean install has not attached the GitHub integration adapter yet, account commands return the same preview gate instead of asking for a raw token: ```json { "schema_version": "wheelie_public_command_probe/v1", "command_family": "integration", "support_state": "allowlist", "reason": "preview_access_required", "sample_repo": "octocat/Hello-World", "request_url": "https://wheelie.dev/docs/wheelie/quickstart.md#preview-access" } ``` `wheelie integration connect github --repo ...` verifies the Wheelie-side repo grant. The follow-up `wheelie source status --repo ... --json` is the source materialization check. The launch quickstart uses `octocat/Hello-World` because stable can clone public GitHub repos directly without a provider CLI session, raw GitHub token, local provider credentials, or operator credentials. Private and other non-public GitHub repos remain out of the clean public launch path until a mediated Wheelie source-provider adapter/allowlist path is attached for the selected repo; if you intentionally select a private or non-public repo, Wheelie must stop with `source_provider_adapter_required` / `requires_adapter` and the safe next action to use a public repo or attach the mediated adapter. The dedicated [private/non-public GitHub repo guide](./private-repos.md) has the exact support wording and unsupported shortcuts. Model catalog and credential commands are also typed gates in the public stable bootstrap until a richer Wheelie model/project adapter is attached: ```json { "schema_version": "wheelie_public_command_probe/v1", "command_family": "models", "operation": "list", "support_state": "requires_adapter", "reason": "project_adapter_required", "next_action": "Attach an authenticated project adapter or run from an authorized Wheelie working copy." } ``` ## 3. Install the harness projection Pick a supported harness you already use. In clean public stable, harness commands are typed probes: they do not mutate files until a richer Wheelie package or project adapter is attached. The projection itself is token-free instructions plus optional harness-specific files, and it does not require a source checkout once the installer path is available. | Harness | Launch-preview boundary | | --- | --- | | Pi | Clean public stable reports `requires_adapter`; richer packages/project adapters own the actual projection install/status implementation. | | Claude Code | Projection/BYO path after a richer package or project adapter is attached; not preinstalled or one-click managed. | | Codex | Projection/BYO path after a richer package or project adapter is attached; not preinstalled or one-click managed. | | Flue | Deferred; no public `wheelie harness install flue` path or managed launch-picker claim. | Clean public stable probe: ```bash wheelie harness install pi --dry-run --json wheelie harness status pi --json ``` Expected clean stable output: ```json { "schema_version": "wheelie_public_command_probe/v1", "command_family": "harness", "operation": "install", "support_state": "requires_adapter", "reason": "project_adapter_required", "implemented_in_clean_install": false, "next_action": "Attach an authenticated project adapter or run from an authorized Wheelie working copy." } ``` When a richer package or project adapter reports harness support, it may return a real plan/status such as: ```json { "schema_version": "wheelie_harness_install_plan/v1", "harnesses": ["pi"], "dry_run": true, "token_free": true, "requires_source_checkout": false, "files": [ { "kind": "instruction", "operation": "create", "summary": "file will be created" }, { "kind": "skill", "operation": "create", "summary": "file will be created" } ], "next_actions": ["Rerun the same command with --apply to write the planned managed projection files."] } ``` ## 4. Start your BYO harness and ask it to use Wheelie Start Pi, Claude Code, or Codex the way you normally do, ideally from the existing checkout you want to change. If `wheelie harness install ...` reports `requires_adapter`, treat that as a truthful clean-stable boundary and use the BYO harness path instead of assuming Wheelie installed or launched it. Instruct the harness to call the local `wheelie` CLI, not to learn the Wheelie SSH protocol, except for explicit quick read/status checks in constrained environments. Then give it a short instruction: ```text Use Wheelie for this coding task. Start with `wheelie doctor --json`, `wheelie auth status --json`, and `wheelie context pack --purpose coding --level startup --json`. Create or load the work item, use Wheelie working-copy/source commands for bounded source inspection, run Wheelie validation, capture/publish the candidate snapshot, and checkpoint the handoff. ``` The harness projection tells agents to prefer Wheelie refs such as `wheelie://work-items/...`, `wheelie://working-copies/...`, `wheelie://context-packs/...`, validation/evidence refs, and checkpoint refs. Provider URLs, branch names, local paths, process IDs, and raw terminal logs are metadata only. ## 5. Get fast startup context ```bash wheelie context pack --purpose coding --level startup --json ``` Expected clean-or-partial output: ```json { "schema_version": "wheelie_context_pack/v1", "purpose": "coding", "level": "startup", "state": "ready", "support_state": { "status": "ready", "reason_codes": [], "next_actions": [] }, "sections": { "auth_support_state": { "state": "ready" }, "source_context": { "state": "ready" }, "validation_context": { "state": "partial" } } } ``` If you are not signed in yet, the same command can still return bounded local/source context with `state: "timeout_fallback"` or `support_state.status: "requires_auth"` and a `next_actions` command such as `wheelie auth login`. Latency expectation: startup context should be cheap and bounded. The harness should call startup context first, then fetch deeper context only when needed: ```bash wheelie context pack --purpose coding --work wheelie://work-items/ --json wheelie artifacts search --project --query "validation evidence" --json ``` If startup context feels slow, run: ```bash wheelie auth status --json wheelie resources status --json wheelie context pack --purpose coding --level startup --json ``` Look for `state`, `support_state.reason_codes`, `latency`, and `next_actions`. Slow or partial context should degrade to typed refs and next actions, not unbounded prompt stuffing. ## 6. Create work and hand it to a working copy Work-item creation is part of the native local/hosted contract. Opening a working copy is a live source-adapter handoff: in launch preview it can succeed for an approved repo/account, reopen an existing authorized checkout, or return `allowlist`, `requires_adapter`, `not_authenticated`, or a repo-binding error with a safe next action. For private/non-public GitHub repos, `source_provider_adapter_required` with `support_state: "requires_adapter"` is a safe stop condition until the selected repo has a mediated adapter or allowlist receipt. ```bash wheelie work create --title "Update the README greeting" --json wheelie work open-working-copy wheelie://work-items/ --repo / --launch pi --json ``` Expected work item output: ```json { "schema_version": "wheelie_work_item_create_result/v1", "work_graph_ref": "wheelie://work-graphs/local-bootstrap", "created": true, "work_item": { "work_item_ref": "wheelie://work-items/wi_...", "state": "open", "support_state": "local" }, "next_action": "wheelie work open-working-copy wheelie://work-items/wi_... --repo / --launch pi --json" } ``` Expected working-copy handoff output when authenticated source access and a supported adapter are available but no harness session receipt is emitted: ```json { "schema_version": "wheelie_work_open_working_copy_result/v1", "work_graph_ref": "wheelie://work-graphs/local-bootstrap", "work_item": { "work_item_ref": "wheelie://work-items/wi_..." }, "working_copy": { "working_copy_id": "wc_...", "projection_path": "/path/to/working-copy" }, "launch": "pi", "agent_session": null, "support_state": "requires_adapter", "reason": "harness_launch_adapter_required", "next_action": "cd /path/to/working-copy; install or attach the pi harness when its status command returns a session/projection receipt, or rerun with --launch none for working-copy handoff only." } ``` The bootstrap WorkGraph store is local and durable under the Wheelie state directory, so a clean profile can create, read, list/search, comment/progress, state-transition, relate/block, watch/frontier, and export work items without a third-party tracker token. Provider aliases are imported projections only; if an alias is absent, expect `support_state: "optional_adapter_absent"` rather than a prompt to configure an external tracker. `open-working-copy` then asks the supported source adapter to materialize or reopen the authorized working copy; in clean public bootstrap, `--launch pi` is a working-copy handoff until the result includes a non-null `agent_session` / projection receipt. The stable lower-level source fallback is `wheelie working-copy create / --name --open --json`, followed by `wheelie work progress wheelie://work-items/ --json` or `wheelie work comment wheelie://work-items/ --json` to connect the handoff in task history. Do not use lower-level `working-copy create --work-item` or `--launch` flags unless `wheelie working-copy --help` in the installed stable build lists them. If source auth, preview access, adapter support, public cloneability, private-repo mediation, harness launch support, or repo binding is missing, working-copy commands fail closed with typed `allowlist`, `requires_adapter`, `source_provider_adapter_required`, `not_authenticated`, `source_repo_forbidden`, or repo-mismatch errors; do not bypass that by pasting raw provider tokens. ## 7. Validate, submit, watch, and checkpoint Inside an available working copy, ask the harness to make the change, then use Wheelie for TAP validation, evidence, and lifecycle state. Local Git validation is launch-supported only after the working copy is materialized; from a clean public environment before source attach it must report `requires_adapter` / `project_validation_catalog_unavailable`. Provider-backed change status, submit/watch, and checkpoint writes need the matching change/checkpoint adapters and can report `requires_adapter` or `preview` in a clean package projection: ```bash wheelie validation plan --json wheelie validation run --only local-git-working-copy-smoke --json wheelie validation status --change --json wheelie change status --change --json wheelie submit --change --dry-run --json # After reviewing the admission preview and any policy/human gates: wheelie submit --change --apply --json wheelie watch --change --cursor --max-wait-secs 900 --ndjson wheelie checkpoint create --message "ready for handoff" --work-item wheelie://work-items/ --context-file handoff.md --json ``` Expected local Git validation plan shape inside a checkout: ```json { "schema_version": "wheelie_validation_plan/v1", "support_state": "available", "reason": "local_validation_catalog_ready", "lanes": [ {"id": "local-git-working-copy-smoke", "receipt_schema": "wheelie_validation_receipt/v1"} ] } ``` Expected adapter-backed path: validation receipts/evidence refs, a change ref, resumable watch cursors, and a checkpoint or handoff artifact when the matching stores are attached. Large logs should be bounded snippets or artifact handles. If the adapter is missing, do not claim submit/watch is live; branch on the typed support state. ## 8. Check budget, resource, and cleanup state ```bash wheelie resources status --json wheelie working-copy gc --dry-run --json ``` Expected output includes resource pressure, active leases, capacity or budget blockers, and cleanup candidates when a working-copy/source adapter is attached. To remove one clean registered working copy, run `wheelie working-copy delete --dry-run --json` and apply only after it reports `can_delete: true`; successful apply returns a typed delete receipt. Broad GC apply can still return `requires_adapter` and a safe `next_action`. Spendful operations should expose cost/capacity state before they run. ## What Wheelie provides to your harness Wheelie gives the harness bounded, typed context: - auth/support state and missing-grant next actions; - work item, work graph, assignee/owner, event cursor, and checkpoint refs; - working-copy/source status, changed files, bounded diffs, and candidate snapshot refs; - validation/TAP plans, run receipts, evidence refs, failed-snippet handles, and change status; - resource/budget posture and spend blockers; - privacy labels and omitted-content reasons for raw source, logs, provider URLs, tokens, and transcripts. Wheelie writes back typed lifecycle state when the matching store or adapter is attached: work events, progress comments, source capture/publish receipts, validation/evidence receipts, submit/watch state, resource receipts, and checkpoints. It should not write back raw chain-of-thought, raw secrets, or unbounded terminal logs. ## Troubleshooting Start with typed JSON/NDJSON receipts and share only safe support-bundle fields. The detailed launch support runbook is [Support and friendly error states](./support.md). | Symptom | What you will see | Safe next action | | --- | --- | --- | | Not signed in | `authenticated: false` or `support_state.status: "requires_auth"` | Run `wheelie auth login`, then `wheelie auth status --json`. | | Missing harness grant | `requires_grant`, `wrong_scope`, or a failed `agent-grant verify` | For common coding agents run `wheelie auth grant-agent trusted-cli --repo / --scope harness:coding --json`; for submit-capable agents use `--scope harness:submit-watch`. | | No capacity / queued too long | `reason: "capacity_limited"`, `support_state: "retry_later"` or `"approval_required"`, and possibly `retry_after_seconds` | Retry only when the receipt gives a bounded retry; otherwise wait, downgrade/defer, or ask support before changing spend/profile. | | Provider key invalid or rate-limited | `credential_invalid`, `credential_revoked`, `provider_rate_limited`, `requires_auth`, or `retry_later` | Reconnect/rotate the provider key or wait for `retry_after_seconds`; do not paste raw keys into prompts, argv, logs, or support. | | Repo/source auth missing | `source_provider_auth_required`, `agent_grant_missing`, `repo_not_authorized`, `source_provider_adapter_required`, or `requires_adapter` | Grant through Wheelie auth, use a supported public repo, or attach the mediated source adapter; do not bypass with raw provider tokens. For private/non-public GitHub repos, follow [the private repo guide](./private-repos.md). | | Validation failed/missing/stale | `validation_failed`, `missing_evidence`, `evidence_stale`, `rerun_required`, or wrong-candidate evidence | Rerun the focused validation lane for the same candidate when safe; ask before spendful lanes or acceptance-shaped changes. | | PR/change creation failed | `change_not_published`, `pr_mutation_failed`, `provider_backpressure`, `blocked`, or `requires_adapter` | Capture/publish a clean working copy or retry after backpressure; ask before provider-visible publication/conflict resolution. | | Preview failed | `preview_capacity_exhausted`, `preview_health_failed`, `preview_capability_revoked`, or `requires_adapter` | Use logs/artifacts, retry bounded health/restart only when receipt says safe, and never share capability-bearing preview URLs. | | Slow/partial context | `timeout_fallback`, `stale_cache`, `degraded`, or latency fields above target | Use startup context, then fetch only the named deeper refs; check `wheelie resources status --json`. | | Disabled capture | capture/publish reports blocked, dirty, uncaptured, unpublished, or spoofed provenance | Run `wheelie working-copy status --json`, repair provenance, then capture/publish again. | | Capacity or budget blocker | `allowlist`, `approval_required`, `budget_exceeded`, or `capacity_limited` | Stop before spendful work and request access/approval. | | Stuck task / stale heartbeat | `heartbeat_stale`, missing checkpoint/context-out, or replay/status disagreement | Resume/nudge only when a fresh checkpoint makes it bounded and non-destructive; otherwise escalate with redacted refs. | | Preview/unsupported command | `preview`, `fixture_only`, or `unsupported` | Do not make it part of the first-run path; use the native command or documented fallback. | ## Deeper reference Keep the first path short; use these when you need details: - [CLI support map](./cli.md) - [Wheelie over SSH](./ssh.md) - [Support levels](./support-levels.md) - [Support and friendly error states](./support.md) - [BYOK and secrets guide](./byok-secrets.md) - [Public command manifest](/schemas/wheelie/public-command-manifest.json)