XeroIDE

XeroIDE — private AI coding for VS Code with XERO/WIZARD assistants, bring-your-own AI, gated edits, safe commands, and wrong-project protection.

XeroIDE is provider-flexible and local-first in design: bring your own AI access, use local or cloud models depending on your setup, and avoid single-provider lock-in or a central token resale dependency. You stay in control of privacy, cost, context, and code changes.

XeroIDE is a VS Code / VSCodium extension that adds AI-assisted coding to your existing editor. XERO is the precise engineering assistant for analysis, debugging, refactoring, careful implementation, and controlled edits. WIZARD is the creative builder assistant for scaffolds, prototypes, interfaces, games, layouts, and fast build flows.

v1.0.0-rc.4 release candidate — XeroIDE has passed the commercial release-check and readiness matrix for packaged-host flows. See CHANGELOG, Release candidate status, and Known limitations. Team sync and remote skill marketplace are not included in this release.

---

Product overview

XeroIDE turns AI coding into a controlled engineering workflow.

XeroIDE is not just an AI chat panel. It is a local-first AI software workspace that plans, builds, verifies, remembers, audits, and ships code using the cheapest safe route available.

Secondary positioning: Plan, build, verify, remember, audit, and ship code using the cheapest safe route available.

XeroIDE is an extension-first AI coding workspace. General product positioning stays provider-generic; provider/runtime names appear only in setup and integration sections:

• Your machine talks directly to the local or cloud model endpoints you configure.
• XeroIDE orchestrates context, privacy controls, cost warnings, audits, and UI — it does not host inference or sell tokens.
• The Assistant sidebar stays simple; Control Center holds advanced tools (context transparency, reviews, providers, policy, audit).

Your machine
├── XeroIDE extension (extension host)
│   ├── SecretStorage — your API keys only
│   ├── Policy Firewall · Cost Guard · Privacy modes
│   ├── Local workspace index
│   ├── Model Autopilot · Context reports · Flight Recorder
│   └── Webviews — UI only (no keys, no provider HTTP from webviews)
├── HTTPS → your configured cloud model provider (bring-your-own AI)
└── HTTP  → your configured local model runtime

There is no XeroIDE central AI proxy and no bundled token plan.

---

Release candidate status

XeroIDE 1.0.0-rc.4 is a commercial release candidate. The packaged VSIX has passed:

• clean install in a fresh VS Code profile
• packaged Ask and Agent webview workflows
• first-run, provider-failure, and read-only storage matrices
• cancellation, reload/crash recovery, multi-root, command-policy, and webview-validation gates
• large-workspace performance, long soak, and packaged accessibility/responsive UI audits

This means the release gates passed; it does not claim perfection, certification, or guaranteed support for every provider/model/workspace. The accessibility audit includes packaged-host DOM automation and manual checklist evidence; external assistive-technology dogfood is recommended before public marketplace launch.

Recommended rollout path: internal dogfood → assistive-tech dogfood → private beta → marketplace pre-release → stable marketplace release.

Install the internal dogfood RC

Build and validate the RC package from the repository root:

npm run compile
npm run xeroide:production-check
npm run xeroide:release-check
npm run package:vsix
npm run test:vsix-content
npm run test:vsix-clean-install
npm run test:vsix-ask-agent-e2e

The internal dogfood artifact is:

./xeroide.vsix

Install it in VS Code / VSCodium with Extensions → ⋯ → Install from VSIX…, or from a terminal:

code --install-extension ./xeroide.vsix

Use a fresh VS Code profile for first-run validation when possible. Do not publish this RC to a public stable marketplace channel; use it for internal dogfood, assistive-technology dogfood, and private beta validation.

---

XERO and WIZARD

XeroIDE provides one unified assistant with two internal execution tiers. XERO handles free/local work using deterministic tools, local models, and self-hosted engines. WIZARD handles advanced BYOK work using your existing provider API keys when the task needs more reasoning power.

• XERO for local-first coding.
• WIZARD for advanced BYOK coding.
• One assistant. Smarter routing. Lower token waste.

You do not need to pick a model on every message. XeroIDE classifies each task, budgets context, and shows a short route reason (tier, cost, privacy). Control tier mode in settings (xeroide.assistant.tierMode) or Control Center → Assistant.

See docs/xero-and-wizard.md and docs/token-saving-strategy.md.

How XeroIDE saves tokens

• Deterministic tools first (no model call)
• XERO preflight before WIZARD paid calls
• Task classification and complexity estimation
• Context budgeting — only necessary files/chunks
• Model capability matching — smallest sufficient model
• Cost Guard before large BYOK requests
• Fallback to local when possible

Assistant modes

Ask, Plan, Agent (build), Debug, and Multitask — each mode enforces what the assistant may do (read-only vs diff-preview edits vs terminal with approval). Run and Ship intents route through deterministic XERO tools when possible (local static server, Git summary).

Route decision card

Every assistant response can show a compact route card: tier (XERO or WIZARD), execution path, reason, cost note, and privacy note. Expand Why this route? for intent, complexity, context budget, and fallback options. Toggle with xeroide.assistant.showRouteDecision.

Who pays for compute

Path	Who pays
Deterministic tools	No model cost
Local models	Your hardware
BYOK cloud	Your provider account
OpenRouter	Your OpenRouter / routing settings
XeroIDE cloud credits	Not available (future)

---

Project Brain

Local per-workspace memory in .xeroide/: structure, frameworks, commands, architecture notes, known issues, and model outcomes. No secrets by default. Control Center → Brain or xeroide.openProjectBrain. See docs/project-brain.md.

Project Map

Heuristic architecture map and import dependency graph (JS/TS/Python imports, package.json). Control Center → Map. See docs/project-map.md.

Goal-Based Workflows

Persistent engineering goals with milestones, files touched, and change-set links. Control Center → Goals. See docs/goals.md.

Change Sets and Rollback

Snapshot-based AI edit tracking with confirmation rollback (no git commands). Created automatically on Agent apply. See docs/change-sets-and-rollback.md.

XERO Verify Engine

Post-edit verification: diagnostics, static site checks, security heuristics, accessibility MVP, JSX/Vite compile checks, playable game completeness, prompt/theme alignment, and visual quality evidence (local-first, deterministic — no cloud model calls). Runs after Agent file apply. See docs/xero-verify-engine.md.

JSX and Vite compile verification

XERO Verify treats dev-server and browser overlay compile errors as hard failures — a running dev server does not mean the app works.

• JSX in wrong extensions: JSX inside .js or .ts files fails verification (jsx_syntax) before completion.
• Vite runtime errors: Terminal or overlay text matching Vite compile patterns (for example [plugin:vite:import-analysis], Failed to parse source, Module not found) fails as runtime_compile_error.
• No false passes: XERO Verify must not report “passed with warnings” when the browser shows a Vite compile error.
• Repair required: Primary action Fix JSX/Vite syntax error — rename to .jsx/.tsx and update index.html, or remove JSX for plain Three.js projects.
• Completion blocked: Summarize, Conclusion, commit, and ship stay blocked until compile errors are fixed and verify passes.

Run npm run test:jsx-vite-verify for deterministic JSX/Vite verify checks.

Playable game verification

When you ask XeroIDE to build a playable game (including FPS/shooter, space combat, arcade, and similar requests), XERO Verify checks generated source for real gameplay — not passive 3D demos.

• Game requests are not complete until controls, entities, collisions, score/health, game over, and restart are detected (or you explicitly accept incomplete output).
• Theme alignment: A playable FPS shell is not enough if it ignores the requested setting. Asking for a space station must not produce a village, forest, or unrelated terrain. XERO scans HUD text, README, and source for theme evidence and contradictions.
• Visual quality (when you ask for HD/high-end/textured/realistic detail): XERO checks for PBR materials, procedural/canvas textures, lighting/shadows, tone mapping, bloom/fog, and scene detail — not flat MeshBasicMaterial block placeholders.
• Passive visual demos fail verification: OrbitControls-only viewers, hyper-realistic human showcases, static environments, blue spheres, and model viewers without a gameplay loop.
• FPS requests additionally require pointer-lock or mouse-look, movement, weapon/shooting, enemies, hit detection, health/score, game over, and restart.
• The build flow shows one primary next action at a time. If gameplay, theme, or visual quality verification fails, the task enters Repair required with Generate space-station HD repair layer, Generate theme repair layer, or Generate gameplay layer — not Conclusion, commit, or ship actions.
• Commit/ship/conclusion actions stay blocked until all required verification passes or you choose Accept incomplete output.

Privacy-first: verification inspects local project files only. Cloud BYOK models are used only when you explicitly route generation/repair through your own keys.

Targeted follow-up edits

XeroIDE supports incremental follow-up edits to an active project (for example: “add windows so you can see space outside”). Follow-ups:

• Classify as code_edit / incremental_edit, not Ask and not a new full build.
• Preserve the existing project, install/dev state, theme, and gameplay unless you explicitly ask to rebuild from scratch.
• Propose a focused patch (typically src/main.js) instead of regenerating the whole scaffold.
• Use a shorter build flow when dependencies are unchanged: review → apply → verify (skip npm install if already done).
• Run follow-up requirement verification when applicable (windows/portholes, glass, visible space exterior).
• Dedupe repeated assistant status cards for the same run/message.
• Block Summarize / Conclusion / commit / ship until required verification passes or you accept incomplete output.

Run npm run test:followup-incremental for deterministic checks on classification, prompts, verify, build flow, and UI dedupe.

Audio/music bug reports (for example: “cannot hear music in the game”) are classified as targeted bug fixes, not gameplay regeneration:

• Classify as code_edit / bug_fix with fix_audio — no GLB/model generation, no full gameplay layer, no project regeneration.
• Inject a browser-safe audio repair prompt (user-gesture unlock, AudioContext resume, procedural music loop).
• Run AudioFeatureVerifier when the request mentions music/audio/sound.
• Run GeneratedAssetVerifier to reject fake .glb/binary placeholders (must have valid GLB magic header glTF).
• When gameplay verification still fails from a prior state, the primary action stays Fix game audio/music; gameplay issues appear as secondary actions.
• Failed verification blocks Conclusion/commit/ship; applied file proposals are not shown again for Accept.

Run npm run test:audio-followup for audio classification, prompts, verifiers, build flow, and approval-state checks.

Repair loop protection

When XERO Verify fails (for example gameplay completeness after a successful follow-up patch):

• The task enters a stable Repair required state — no recursive auto-repair.
• Internal repair prompts are never shown as user chat messages. Repairs run only when you click Generate gameplay layer (or another repair action).
• Duplicate assistant status cards and planning rows are deduped/upserted (one planning row with updated elapsed time).
• Awaiting approval shows “Waiting for approval”, not “Agent is working…”.
• Cancel task stops internal repair/generation loops and ignores stale async updates for the cancelled run.

Run npm run test:repair-loop for checks on message visibility, repair guards, and follow-up preservation.

Single-source-of-truth task state

BuildFlowState (via computeBuildFlowState) is the single source of truth for workflow actions:

• The sticky bottom action bar is the only place for primary workflow buttons (Review, Install, Verify, Repair, Summarize).
• Information cards (file changes, verification, activity) show status only — they do not duplicate primary actions.
• Step counts are derived from the active plan (applicableBuildSteps) — index never exceeds total.
• Repair required shows as a state label, not “7 of 4”.
• Verify failure blocks Summarize, Conclusion, commit, and ship until verify passes or you accept incomplete output.
• Run verify updates the active task thread immediately (not just the platform change-set panel).
• Activity events upsert by phase — one Planning row with updated elapsed time.

Run npm run test:task-state-machine for invariant checks.

Dogfood / QA mode (pre-launch development)

Dogfooding XeroIDE on real consumer projects (Vite + Three.js games) exposes platform bugs — not just project bugs. Enable internal QA capture with:

"xeroide.dogfoodMode": true

Or run XeroIDE: Toggle Dogfood QA Mode.

When enabled, failed agent runs are analyzed for platform issues such as:

Category	Example
verification_false_positive	Verify passed but Vite/browser shows compile error
state_machine	Conclusion visible while verify failed; impossible step counts
stuck_approval_state	Accept shown for already-applied files
wrong_task_classification	Audio bug triggers gameplay/model generation
fake_asset_generation	Text placeholder .glb files
repair_loop	Same repair fingerprint repeats

Reports are saved locally only under .xeroide/dogfood/reports/ (JSON + index). Nothing is sent to a server.

Each report includes severity, consumer impact, recommended platform fix, and regression test suggestions. The assistant shows a Dogfood Report card with Open / Copy / Create regression test / Mark fixed / Dismiss actions.

Final conclusions include a Dogfood finding section when a platform bug was detected.

Commands: xeroide.dogfood.openLatestReport, copyLatestReport, createRegressionTest, listReports, markReportFixed, dismiss.

Run npm run test:dogfood for classifier, store, and regression suggestion checks.

Final task conclusions

XeroIDE generates a structured final conclusion (Cursor-style) when a task reaches a terminal state:

• Complete — only when verification passed; lists changes, files, verification, and next step.
• Repair required — when verify failed; never pretends success.
• Blocked — when commands or prerequisites prevent verify.
• Cancelled — when the user cancels the task.

Conclusions appear as one distinct card at the end of the assistant response. Information cards and the sticky action bar do not duplicate conclusion actions. The progress step is labeled Conclusion (not auto-checked while verify is pending).

Run npm run test:final-conclusion for builder/formatter/guard tests.

AI Workbench

Task scratchpad: context, files, tools, verification, cost, replay. Control Center → Workbench. See docs/ai-workbench.md.

Test Generation and Repair

Test planner, generation prompts (approval required), and repair loop (XERO first). Control Center → Tests. See docs/test-generation-and-repair.md.

Security Gate

Pre-ship security checks integrated with Policy Firewall. See docs/security-gate.md.

Build Product Mode

Guided questionnaire for static sites, React/Vite, or Next plans — no auto scaffolding commands. See docs/build-product-mode.md.

Deployment Assistant

Checklist-only MVP for static, GitHub Pages, Netlify, Vercel, Cloudflare, Docker, Node. No API deploy. See docs/deployment-assistant.md.

Team / Agency Mode

Local workspace profiles for client/agency/enterprise constraints. See docs/team-agency-mode.md.

Skill Packs

Ten built-in workflow packs (frontend, SaaS, security review, tests, etc.). See docs/skill-packs.md.

Model Benchmarks

Local benchmark tasks stored in .xeroide/model-benchmarks.json. See docs/model-benchmarks.md.

Cost Simulator

WIZARD cost risk class before BYOK runs. Control Center → Cost. See docs/cost-simulator.md.

Ask the Project

Local Q&A from Project Brain, Project Map, README, and index — read-only. See docs/ask-the-project.md.

Review Board

One-page project health summary. Control Center → Review Board. See docs/review-board.md.

Approval Policies

Human approval gates for cloud AI, multi-file edits, terminals, external tools, and ship. See docs/approval-policies.md.

Session Replay

Metadata-only session replay (no full prompts/code by default). See docs/session-replay.md.

Fast Actions

Deterministic actions without model calls (README template, git summary, local site, etc.). See docs/fast-actions.md.

Privacy and local storage

All platform features above store data under .xeroide/ in your workspace. Nothing is uploaded to XeroIDE servers. API keys stay in VS Code SecretStorage. Project Brain and replay omit full prompts/code unless you explicitly enable those settings.

Platform commands (selection)

Command	Purpose
xeroide.openProjectBrain	Project Brain tab
xeroide.openProjectMap	Project Map tab
xeroide.createGoal	Create tracked goal
xeroide.openChangeSets	Change sets + rollback
xeroide.runXeroVerify	Run verification
xeroide.openAiWorkbench	AI Workbench
xeroide.runSecurityGate	Security Gate
xeroide.openSkillPacks	Skill packs
xeroide.askProject	Ask the Project
xeroide.openReviewBoard	Review Board
xeroide.runFastAction	Model-free fast action
xeroide.openLocalPacks	Local pack manifests

---

Free and local AI engines

XeroIDE supports local and self-hosted AI engines so you can code with AI without a central XeroIDE proxy. These are runtimes on your machine or your server — XeroIDE does not host models or provide shared API keys.

Engine	Type	Default endpoint
Ollama	Native API	http://127.0.0.1:11434
LM Studio	OpenAI-compatible	http://localhost:1234/v1
llama.cpp	OpenAI-compatible	http://localhost:8080/v1
LocalAI	Self-hosted	http://localhost:8080/v1
vLLM	Self-hosted	http://localhost:8000/v1
Jan	OpenAI-compatible	http://localhost:1337/v1
GPT4All	OpenAI-compatible	http://localhost:4891/v1
text-generation-webui	OpenAI-compatible	http://localhost:5000/v1
Custom endpoint	Any compatible server	You configure

Commands: Scan for Local AI Engines (xeroide.scanLocalEngines), Configure Local AI Provider (xeroide.configureLocalProvider), Test Local AI Provider (xeroide.testLocalProvider).

Other tools (KoboldCpp, TabbyAPI, LiteLLM self-hosted, etc.) can usually connect via Custom Local Endpoint when they expose an OpenAI-compatible API.

See docs/local-ai-engines.md for setup and troubleshooting.

---

OpenRouter support

XeroIDE can connect to OpenRouter using your own OpenRouter API key. OpenRouter can provide access to many models through one API. You can also configure BYOK provider keys inside OpenRouter and use OpenRouter as your routing layer.

OpenRouter lets you use one API key to access many models. If you configure BYOK provider keys inside OpenRouter, your requests can route through your own provider accounts while keeping one unified XeroIDE connection.

Standard OpenRouter

• Uses OpenRouter credits (per your OpenRouter account)
• One OpenRouter key, many models
• Set xeroide.openrouterMode to standard

OpenRouter free models

• Uses available free routes where supported (e.g. openrouter/free)
• Availability and limits may vary
• Set xeroide.openrouterMode to free

OpenRouter BYOK router

• You configure provider keys inside OpenRouter
• XeroIDE stores only your OpenRouter API key locally (SecretStorage)
• Requests go to OpenRouter; routing and billing follow your OpenRouter workspace
• Set xeroide.openrouterMode to byok

Important: OpenRouter BYOK is not the same as direct provider BYOK in XeroIDE. For the strictest provider-direct or local-only workflow, use direct provider keys or local engines. See docs/openrouter.md and docs/openrouter-byok.md.

Commands: xeroide.connectOpenRouter, xeroide.connectOpenRouterByok, xeroide.connectOpenRouterFree, xeroide.testOpenRouterConnection, xeroide.listOpenRouterModels, xeroide.showOpenRouterStatus.

---

External Tools

XeroIDE can connect to the web and third-party services only when Connected Mode is enabled. External requests run from your machine, require permission when configured, and are logged locally. XeroIDE does not proxy these requests through XeroIDE servers.

• Local-only (default): no web search, URL fetch, GitHub/GitLab, databases, or IPFS.
• Connected: enable tools in Control Center → External Tools (xeroide.openExternalTools).

Includes web fetch, user-configured web search (Brave/SerpAPI/Tavily/SearXNG), GitHub/GitLab tokens, read-only database queries (SQLite via CLI), IPFS, and package metadata lookup.

See docs/external-tools.md.

---

Unique benefits

Benefit	What it means
BYOK & local	Use accounts and hardware you already have; no mandatory XeroIDE subscription.
See what the AI sees	Context reports list files, chunks, and approximate size per request.
Diff-first edits	AI code changes open in a diff preview; nothing is auto-applied without your approval.
Privacy modes	From “local first” to Air-Gapped (cloud blocked).
Policy Firewall	Blocks .env, common secret paths, node_modules, and oversized sends.
Cost Guard	Warns before large cloud BYOK requests (your provider bill).
Model Autopilot	Suggests provider/model by task and privacy mode, with a human-readable reason.
AI Flight Recorder	Local metadata audit trail (not full prompts by default).
Codebase Tour	Guided overview for onboarding to a new repo.
Live Health	Review-driven findings in Control Center (diff-first fixes).
Project Changes	Local Git view of what changed since your last push — no GitHub/GitLab token required.

---

Agent: Run site locally (static)

For workspaces with index.html and no package.json, XeroIDE can preview the site with a built-in HTTP server (Node http inside the extension). No npm install, no package.json, and no global serve package.

• Say Run locally, preview site, or click Run Locally after applying static file changes.
• Install and run on a static site is treated as run-only (no install step).
• Node projects (package.json present) offer npm run dev / start / preview with one terminal approval per command.

Command: XeroIDE: Run Local Site (xeroide.runLocalSite).

---

Project Changes

XeroIDE tracks what has changed locally since your last push using your local Git repository only.

• Works with remotes on GitHub, GitLab, Bitbucket, or any Git host (via git remote URLs)
• No provider API token required for MVP
• No backend server — all commands run git on your machine
• No automatic git add, commit, or push
• Auto-updates while you develop (debounced refresh on save and .git changes)

Open Control Center → Project Changes or run XeroIDE: Open Project Changes.

Optional AI actions (metadata-only by default): summarize changes, suggest commit message, push checklist. See docs/git-provider-integration.md for future optional API integration.

In chat, set context to Current Changes to ask: “What changed since my last push?”

---

Trust & data handling

XeroIDE is designed so early testers can verify these claims:

Claim	Implementation
No backend proxy	Provider HTTP from extension host only (ProviderRouter).
No bundled token plan	No XeroIDE API keys; you supply provider keys or use local/demo.
No shared keys	Keys stored per-user in VS Code SecretStorage (SecretManager).
No telemetry by default	No analytics SDK in the extension; see Privacy model.
Webviews never receive API keys	Keys entered via host showInputBox; webviews use command links or postMessage without secrets.

Details: docs/security-and-privacy.md

---

No unlimited AI

XeroIDE does not provide hosted AI subscriptions, does not pay model bills for users, and does not guarantee free or unlimited cloud access.

Free or low-cost options are user-side only:

• Local models (Ollama on your hardware)
• Demo mode (mock responses for UI exploration)
• Provider free routes (e.g. OpenRouter free models when the provider offers them — availability may change)

---

Quick start (developers & testers)

Prerequisites

• Node.js 18+
• VS Code or VSCodium 1.85+
• (Optional) Ollama for local AI

Run locally

git clone <your-repo-url>
cd XeroIDE
npm install
npm run compile

1. Open the XeroIDE project folder in VS Code / VSCodium (File → Open Folder).
   If you renamed the repo from an older folder name, close the old workspace and open the new path (e.g. /Users/you/XeroIDE) — extension refresh fails when the workspace path no longer exists.
2. Press F5 (Run Extension) to launch an Extension Development Host.
3. In the new window: open the XeroIDE activity bar → run XeroIDE: Connect AI.

After code changes: npm run compile, then stop and F5 again (Reload Window alone may not refresh webviews).

Package as .vsix

npm install
npm run package        # creates versioned xeroide-1.0.0-rc.1.vsix in project root
# or
npm run package:out    # writes ./xeroide.vsix

Install in VS Code / VSCodium:

• Extensions view → ⋯ → Install from VSIX… → select the .vsix file.

Requires @vscode/vsce (included as a devDependency). If packaging fails on your OS, run npm run compile and use Install from VSIX from a machine where vsce succeeds, or copy the built out/ tree for F5 development.

npm scripts

Script	Purpose
npm run compile	Build TypeScript to out/
npm run check:commands	Verify package.json commands match commandManifest.ts
npm run watch	Watch mode compile
npm run lint	Typecheck without emit (tsc --noEmit)
npm run package	Build VSIX via vsce
npm run package:out	Build VSIX as ./xeroide.vsix
npm test	Smoke test (command declarations, no keys in media/)

---

Setup guides

Topic	Document
Privacy modes & Air-Gapped	docs/privacy-model.md · docs/air-gapped-mode.md
Local AI (Ollama)	docs/local-ai.md
BYOK (OpenAI, Anthropic, …)	docs/byok-setup.md
OpenRouter & free routes	docs/byok-setup.md#openrouter
Policy Firewall	docs/policy-firewall.md
Cost Guard	docs/cost-guard.md
AI Flight Recorder	docs/ai-flight-recorder.md
Codebase Tour	docs/codebase-tour.md
Alpha testing checklist	docs/alpha-testing.md

---

Usage modes (privacy profiles)

Set during Connect AI or via XeroIDE: Change Privacy Mode:

Mode	Behavior
Private	Cloud providers blocked; local/demo only.
Balanced	Local first when Ollama is ready; cloud for harder tasks.
Cheap	Prefer smaller context and economical routing.
Power	Prefer stronger cloud models when allowed.
Air-Gapped	All cloud providers blocked; Ollama/mock only.

See docs/privacy-model.md.

---

Core features (alpha)

Policy Firewall (AI Firewall)

Filters sensitive paths, respects workspace .xeroignore, redacts likely secrets in context (API keys, JWTs, PEM blocks, database URLs), and enforces privacy-mode cloud blocks before a request leaves your machine.
→ docs/policy-firewall.md

Cost Guard (Cost Pilot)

Assesses cloud context size and file count; prompts before large BYOK sends. Optional daily cloud request cap (xeroide.costGuard.dailyCloudRequestLimit) offers local fallback when reached.
→ docs/cost-guard.md

Task receipts

After WIZARD or code-editing tasks complete, XeroIDE saves a local receipt under .xeroide/receipts/ (provider, files changed, commands, verification). View the latest receipt in Control Center → Workbench.

Agent workflow and safety

Agent mode proposes changes before applying them. Review file diffs, approve/apply when ready, and let XERO Verify run automatically after install/dev-server steps where applicable. Project writes are gated to the active project root, command execution follows workspace trust and command-risk policy, and terminal/dev-server actions can require approval depending on policy.

Cancellation and recovery

Use Cancel during active work to stop provider streaming, pending approval, file apply, command execution, verification, or repair. Cancelled tasks are terminal and stale callbacks are ignored. If VS Code reloads or the extension host restarts mid-task, XeroIDE reconciles from local receipts and recovery state; it does not automatically approve pending changes or repeat already-applied transactions.

Multi-root workspaces

XeroIDE resolves the active project by canonical workspace folder and project evidence, not by the first folder name alone. When a request is ambiguous across roots, XeroIDE asks for clarification or fails safely instead of silently targeting the wrong project.

Diagnostics and exports

Receipts, context reports, Project Brain data, and recovery records are stored locally under .xeroide/ or VS Code storage. Developer diagnostics are hidden by default; enable Developer Mode only when you need request IDs, bridge details, or deeper troubleshooting output.

Developer Mode

Normal users see a clean assistant UI. Enable xeroide.developerMode (or toggle diagnostics in the assistant) to show request IDs, reconcile internals, and raw debug output.

Model Autopilot

Chooses provider/model based on task type, privacy mode, local availability, and your defaults — and records why in the decision path.
Configured via xeroide.useLocalFirst and privacy mode.

AI Flight Recorder

Local ring buffer of request metadata (provider, file count, policy warnings — not full prompts unless you opt in).
Command: XeroIDE: AI Flight Recorder
→ docs/ai-flight-recorder.md

Codebase Tour

Command: XeroIDE: Codebase Tour — structured repo overview using your configured provider.
→ docs/codebase-tour.md

Live Health

Run XeroIDE: Review Current File (or selection). Findings appear in Control Center; fixes use diff preview via Edit Selected Code.
Background review on save is optional (xeroide.enableBackgroundReview).

Context transparency (“See what the AI sees”)

After chat or extension-host commands, open Control Center or XeroIDE: Open Context Details for files included, blocked paths, and approximate size.

---

Main commands

Command	Purpose
XeroIDE: Connect AI	Onboarding wizard (editor panel)
XeroIDE: Open Conversation	Streaming chat (editor panel)
XeroIDE: Open Control Center	Advanced sidebar hub
XeroIDE: Open Provider Settings	Full provider panel (editor)
XeroIDE: Index Workspace Locally	Build local search index
XeroIDE: Ask About Workspace	Q&A using local index chunks
XeroIDE: Explain Current File	Explain active file
XeroIDE: Edit Selected Code	Edit selection with diff preview
XeroIDE: Review Current File	Review + Live Health findings
XeroIDE: Change Privacy Mode	Privacy profile picker
XeroIDE: AI Policy Firewall	Policy status panel
XeroIDE: Cost Guard	Cost settings / last assessment
XeroIDE: Connect OpenRouter	OpenRouter setup wizard
XeroIDE: Connect OpenRouter BYOK	OpenRouter BYOK wizard
XeroIDE: Test OpenRouter Connection	Validate OpenRouter API key
XeroIDE: Remove All Cloud API Keys	Delete all BYOK keys from SecretStorage
XeroIDE: Enable Connected Mode	Turn on external tools (from your machine)
XeroIDE: Fetch URL	Fetch a public URL with approval
XeroIDE: Configure Web Search	Set Brave/SerpAPI/Tavily/SearXNG
XeroIDE: Connect GitHub	Store GitHub PAT locally

---

Key settings

Setting	Purpose
xeroide.privacyMode	private · balanced · cheap · power · airgapped
xeroide.defaultProvider	Default provider id
xeroide.ollamaEndpoint	Ollama URL (prefer http://127.0.0.1:11434 on macOS)
xeroide.openrouterModel	Model id; use openrouter/free for free-route preset
xeroide.openrouterMode	standard · free · byok
xeroide.costGuard.enabled	Enable Cost Guard
xeroide.costGuard.dailyCloudRequestLimit	Daily cloud cap (0 = unlimited)
xeroide.developerMode	Show developer diagnostics in the UI
xeroide.audit.enabled	Enable Flight Recorder
xeroide.audit.storeFullPrompts	Store full prompts in audit (off by default)
xeroide.showCostWarnings	Modal warnings before cloud usage

---

Known limitations

• Project Map dependency graph uses heuristics, not full AST — may miss dynamic imports.
• Deployment Assistant is checklist-only — no automated deploy or marketplace downloads.
• Test repair requires user approval for terminal runs and WIZARD cost confirmation.
• Agency profiles are local JSON — not synced across machines yet.
• Model quality depends entirely on your configured provider or local model — XeroIDE does not tune model weights.
• Local models require sufficient RAM/GPU on your machine; large repos may index slowly.
• Free cloud routes (e.g. OpenRouter free models) may change, rate-limit, or disappear without notice.
• No XeroIDE-hosted unlimited AI — there is no vendor-subsidized token pool.
• No backend sync in alpha — settings and indexes are local to your VS Code profile / machine.
• No team admin dashboard in alpha — single-user workflow only.
• Background review may log to Output without updating Control Center until you run an explicit review.
• Gemini and some provider features may be partially wired; validate with Validate Provider Keys.
• Release-candidate accessibility evidence does not include a separate external screen-reader transcript; assistive-technology dogfood is recommended before public marketplace launch.
• Provider availability is not guaranteed by XeroIDE. Local Ollama, OpenRouter free routes, BYOK model access, rate limits, and context windows depend on user configuration and provider-side availability.
• Command/package failures from npm, Vite, shell, or workspace trust are surfaced by XeroIDE but still depend on the local project and environment.

---

Documentation index

• Alpha testing checklist
• Privacy model
• Local AI
• BYOK setup
• OpenRouter
• OpenRouter BYOK
• External Tools
• Connected Mode
• Tool permissions
• Policy Firewall
• Cost Guard
• Air-Gapped mode
• AI Flight Recorder
• Codebase Tour
• Security & privacy (technical)
• Manual test notes
• Release process
• Project Brain
• Project Map
• Goals
• Change sets & rollback
• XERO Verify
• AI Workbench
• Test generation
• Security Gate
• Build Product Mode
• Deployment Assistant
• Team / Agency Mode
• Skill packs
• Model benchmarks
• Cost simulator
• Ask the Project
• Review Board
• Approval policies
• Session replay
• Fast actions
• Marketplace (future)

---

License

See repository license file.