# Vaner Documentation — Full Content > All documentation pages concatenated for AI consumption. > For a curated index see: https://docs.vaner.ai/llms.txt > For AI install/operation prompts see: https://vaner.ai/prompts/install.md --- # Architecture (/architecture) Vaner runs as a small daemon next to your editor. It watches your repo, prepares work in the background, and serves that work to your AI client through MCP when you ask. The model never waits on Vaner; Vaner has the answer ready. ## How you interact with Vaner [#how-you-interact-with-vaner] Vaner is one local engine with several surfaces around it. MCP is the primary interface for AI agents. Desktop and Companion are the primary human controls. | Surface | Primary user | Purpose | Default? | Where documented | | ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------ | -------------------- | ------------------------------------------------------------- | | AI client via MCP | AI agent | Pull Prepared Work and call `vaner.*` tools from Cursor, Claude Code, Codex, Zed, and similar clients. | Yes, for agents | [MCP mode](/integrations/mcp) | | Desktop tray/taskbar window | Human user | Install, start/stop Vaner, see current status, and wire detected clients. | Yes, for humans | [Getting Started](/getting-started) | | Companion/settings thin client | Human user | Manage common settings, integrations, backend/runtime choices, and privacy posture. | Yes, through Desktop | [Configuration](/configuration) | | Cockpit / Web UI | Advanced user | Inspect engine state, priorities, Prepared Work, diagnostics, and live activity. | No, advanced | [Prepared Work](/prepared-work#inspecting-prepared-work) | | CLI | Power users / CI | Script setup, daemon control, status, doctor, logs, and config. | No | [CLI reference](/cli) | | Primer/rules, skills, plugins/hooks | AI agent integration | Make MCP usage reliable and client-specific by teaching clients when and how to use Vaner. | Yes, where supported | [Client integration depth](/integrations/client-capabilities) | | Proxy/gateway | Compatibility users | OpenAI-compatible fallback for tools that cannot call MCP directly. | No | [Proxy mode](/integrations/proxy) | Users normally do not install Vaner inside the AI client first. Vaner Desktop or `vaner init` configures the integration; the AI client is where the agent uses Vaner through MCP. All surfaces talk to the same daemon. None of them are in the model's hot path; they pull from a queue Vaner keeps populated. ## What Vaner does [#what-vaner-does] ```mermaid flowchart LR Repo[Repo signals] --> Vaner[Vaner daemon] Vaner --> Store[Prepared work + evidence] Store --> MCP[MCP tools] MCP --> Agent[Your AI client] Agent -->|feedback| Vaner ``` When the repo changes (a commit lands, a file changes, a test runs), Vaner notices and **prepares**. Preparing means: pulling related context, running the model in idle time, scoring multiple candidate angles, and landing the strongest as a Prepared Work card with evidence attached. When you actually ask the agent something, Vaner has the relevant card ready to hand over instead of starting from a cold retrieval pass. ## Boundaries [#boundaries] * **Non-mutating by default.** Vaner can prepare a virtual diff but never applies it. Adopt is an explicit user action. * **Local-first.** The daemon, the cockpit, and the model all run on your machine unless you've chosen a hybrid bundle. Privacy posture is part of the [policy bundle](/policy-bundles) you pick at install. * **Read-only against your code.** Vaner reads the working tree and git history; it doesn't write to your branch. ## Going deeper [#going-deeper] The internal moving parts (frontier exploration, scenario scoring, prediction registry, refinement context) aren't user-facing. If you want them, the source is the canonical reference: see [`src/vaner/engine.py`](https://github.com/Borgels/vaner/blob/main/src/vaner/engine.py) and the per-component modules under `src/vaner/`. For knob-by-knob configuration, see [Configuration](/configuration). --- # Auto Focus (/auto-focus) Auto Focus is Vaner's daemon-owned focus layer. It keeps Vaner quiet when there is no useful workspace context and allows Prepared Work only when one eligible workspace is clearly selected. The desktop apps are control surfaces. They show daemon state and send user actions, but they do not decide the active workspace or scheduling policy. ## Default behavior [#default-behavior] * No supported client running: Vaner is idle except cheap maintenance. * Supported client running, no wired workspace: Vaner stays in standby. * One wired active workspace: Vaner may prepare work for that workspace. * Multiple workspaces: Vaner chooses one only when confidence is high. * Ambiguity: Vaner stays in standby instead of guessing. * Paused workspace: no repo reads, indexing, reasoning, or Prepared Work. Vaner selects at most one proactive workspace by default. Other workspaces are standby, dormant, unknown, or paused. ## Privacy boundary [#privacy-boundary] Vaner can detect supported AI clients so it knows when to stay quiet and when to prepare work. It only checks supported clients and Vaner integrations. It does not read prompts, window titles, browser tabs, clipboard, terminal history, terminal buffers, or arbitrary apps. Client detection is local and default-enabled. You can switch to Manual Only or Pause Vaner from Desktop, CLI, or MCP. ## Why not working [#why-not-working] Auto Focus exposes skipped and deferred reasons everywhere: * Desktop Focus panel * `vaner focus status` * `vaner.focus.status` * `GET /focus` Example: ```text Standby: Cursor is running, but no wired workspace was detected. Action: Connect this workspace or choose Work Here. ``` ## CLI [#cli] ```bash vaner focus status vaner focus work-here . vaner focus pin . vaner focus pause . vaner focus resume . vaner focus pause --all vaner focus mode manual-only vaner resources status vaner jobs status ``` ## MCP tools [#mcp-tools] ```text vaner.focus.status vaner.focus.work_here vaner.focus.pin_current_workspace vaner.focus.pause_current_workspace vaner.focus.resume_current_workspace vaner.focus.set_mode vaner.resources.status vaner.jobs.status vaner.jobs.cancel ``` ## HTTP [#http] ```text GET /focus POST /focus/workspaces/{id}/work-here POST /focus/workspaces/{id}/pin POST /focus/workspaces/{id}/unpin POST /focus/workspaces/{id}/pause POST /focus/workspaces/{id}/resume POST /focus/pause-all POST /focus/mode GET /resources GET /jobs ``` `/resources` is read-only in this release. It exposes minimal local runtime and device inventory from existing Vaner config and hardware probes. ## Cloud execution [#cloud-execution] Auto Focus does not run proactive or background work in the cloud in this release. Future cloud execution, if added, will be explicit policy rather than silent fallback. --- # Backends and Multi-Agent Setup (/backends) Vaner is MCP-first: your IDE/agent keeps ownership of chat generation, and Vaner uses a backend to run its **ponder loop** (scenario ranking, exploration, and precompute). ## Default backend (most users) [#default-backend-most-users] Vaner Desktop and `vaner init` default to Ollama on localhost. That is the same default on macOS, Windows, and Linux. The generated local config looks like this: ```toml [backend] name = "ollama" base_url = "http://127.0.0.1:11434/v1" model = "llama3.2:3b" api_key_env = "" prefer_local = true ``` You can switch to a larger pulled Ollama model later: ```bash vaner config set backend.model qwen3.5:8b --path . ``` Hosted backends are explicit alternatives: ```toml [backends.openai] base_url = "https://api.openai.com/v1" model = "gpt-4o" api_key_env = "OPENAI_API_KEY" [backends.claude] base_url = "https://api.anthropic.com/v1" model = "claude-sonnet-4-20250514" api_key_env = "ANTHROPIC_API_KEY" ``` Use this with MCP mode (`vaner mcp --path .`): your client calls Vaner tools and Vaner ponders with the configured backend. ## Picking local vs hosted [#picking-local-vs-hosted] * **Local** (Ollama, LM Studio, vLLM): best for privacy and predictable cost. * **Hosted** (OpenAI, Anthropic, OpenRouter): best when you need stronger reasoning or larger context windows. ## Multi-backend profiles [#multi-backend-profiles] Named profiles are useful if you switch between a cheap/default model and a heavier model for deeper exploration. Vaner also supports per-client isolation: * Send `X-Vaner-Client` to isolate context traces per agent. * Use `vaner inspect --last --client ` for client-specific visibility. ## Advanced: gateway-mode per-request overrides [#advanced-gateway-mode-per-request-overrides] Only in proxy/gateway mode can a caller select a backend profile per HTTP request via headers: ```text X-Vaner-Backend: openai ``` Multi-repo override is disabled by default and should only be enabled intentionally: ```toml [proxy] allow_repo_override = true ``` If your client supports MCP directly, skip these gateway controls and stay on MCP mode. --- # Changelog (/changelog) Notable product releases are published on [**GitHub Releases**](https://github.com/Borgels/vaner/releases) (downloads, tags, and discussion). This page mirrors published release notes in a short, docs-friendly highlights format. {/* sync:github-releases begin */} *The section below is generated from [GitHub Releases](https://github.com/Borgels/vaner/releases). Edit release notes on GitHub, then run `npm run sync:changelog -- --force`.* ## v0.9.0 [#v090] *Released May 4, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.9.0)* * Auto Focus surfaces prepared work closer to the moment of use, with tighter linting around promoted, archived, and contradictory memory * `vaner launch ` and `vaner clients verify` make setup and recovery easier across supported AI clients * Setup now applies policy bundles automatically and improves local model/GPU selection for desktop-class machines * Signed PyPI artifacts, SBOM, and provenance are attached to the GitHub release ## v0.8.10 [#v0810] *Released May 2, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.10)* * chore: harden release preflight discipline * ci: harden zizmor workflow checks * feat: productize Prepared Work surface * chore(readme): simplify to \~100 lines, single front-door, link to docs * feat(primer): add Zed, Windsurf, Roo Code primer surfaces * feat(clients): add `vaner clients verify` for the four-layer leverage stack * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.10). ## v0.8.9 [#v089] *Released May 2, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.9)* * fix(setup): pick qwen3.6 (latest+best) for 32 GB cards instead of qwen3.5 (#224) @abolsen * feat: cockpit refresh + model catalog refresher with proper sampling defaults (#211) @abolsen * feat(cli): vaner up --json + per-device GPU enumeration (#221) @abolsen * feat(init): auto-apply policy bundle, no five-question wizard (#220) @abolsen * feat(cli): `vaner launch ` end-to-end installer (#218) @abolsen * feat(hooks): Cline + Windsurf prompt-submit hooks (Phase C4) (#217) @abolsen * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.9). ## Vaner 0.8.8 [#vaner-088] *Released April 30, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.8)* * Vaner 0.8.8 focuses on prepared work quality, exact component targeting, and release-grade benchmark governance * Adds the Prepared Work surface, combining predictions and generated work artifacts into one cleaner user-facing feed * Adds WorkProduct lifecycle support for high-signal prepared artifacts such as review notes, bug hypotheses, docs drift, research briefs, and exportable virtual diffs * Improves exact component targeting with lightweight symbol indexing and deterministic target normalization so named functions/classes/files beat broad stale relevance * Tightens draft readiness: weak component matches stay evidence-only, while exact definitions, strong test+usage evidence, and explicitly docs/schema-shaped cases can become draft-ready * Adds schema-locked benchmark governance with stable small/medium/large profiles, release gates, reproducibility metadata, and leak scanning * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.8). ## v0.8.7 [#v087] *Released April 26, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.7)* * feat(0.8.7): Live Intent Capture Phase 1 + L0 Claude Code adapter + 0.8.6 carry-overs (#189) @abolsen * fix: resolve code scanning alerts (#188) @abolsen * ci: move to larger GitHub-hosted runners + quality/compatibility split (#187) @abolsen * @abolsen ## v0.8.6 [#v086] *Released April 25, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.6)* * feat(intent): 0.8.6 WS4 — work-style intent priors (#175) @abolsen * feat(0.8.6): WS5 → WS12b release content (recovery) (#186) @abolsen * feat(setup): 0.8.6 WS2 — hardware detection (#185) @abolsen * feat(setup): 0.8.6 WS1 — setup primitives + config schema (#172) @abolsen * fix(release): call SLSA generator by tag, not SHA (#171) @abolsen * @abolsen ## v0.8.5 [#v085] *Released April 25, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.5)* * feat(integrations): 0.8.5 WS2 — context-injection layer (#158) @abolsen * feat(integrations): 0.8.5 WS1 — guidance assets + behavior-shaping tool descriptions (#157) @abolsen * docs(bench): 0.8.4 Deep-Run pipeline-validation bench writeup (#156) @abolsen * chore: harden 0.8.5 contract and release checks (#167) @abolsen * feat(mcp): 0.8.5 WS7 — MCP Apps UI bundle + ui:// resource registration (#163) @abolsen * @abolsen ## v0.8.4 — Validate, then Generalize + contract crate [#v084--validate-then-generalize--contract-crate] *Released April 24, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.4)* * 0.8.4 is a **validation-and-position** release. It generalises the 0.8.3 Deep-Run maturation loop into a reusable `RefinementContext` (default-off feature flag), ships the WS4 adoption-outcome feedback log, and bundles the merged `feat/vaner-contract-crate` Rust contract crate with cross-language conformance fixtures * **Default-off**: `refinement.enabled` ships `False`. 0.8.3 Deep-Run behaviour preserved exactly. 0.8.5 will activate the refinement consumer alongside a production drafter — the adoption-outcome log already accumulates real data from day one so 0.8.5 has signal to consume * `RefinementContext` abstracts the 0.8.3 `DeepRunSession` input to `mature_one()` + `select_maturation_candidates()`, paving the way for background refinement outside Deep-Run mode * `_run_background_refinement_pass()` engine hook — dormant by default; enabled only when `refinement.enabled=True` AND a refinement drafter is injected * `RefinementConfig` with `enabled=False` default + explicit `adoption_pending_confirm_seconds` threshold * 0.8.3 Deep-Run call sites preserved via `RefinementContext.from_deep_run_session()` * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.4). ## v0.8.0 — persistence + goals + unified resolve + briefing + drafter [#v080--persistence--goals--unified-resolve--briefing--drafter] *Released April 24, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.0)* * Completes the architectural cleanup on top of the Phases 1–4 foundation. Six independent work streams ship together because they share the same touch points in `engine.py` and `prediction_registry.py` * `PredictionRegistry` survives across precompute cycles. Signal-driven invalidation (`file_change` / `commit` / `category_shift` / `adoption`) demotes weight, clears briefings, and stales predictions only when real state has changed — no wall-clock decay. Per-path content hashes via `git hash-object` with SHA-256 fallback * Single `Briefing` / `BriefingSection` / `BriefingAssembler` replaces three ad-hoc string-concat sites across engine + MCP. Optional tokenizer hook for real token counts * Single `Drafter` owns the rewrite + draft LLM templates and gate arithmetic. `_precompute_predicted_responses` routes through it; arc / pattern / history / goal-sourced predictions all drive through one path * `WorkspaceGoal` dataclass, branch-name parser with known-acronyms list, `workspace_goals` SQLite table. Engine seeds `PredictionSpec(source="goal")` from active goals. Four new MCP tools: `vaner.goals.{list, declare, update_status, delete}` * `VanerEngine.resolve_query(query, ...)` — single canonical query → Resolution entry. Consults the prediction registry for a label-match, falls back to the heuristic query path, builds Resolution via BriefingAssembler with honest \`alternatives\_considered\`, \`predicted\_response\`, and \`briefing\_token\_used\` / \`briefing\_token\_budget\` * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.8.0). ## v0.7.1 [#v071] *Released April 22, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.7.1)* * See details on GitHub. ## v0.7.0 [#v070] *Released April 21, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.7.0)* * ci: make windows verify non-blocking * fix: ship vaner 0.6.2 hardening (refresh) * docs: keep README focused on Vaner * feat(cockpit): live pipeline view with scenario cluster + system vitals * feat(plugin): ship supported Claude Code plugin + same-repo marketplace * feat(init): install per-client usage primers alongside MCP wiring * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.7.0). ## v0.6.1 [#v061] *Released April 21, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.6.1)* * Fix MCP server startup for stdio/SSE by passing explicit notification capabilities * Restore `vaner config show/keys` stability with intent config compatibility * Add backup-file idempotence and rotation for repeated MCP client wiring * Harden installer MCP dependency resolution and add `vaner uninstall` * Include regression tests and updated installer-first docs/site flows * See full changelog in `CHANGELOG.md` ## v0.6.0 [#v060] *Released April 21, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.6.0)* * fix(ux): harden installer safety, upgrades, and hardware detection * feat(mcp): v1.0 redesign + first-class memory semantics ## v0.4.0 [#v040] *Released April 20, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.4.0)* * Added `vaner up` / `vaner down` for a supervised one-command startup and shutdown path * Unified `vaner status` and `vaner doctor` via a shared runtime snapshot for consistent health reporting * Hardened startup reliability with preflight checks (repo-root safety, inotify headroom, busy-port remediation) * Added inotify overflow fallback to polling watcher mode instead of crashing * Extended `vaner logs` to include daemon and cockpit runtime logs * Updated installer next-steps messaging to point users to `vaner up` + `vaner doctor` * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.4.0). ## v0.3.0 [#v030] *Released April 20, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.3.0)* * MCP-first skills-loop improvements including scenario feedback plumbing and `vaner distill-skill` * CLI UX polish (`--version`, grouped help, config get/keys/edit, aliases, richer doctor output, `vaner upgrade`) * Hermetic eval/query core test lane (no sentence-transformers dependency in default CI path) * `exploration.exploration_model` -> `exploration.model` * `exploration.exploration_endpoint` -> `exploration.endpoint` * `exploration.exploration_backend` -> `exploration.backend` * ...and more on [GitHub](https://github.com/Borgels/vaner/releases/tag/v0.3.0). ## v0.2.0 [#v020] *Released April 20, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.2.0)* * See details on GitHub. ## v0.1.0 - initial public release [#v010---initial-public-release] *Released April 19, 2026 · [Details on GitHub](https://github.com/Borgels/vaner/releases/tag/v0.1.0)* * Initial public release v0.1.0 {/* sync:github-releases end */} --- # CLI Reference (/cli) ## Recommended first-run flow [#recommended-first-run-flow] ```bash vaner init --path . vaner up --path . vaner status --path . vaner doctor --path . vaner down --path . ``` `vaner init` probes hardware, picks a sensible [policy bundle](/policy-bundles), and detects supported AI clients. Skip prompts with `--non-interactive`. ## Setup [#setup] ```bash vaner setup show # Current bundle + reasons + hardware vaner setup recommend # JSON-out (programmatic) vaner setup apply # Persist + hot-reload running daemon vaner setup advanced # Open config in $EDITOR vaner setup hardware # Print HardwareProfile.detect() ``` See [Policy bundles](/policy-bundles) for the catalog and [Configuration](/configuration#advanced-knobs) for the full knob surface. ## Advanced daemon controls [#advanced-daemon-controls] Most users should use `vaner up` and `vaner down`. Use these only when you need separate process control: ```bash vaner daemon start --once false --path . vaner daemon serve-http --path . vaner daemon status --path . vaner daemon stop --path . ``` ## Prepared Work via HTTP/MCP [#prepared-work-via-httpmcp] Prepared Work is normally consumed through desktop, cockpit, or MCP clients. The daemon exposes the same surface over loopback HTTP: ```bash curl -s http://127.0.0.1:8473/prepared-work | jq curl -s http://127.0.0.1:8473/work-products | jq ``` Use `vaner.prepared_work.dashboard` in MCP clients for the UI-safe card feed. Diagnostic clients can use `vaner.work_products.*` for inspect, export, dismiss, and feedback flows. ## Scenario cockpit commands [#scenario-cockpit-commands] ```bash vaner scenarios list --limit 10 --path . vaner scenarios show --path . vaner scenarios expand --path . vaner scenarios compare --path . vaner scenarios outcome --result useful --skill vaner-feedback --path . ``` ## Prompt-time reasoning and comparison [#prompt-time-reasoning-and-comparison] ```bash vaner query "where is auth enforced?" --path . vaner why --path . vaner compare "Summarize auth flow" --path . vaner impact --path . ``` ## Local debugging and state control [#local-debugging-and-state-control] ```bash vaner inspect --last --path . vaner metrics --path . --output summary vaner prepare --path . vaner precompute --path . vaner forget --path . ``` ## Skill loop commands [#skill-loop-commands] ```bash vaner distill-skill --path . [--out-dir PATH] [--name NAME] [--force] ``` `vaner init` also installs a managed `vaner-feedback` skill into `.cursor/skills/vaner/` and `.claude/skills/vaner/`. ## Live monitoring and diagnostics [#live-monitoring-and-diagnostics] ```bash vaner watch --cockpit-url http://127.0.0.1:8473 vaner logs --path . vaner logs --events --cockpit-url http://127.0.0.1:8473 vaner show --cockpit-url http://127.0.0.1:8473 vaner status --path . vaner ps --path . vaner doctor --path . ``` ## Configuration and profile controls [#configuration-and-profile-controls] ```bash vaner config show --path . vaner config show --json --path . vaner config keys --path . vaner config get backend.model --path . vaner config set intent.enabled true --path . vaner config set intent.skills_loop.enabled true --path . vaner config set gateway.routes.gpt- https://api.openai.com/v1 --path . vaner config edit --path . vaner profile show --path . vaner upgrade ``` ## MCP server [#mcp-server] ```bash vaner mcp --path . vaner mcp --path . --transport sse --host 127.0.0.1 --port 8472 ``` The stdio form is the default for Claude Code, Cursor, Codex CLI, VS Code, Windsurf, Zed, Continue, Cline, Roo, and Claude Desktop. ## Optional capability: OpenAI-compatible gateway [#optional-capability-openai-compatible-gateway] ```bash vaner proxy --path . --host 127.0.0.1 --port 8471 ``` Use this only when your client cannot call MCP tools directly. ## Evaluation flows [#evaluation-flows] ```bash vaner eval --path . vaner run-eval --cases-file examples/evals/basic.jsonl --path . ``` ## Version and completion [#version-and-completion] ```bash vaner --version vaner --install-completion ``` Run `vaner --help` and `vaner --help` for full flags. --- # Configuration (/configuration) Vaner reads configuration from `.vaner/config.toml`. ## Example [#example] ```toml [backend] name = "ollama" base_url = "http://127.0.0.1:11434/v1" model = "llama3.2:3b" api_key_env = "" prefer_local = true [mcp] transport = "stdio" http_host = "127.0.0.1" http_port = 8472 [intent] enabled = true include_global_skills = false skill_roots = [".cursor/skills", ".claude/skills", "skills"] [intent.skills_loop] enabled = true max_feedback_events_per_cycle = 200 [gateway.passthrough] enabled = false [privacy] allowed_paths = ["src/**", "docs/**"] excluded_patterns = ["*.env", "*.key", "*.pem", "credentials*", "secrets*"] redact_patterns = ["sk-[a-zA-Z0-9_-]{20,}"] [compute] device = "auto" cpu_fraction = 0.25 gpu_memory_fraction = 0.4 idle_only = true idle_cpu_threshold = 0.6 idle_gpu_threshold = 0.7 embedding_device = "cpu" max_cycle_seconds = 300 max_session_minutes = 30 [exploration] max_exploration_depth = 3 frontier_max_size = 500 min_priority = 0.10 llm_gate = "non_trivial" endpoint = "" model = "" backend = "auto" api_key = "" embedding_model = "all-MiniLM-L6-v2" ``` ## Key sections [#key-sections] * `mcp`: MCP server transport and host/port for SSE mode. * `intent`: skill discovery roots and whether feedback adapts frontier behavior. * `exploration`: controls speculative scenario preparation behavior. * `exploration.endpoint/model/backend`: optional dedicated exploration LLM (separate from user-facing backend). * `exploration.embedding_model`: semantic embedding model for cache matching. * `gateway.passthrough`: optional OpenAI-compatible proxy capability (`false` by default). * `backend`: user-facing model endpoint used for proxy mode. * `privacy`: include/exclude/redaction rules. * `compute`: CPU/GPU limits, embedding device selection, idle-only guardrails, and ponder wall-clock caps. ### CLI shortcuts [#cli-shortcuts] ```bash vaner config keys --path . vaner config get backend.model --path . vaner config set backend.model qwen3.5:35b --path . vaner config set gateway.routes.gpt- https://api.openai.com/v1 --path . vaner config edit --path . ``` ## Where to set values [#where-to-set-values] * `.vaner/config.toml`. Persistent. * `vaner config set `. Hot-reloads the daemon. * `vaner config edit`. Opens the file in `$EDITOR`. * Cockpit Preferences → Engine. Interactive editor. ## Advanced knobs [#advanced-knobs] Most users don't touch these. The policy bundle picked at install time already sets sensible values for every section. If you do need to tune something specific (custom backend URL, daily spend cap, prediction horizon bias, etc.), the full knob surface is in the source — see [`src/vaner/models/config.py`](https://github.com/Borgels/vaner/blob/main/src/vaner/models/config.py) for every field with its type and default. Or: ```bash vaner config keys --path . # list every settable key ``` --- # Examples (/examples) The repository includes example setups in `examples/`: * `basic-usage` * `cloud-agent` * `docker` * `multi-agent-cursor` * `multi-backend` * `ollama-local` * `openai-proxy` * `python-sdk` * `skills-loop` Gateway-mode examples: * `openai-proxy` * `multi-agent-cursor` Browse examples in the main repository: * [github.com/Borgels/vaner/tree/main/examples](https://github.com/Borgels/vaner/tree/main/examples) --- # Getting Started (/getting-started) The fastest path is the [Vaner Desktop app](https://vaner.ai). It gives you the human-facing installer, setup, status, and integration controls, picks a local Ollama model that fits your hardware, and wires Vaner into the AI clients it detects. macOS, Windows, and Linux are the same Vaner Desktop product. The macOS app does not have a separate feature set today; it is a native shell around the same Vaner engine, MCP wiring, and Ollama-first runtime. You normally do not install Vaner inside the AI client first. Desktop configures the integration, then your AI client uses Vaner through MCP. ## How you interact with Vaner [#how-you-interact-with-vaner] | Surface | Primary user | Purpose | Default? | Where documented | | ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------- | | AI client via MCP | AI agent | Pull Prepared Work and call `vaner.*` tools during a task. | Yes, for agents | [MCP mode](/integrations/mcp) | | Desktop tray/taskbar window | Human user | Install, start/stop Vaner, see status, and wire detected clients. | Yes, for humans | [Install Vaner Desktop](#install-vaner-desktop) | | Companion/settings thin client | Human user | Manage common settings, integrations, backend/runtime choices, and privacy posture. | Yes, through Desktop | [Configuration](/configuration) | | Cockpit / Web UI | Advanced user | Inspect engine state, priorities, Prepared Work, diagnostics, and live activity. | No, advanced | [Prepared Work](/prepared-work#inspecting-prepared-work) | | CLI | Power users / CI | Script setup, daemon control, status, doctor, logs, and config. | No | [Power users / CI](#power-users--ci) | | Primer/rules, skills, plugins/hooks | AI agent integration | Make MCP usage reliable and client-specific. | Yes, where supported | [Client integration depth](/integrations/client-capabilities) | | Proxy/gateway | Compatibility users | OpenAI-compatible fallback for tools that cannot call MCP directly. | No | [Proxy mode](/integrations/proxy) | ## Install Vaner Desktop [#install-vaner-desktop] macOS: 1. Download [Vaner Desktop for macOS](https://vaner.ai/download/macos). 2. Open the `.dmg` and drag Vaner into Applications. 3. Launch Vaner Desktop and let it install/start Ollama if needed. If macOS blocks the first launch for an unsigned 0.x build, right-click Vaner and choose **Open** once. Linux: 1. Download [Vaner for Linux](https://vaner.ai/download/linux-deb). 2. Install the `.deb`, then launch **Vaner** from your app list. The Linux desktop package is named `vaner`; the installed GUI command is `vaner-desktop`. The power-user CLI remains the PyPI command `vaner`. If Vaner ever ships the CLI through apt, that package should be named `vaner-cli`. Windows: 1. Download [Vaner for Windows](https://vaner.ai/download/windows). 2. Run the installer, then launch Vaner from the Start menu. ## Power users / CI [#power-users--ci] Use the CLI path for CI, Docker, SSH-only machines, or scripted setup. ```bash curl -fsSL --proto '=https' --tlsv1.2 https://vaner.ai/install.sh | bash ``` Linux and macOS. Detects `uv` or `pipx`, asks before installing prerequisites (Python 3.11+), and installs `vaner[mcp]` so MCP is ready out of the box. Windows: ```powershell pip install "vaner[mcp]" ``` CI / Dockerfile: ```bash VANER_YES=1 \ VANER_BACKEND_PRESET=openai \ VANER_BACKEND_MODEL=gpt-4o-mini \ VANER_BACKEND_API_KEY_ENV=OPENAI_API_KEY \ curl -fsSL https://vaner.ai/install.sh | bash ``` Full env-var list and source: [scripts/install.sh](https://github.com/Borgels/vaner/blob/main/scripts/install.sh). ### Initialize [#initialize] ```bash vaner init --path . ``` Probes your hardware, picks a sensible [policy bundle](/policy-bundles), configures backend + compute defaults, and detects supported AI clients on your machine. You confirm the client list before anything is written. If you want to override the auto-picked bundle, run `vaner setup apply ` after init. ### Start [#start] ```bash vaner up --path . ``` Starts the daemon and cockpit, opens the cockpit URL, supervises both. ```text Daemon PID: Cockpit PID: Cockpit URL: http://127.0.0.1:8473 Health: ready ``` `Ctrl+C` or `vaner down` when done. ## Daily commands [#daily-commands] ```bash vaner up # start vaner status # health summary vaner doctor # detailed diagnostic vaner down # stop ``` ## Connect an AI client [#connect-an-ai-client] If `vaner init` didn't detect your client, see [Connect your client](/integrations/connect-your-client). One command per client; manual MCP picker if you'd rather paste it yourself. ## What's next [#whats-next] --- # Hardware Tiers (/hardware-tiers) Vaner runs a read-only, fail-safe hardware probe on first launch and on every `vaner setup` invocation. The probe collects RAM, CPU class, GPU type / VRAM, battery presence, and detected local runtimes, then maps the result into one of four tiers. The tier feeds the [policy-bundle selector](/policy-bundles) so a *Capable* MacBook gets different defaults from a *High-Performance* workstation. The probe is best-effort and never raises: a missing dependency, a non-zero subprocess exit, a timeout, or unrecognised output yields a sensible fallback rather than failing the wizard. Source: [`vaner.setup.hardware`](https://github.com/Borgels/vaner/blob/main/src/vaner/setup/hardware.py). ## The four tiers [#the-four-tiers] | Tier | Mapping rules | Engine implications | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **light** | `ram_gb < 16`, OR (no GPU and `cpu_class == "low"`), OR (battery present and `ram_gb < 24`) | Smaller local model (`runtime_profile = small`), lower background budget, conservative Deep-Run preset, snappier latency floor. | | **capable** | Anything that isn't light, high-performance, or unknown — typical 32 GB laptop or desktop with integrated or modest GPU | Medium local model, balanced cycle budget, moderate drafting aggressiveness, balanced Deep-Run preset. | | **high\_performance** | NVIDIA or Apple Silicon GPU with `gpu_vram_gb >= 16` (or unknown for unified-memory Apple Silicon), `ram_gb >= 32`, AND not on battery | Larger local model, deeper background budget, aggressive Deep-Run preset, higher concurrency. | | **unknown** | OS probe failed entirely, OR `ram_gb == 0` (RAM probe returned nothing) | Treat snapshot as untrusted. Recommend the *Hybrid Balanced* bundle (cloud-recommended), keep local work conservative. | The `tier_for(profile)` rules are evaluated in the order shown above: `unknown` → `light` → `high_performance` → otherwise `capable`. ## What the engine actually does per tier [#what-the-engine-actually-does-per-tier] ### light [#light] * Runtime profile: `small` (e.g. a 3–7B local model). * `compute.max_cycle_seconds` shortened; `max_concurrent_jobs` capped low. * Background pondering biased toward `likely_next` and `finish_partials`. * Deep-Run preset defaults to `conservative`; long-horizon work falls back to cloud if the bundle allows it. ### capable [#capable] * Runtime profile: `medium` (e.g. 7–13B Q4+). * Cycle and concurrency at the shipped defaults. * Bundle defaults apply unmodified, this is the "intended" tier for the shipped knobs. * Deep-Run preset `balanced`; daytime cycles are short, overnight cycles broader. ### high\_performance [#high_performance] * Runtime profile: `large` (e.g. 30–70B Q4+). * Cycle budget extended; concurrent jobs scaled up to take advantage of the hardware. * Background pondering biased toward `long_horizon` and `balanced`. * Deep-Run preset `aggressive`; the box can handle heavy overnight runs. ### unknown [#unknown] * Treated as untrusted. The selector recommends *Hybrid Balanced* by default and keeps local work small. * Cockpit shows the tier as *Unknown* with a "Re-detect hardware" affordance and a link to [Troubleshooting](/troubleshooting) for probe failures. ## Inspecting the probe [#inspecting-the-probe] ```bash vaner setup hardware # raw HardwareProfile.detect() output vaner setup show # tier + bundle + reasons ``` The desktop apps surface the tier as a one-liner, *"This MacBook Pro looks Capable."*, on the Simple-Mode pane. On every wizard run the probe re-fires; nothing is cached at module level. ## Caveats [#caveats] * **Apple Silicon** uses unified memory, `gpu_vram_gb` is `None` rather than a number. The selector treats that as "VRAM constraint not applicable" and only checks RAM. * **Windows without `psutil`** gets a degraded probe; install `pynvml` (for NVIDIA GPUs) and `psutil` for accurate readings. * **Thermal pressure** (Linux only) is best-effort. If any `/sys/class/thermal/thermal_zone*/temp` zone reports above 85 °C, the snapshot's `thermal_constrained` field flips to `True`. The selector currently only logs this; future bundles may use it to suppress aggressive Deep-Run. --- # Introduction (/) Vaner is a **local-first preparation engine** for AI workflows. It runs beside your AI client, watches the project you've scoped to, and uses idle compute to prepare evidence-backed work (review notes, bug hypotheses, docs drift, virtual diffs, research briefs, ready drafts) before you ask. When the real question arrives, your client gets the best fit quickly instead of starting from a cold retrieval pass. Prepared Work is non-mutating by default. Vaner can prepare a virtual diff but will not apply it or edit your files unless you explicitly export or adopt it. ## Install Vaner [#install-vaner] ## What's next [#whats-next] ## Why Vaner [#why-vaner] Vaner is successful when it improves at least one of: * **Answer quality.** Your agent's first reply is grounded in actual evidence, not generic recall. * **Prompt-time latency.** Work is prepared in advance; the agent picks it up when you ask. * **Cost per good answer.** Local idle compute substitutes for cloud round-trips on routine paths. Model-agnostic. Local Ollama is the default runtime, including on Apple Silicon Macs. vLLM, llama.cpp-compatible servers, or cloud backends (OpenAI, Anthropic, OpenRouter) also work through the same MCP surface. --- # Policy Bundles (/policy-bundles) A *policy bundle* is the intermediate layer between user-facing setup and the engine's actual knobs. Each bundle names an outcome-level archetype (e.g. *"Local Balanced"*, *"Hybrid Quality"*) and carries the dimensions the engine consults: cloud posture, runtime profile, spend profile, latency profile, privacy profile, prediction-horizon bias, drafting aggressiveness, exploration ratio, persistence strength, goal weighting, context-injection default, and Deep-Run profile. Bundles compose multiplicatively with Deep-Run preset overrides at session start. Bundles set the *baseline*; Deep-Run sessions layer additive overrides on top. The single source of truth is [`vaner.setup.catalog.PROFILE_CATALOG`](https://github.com/Borgels/vaner/blob/main/src/vaner/setup/catalog.py). The seven shipped bundles are listed below in catalog order. ## Local Lightweight [#local-lightweight] `id: local_lightweight` > Run entirely on this device with a small local model. Best for > older laptops, battery, and privacy-first users. **Who it's for.** Laptop on battery, integrated GPU, no cloud budget. You want Vaner not to heat the room. | Dimension | Value | | ------------------------- | ------------------ | | Local / cloud posture | `local_only` | | Runtime profile | `small` | | Spend profile | `zero` | | Latency profile | `snappy` | | Privacy profile | `strict` | | Drafting aggressiveness | `0.8` (cautious) | | Exploration ratio | `-0.05` | | Persistence strength | `0.7` (decay fast) | | Context injection default | `digest_only` | | Deep-Run profile | `conservative` | ## Local Balanced [#local-balanced] `id: local_balanced` > Local-first with a mid-sized model. Solid default for a capable > laptop or desktop with no cloud reliance. **Who it's for.** Capable laptop or desktop, willing to ponder more in the background. The default for the *Capable* hardware tier. | Dimension | Value | | ------------------------- | ----------------- | | Local / cloud posture | `local_preferred` | | Runtime profile | `medium` | | Spend profile | `zero` | | Latency profile | `balanced` | | Privacy profile | `strict` | | Drafting aggressiveness | `1.0` | | Exploration ratio | `0.0` | | Persistence strength | `1.0` | | Context injection default | `policy_hybrid` | | Deep-Run profile | `balanced` | ## Local Heavy [#local-heavy] `id: local_heavy` > All-local with a large model and aggressive background pondering. > Built for workstations and homelab GPUs. **Who it's for.** Workstation or homelab with a large local model (e.g. 30–70B at Q4+). Local-only by policy, aggressive by capacity. | Dimension | Value | | ------------------------- | --------------- | | Local / cloud posture | `local_only` | | Runtime profile | `large` | | Spend profile | `zero` | | Latency profile | `quality` | | Privacy profile | `strict` | | Drafting aggressiveness | `1.1` | | Exploration ratio | `+0.10` | | Persistence strength | `1.3` | | Context injection default | `policy_hybrid` | | Deep-Run profile | `aggressive` | ## Hybrid Balanced [#hybrid-balanced] `id: hybrid_balanced` > Local for everyday work, cloud only when it's clearly worth it. > Recommended default for most users. **Who it's for.** Anyone fine with the engine reaching for a cloud model when local is genuinely insufficient. The canonical default when the hardware tier is *unknown*, safe middle path. | Dimension | Value | | ------------------------- | --------------- | | Local / cloud posture | `hybrid` | | Runtime profile | `medium` | | Spend profile | `low` | | Latency profile | `balanced` | | Privacy profile | `standard` | | Drafting aggressiveness | `1.0` | | Exploration ratio | `+0.05` | | Persistence strength | `1.0` | | Context injection default | `policy_hybrid` | | Deep-Run profile | `balanced` | ## Hybrid Quality [#hybrid-quality] `id: hybrid_quality` > Reach for the best available model, local or cloud, and trade > some snappiness and budget for higher answer quality. **Who it's for.** Serious work where you'd rather pay than wait. Cloud bias is set higher; latency optimises for quality over snap. | Dimension | Value | | ------------------------- | ------------------------ | | Local / cloud posture | `cloud_preferred` | | Runtime profile | `large` | | Spend profile | `medium` | | Latency profile | `quality` | | Privacy profile | `standard` | | Drafting aggressiveness | `1.2` | | Exploration ratio | `+0.10` | | Persistence strength | `1.2` | | Context injection default | `top_match_auto_include` | | Deep-Run profile | `balanced` | ## Cost Saver [#cost-saver] `id: cost_saver` > Hybrid setup with tight cloud spend caps. Prefers the cheapest > endpoint that still meets the bar. **Who it's for.** Cost-conscious user who still wants some hybrid capacity. Tight spend cap; cheapest endpoint that meets the latency and context floor. | Dimension | Value | | ------------------------- | ---------------------- | | Local / cloud posture | `local_preferred` | | Runtime profile | `small` | | Spend profile | `low` | | Latency profile | `balanced` | | Privacy profile | `standard` | | Drafting aggressiveness | `0.9` | | Exploration ratio | `-0.05` | | Persistence strength | `0.9` | | Context injection default | `adopted_package_only` | | Deep-Run profile | `conservative` | ## Deep Research [#deep-research] `id: deep_research` > Long-horizon, broad exploration for research and writing. Persists > predictions longer and prefers depth over speed. **Who it's for.** Research / writing work where Vaner should ponder broadly and persistently. Overnight Deep-Run is the natural mode; daytime use composes the bundle's bias with the active session's preset. | Dimension | Value | | ------------------------- | ------------------------------ | | Local / cloud posture | `hybrid` | | Runtime profile | `large` | | Spend profile | `medium` | | Latency profile | `quality` | | Privacy profile | `standard` | | Drafting aggressiveness | `1.1` | | Exploration ratio | `+0.15` (most explore-leaning) | | Persistence strength | `1.5` (slowest decay) | | Goal weighting | `1.4` (highest) | | Context injection default | `policy_hybrid` | | Deep-Run profile | `aggressive` | ## How a bundle is selected [#how-a-bundle-is-selected] `vaner setup recommend` scores all seven bundles against detected [hardware tier](/hardware-tiers) and returns the best match. The reasoning trail (*"hybrid because cloud\_posture = hybrid; medium runtime because tier = capable; balanced Deep-Run because preparation = standard"*) is surfaced verbatim in the cockpit. To inspect or change the active bundle: ```bash vaner setup show # current bundle + reasons + hardware vaner setup recommend # JSON: candidate bundles with scores vaner setup apply # persist + hot-reload ``` --- # Prepared Work (/prepared-work) Prepared Work is Vaner's main user-facing surface. It's a small feed of evidence-backed cards Vaner prepared during idle time, ready to inspect when you ask. Each card answers four questions: * What did Vaner prepare? * Why did Vaner prepare it now? * What evidence supports it? * What safe action can I take? Vaner intentionally shows few, strong items. Candidate, hidden, stale, and superseded artefacts stay out of the feed. Auto Focus gates this feed. By default, proactive Prepared Work only runs for one eligible active workspace; ambiguous or paused workspaces stay quiet. See [Auto Focus](/auto-focus). ## What can appear [#what-can-appear] * Review notes * Bug hypotheses * Docs drift notes * Virtual diffs * Research briefs * Ready prediction-backed drafts ## Actions [#actions] Each card carries server-authoritative actions. Clients render only what Vaner returns: * **Inspect.** Full rationale, evidence, warnings, preview. * **Export.** Vaner-owned content (markdown, patch payload). * **Adopt.** Use a ready prediction as your current intent. * **Dismiss.** Hide from the feed. * **Feedback.** Record useful / partial / irrelevant / wrong. Export and adopt are explicit. Vaner never silently applies patches or edits project files. ## Virtual diffs [#virtual-diffs] Patch-shaped Prepared Work. Stored, not auto-applied. They include the target files, source snapshot, rationale, evidence, and export payload. A virtual diff goes stale when its target files no longer match the recorded snapshot. Stale diffs block export until regenerated. ## Inspecting Prepared Work [#inspecting-prepared-work] The cockpit is Vaner's local control surface. Start it with: ```bash vaner up --path . ``` Default URL: `http://127.0.0.1:8473`. Same Prepared Work feed as the desktop app and any MCP client; UI-safe by default with a diagnostic toggle. Useful endpoints for scripted checks: * `GET /prepared-work` * `GET /work-products` * `GET /work-products/{id}/inspect` * `POST /work-products/{id}/export` Watch the live event stream: ```bash vaner watch --cockpit-url http://127.0.0.1:8473 ``` ## Long-horizon mode [#long-horizon-mode] `vaner deep-run start` opens a longer session biased toward *"what will matter tomorrow?"* instead of the daytime *"what's likely next?"* loop. Pairs with the [*Deep Research*](/policy-bundles#deep-research) bundle. Deep-Run prepares; it does not act. Drafts queue for human adopt / discard. Nothing ships, sends, or commits without an explicit confirmation. ```bash vaner deep-run start vaner deep-run start --preset aggressive --duration 480 --cost-cap 5 vaner deep-run status vaner deep-run stop ``` Bundle defaults pre-fill the session. See [Configuration](/configuration#deep-run) for the per-session knobs and [Policy bundles](/policy-bundles) for each bundle's `deep_run_profile`. ## Goals [#goals] A **goal** is a long-horizon intent in your workspace ("ship the new auth middleware"). Goals persist across daemon restarts and survive individual prompts. Each carries a status (`active` / `paused` / `abandoned` / `achieved`), related files, and a reconciliation state. Declare and inspect goals from any MCP-aware client: ```text vaner.goals.list vaner.goals.declare vaner.goals.update_status vaner.goals.delete ``` Or browse them in the cockpit's `Goals` view. When the repo changes, Vaner reconciles each goal's linked artefacts against the new state. A goal whose evidence has gone stale gets demoted; one that gains confirming evidence gets promoted. ## HTTP and MCP [#http-and-mcp] HTTP: * `GET /prepared-work` * `GET /work-products` * `GET /work-products/{id}/inspect` * `POST /work-products/{id}/export` * `POST /work-products/{id}/dismiss` * `POST /work-products/{id}/feedback` MCP: * `vaner.prepared_work.dashboard` * `vaner.work_products.list` * `vaner.work_products.inspect` * `vaner.work_products.export` * `vaner.work_products.dismiss` * `vaner.work_products.feedback` The default dashboard hides internal lifecycle and ranking fields. Diagnostic clients can opt in. --- # Security and Privacy (/security) Vaner defaults to a conservative posture: * Local-first execution * No content logging * Explicit repository scope (`vaner init --path`) * Exclusion patterns for sensitive files * Inspectable context decisions via `vaner inspect --last` * Non-mutating Prepared Work by default: virtual diffs and exports require explicit user action and are never auto-applied to project files * Local retention controls via `vaner forget` * Skill discovery defaults to repo-local roots (`.cursor/skills/**`, `.claude/skills/**`, `skills/**`) * Privacy zoning for skills (`project_local` for repo paths, `external` for outside paths) * Global skill scanning is opt-in via `[intent].include_global_skills = true` For production deployments, terminate TLS at a trusted reverse proxy and keep Vaner bound to localhost/private networks where possible. --- # Supported hardware (/supported-hardware) Vaner uses [Ollama](https://ollama.com) as its default local runtime, so **Vaner runs everywhere Ollama runs**. If your machine can pull and run a model with `ollama run`, Vaner can use it. On macOS, Ollama officially supports [macOS Sonoma v14+](https://docs.ollama.com/macos) and Apple M-series CPUs/GPUs. Apple GPU acceleration uses [Metal](https://docs.ollama.com/gpu); Intel Macs run Ollama CPU-only. The defaults the Vaner Desktop app picks are tuned to fit comfortably on the hardware it detects. You can override the model later via `vaner config set backend.model `. ## NVIDIA GPUs [#nvidia-gpus] Compute Capability ≥ 5.0 is supported. Most consumer cards from the GTX 10-series (Pascal) onward and every RTX card qualify. See the official [Ollama NVIDIA list](https://docs.ollama.com/gpu) for the full per-architecture matrix. | VRAM | Practical model size | Examples | | -------- | ---------------------- | ----------------------------------- | | 4–8 GB | up to \~4B params, Q4 | Qwen 3 4B, Gemma 4 (small) | | 8–16 GB | up to \~8B params, Q4 | Qwen 3.5 8B | | 16–24 GB | up to \~14B params, Q4 | Qwen 3-Coder Next | | 24 GB+ | up to \~30B params, Q4 | Qwen 3.5 / 3.6 (mid), Llama 4 Scout | Multi-GPU is supported via Ollama's default placement; Vaner doesn't override it. Vaner picks the highest-VRAM device when reporting the hardware tier. ## AMD GPUs (ROCm) [#amd-gpus-rocm] Vaner inherits Ollama's ROCm support on Linux. A subset of cards from the RX 6000-series onward work natively; older cards or unsupported SKUs fall back to CPU. See the official [Ollama AMD list](https://docs.ollama.com/gpu) for the canonical per-card status. | VRAM | Practical model size | | -------- | ---------------------- | | 8–16 GB | up to \~8B params, Q4 | | 16–24 GB | up to \~14B params, Q4 | | 24 GB+ | up to \~30B params, Q4 | Windows ROCm support depends on the driver/HSA combo your card uses; treat as best-effort. ## Apple Silicon [#apple-silicon] M1 and later are the recommended Mac path. Ollama uses Metal for Apple GPU acceleration. Unified memory is the constraint: the model has to fit in shared system RAM, with headroom for macOS itself. | Unified memory | Practical model size | | -------------- | ------------------------------------------ | | 8 GB | up to \~3B params, Q4 (tight; expect swap) | | 16 GB | up to \~7B params, Q4 | | 32 GB | up to \~14B params, Q4 | | 64 GB+ | up to \~30B params, Q4 | The Vaner Desktop app for macOS picks defaults based on your machine's total memory and reserves a sensible chunk for the OS. ## CPU-only [#cpu-only] Vaner runs on CPU when no supported accelerator is detected. Reasonable for small models (≤ 4B params, Q4); larger models thrash and you'll notice it. | RAM | Practical model size | Notes | | -------- | -------------------- | ---------------------------------------------------------------- | | 8–16 GB | up to \~3B params | Slow but usable for `vaner.suggest` / short prompts | | 16–32 GB | up to \~7B params | Acceptable latency for non-interactive precompute | | 32 GB+ | up to \~14B params | Still slower than the smallest GPU; consider an external GPU box | If you'll run on CPU, set the compute preset to `background` in `.vaner/config.toml` so Vaner only uses idle cycles: ```toml [compute] preset = "background" ``` ## Platforms [#platforms] | OS | Status | | ------------------------------------ | ----------------------------------------------------------------------------------------------- | | Linux (Ubuntu, Fedora, Debian, Arch) | Supported. Wayland and X11 both work — there's no Vaner-side difference. | | macOS 14+ | Supported with Ollama as the default runtime. Apple Silicon recommended; Intel Mac is CPU-only. | | Windows 10/11 | Supported via the [Vaner Desktop installer](https://vaner.ai). | ## What if my GPU isn't on Ollama's list? [#what-if-my-gpu-isnt-on-ollamas-list] Two paths: 1. **Run Vaner on a different machine.** The daemon is remote-friendly: `vaner up` on a beefy box, point your AI client at its loopback URL via SSH tunnel, done. See [Backends](/backends) for the configuration. 2. **Use a cloud backend.** OpenAI / Anthropic / OpenRouter all work the same way through MCP. Vaner Desktop's setup wizard exposes them as backend presets. Either way, the Vaner CLI and MCP surface are unchanged. The only thing different is which GPU does the inference. --- # Troubleshooting (/troubleshooting) ## Nothing is happening after install [#nothing-is-happening-after-install] Symptom: * You installed Vaner and connected MCP, but scenarios do not update and cockpit stays idle. Fix: ```bash vaner doctor --path . vaner up --path . ``` Expected: * `doctor` shows `daemon_running: PASS` * `vaner status` shows daemon `running` * `vaner show` loads cockpit at `http://127.0.0.1:8473/` ## Port already in use [#port-already-in-use] Symptom: * `vaner daemon serve-http` fails with `address already in use`. Fix: ```bash vaner down --path . vaner up --path . ``` If another process owns 8473, Vaner now suggests the next free port. You can pin one manually: ```bash vaner up --path . --port 8474 ``` ## inotify watch limit reached [#inotify-watch-limit-reached] Symptom: * Background daemon fails with `inotify watch limit reached`. Fix: ```bash sudo sysctl fs.inotify.max_user_watches=524288 vaner up --path . ``` Vaner also falls back to polling mode when this happens, so it should keep running with reduced responsiveness. ## Ran on the wrong folder [#ran-on-the-wrong-folder] Symptom: * You accidentally ran Vaner on `/home/` or another huge non-repo directory. Fix: ```bash cd /path/to/your/repo vaner up --path . ``` If you must run a non-standard path, use `--force` deliberately: ```bash vaner up --path /some/path --force ``` ## My agent is not calling Vaner tools [#my-agent-is-not-calling-vaner-tools] Symptom: * MCP config exists, but your client never uses Vaner tools. Fix checklist: 1. Confirm MCP config exists (`.cursor/mcp.json`, Claude config, etc.). 2. Reload your AI client window/session after `vaner init`. 3. Verify with `vaner doctor --path .` and look for MCP-related checks. 4. Prompt explicitly once: "use the vaner MCP tools for this task". ## Prepared Work looks empty [#prepared-work-looks-empty] Symptom: * `/prepared-work` or the desktop Prepared Work feed returns no cards. Fix: ```bash vaner up --path . vaner doctor --path . curl -s http://127.0.0.1:8473/status | jq ``` An empty feed is valid when Vaner has no strong, fresh item to show. Weak candidate artifacts and stale virtual diffs are intentionally hidden from the normal feed. Run a longer session, declare a goal, or use `vaner.warm` from an MCP client to steer preparation toward active work. ## Ollama errors or 404 responses [#ollama-errors-or-404-responses] Symptom: * Backend requests fail, or `doctor` reports runtime/model issues. Fix: ```bash ollama serve ollama pull vaner doctor --path . ``` Confirm your configured model matches a pulled model in Ollama: * `.vaner/config.toml` -> `[backend].model` * `http://127.0.0.1:11434/api/tags` -> includes the same model name On macOS, install Ollama from [ollama.com/download](https://ollama.com/download) or let Vaner Desktop offer to install it. Apple Silicon Macs use Ollama's Metal acceleration automatically; Intel Macs are CPU-only, so use a smaller model if first-run checks are slow. ## CLI says daemon is stopped but doctor is green [#cli-says-daemon-is-stopped-but-doctor-is-green] `vaner status` and `vaner doctor` now use the same runtime snapshot source. If they disagree, restart with: ```bash vaner down --path . vaner up --path . vaner doctor --path . ``` ## The wizard did not detect my client [#the-wizard-did-not-detect-my-client] Symptom: * `vaner init` did not list your MCP client in step 3. Fix: ```bash vaner init --clients cursor --path . # explicit known client id vaner init --clients other --path . # print generic MCP snippet ``` Supported explicit ids: * `cursor` * `claude-desktop` * `claude-code` * `vscode-copilot` * `codex-cli` * `windsurf` * `zed` * `continue` * `cline` * `roo` If your client is still missing, use the generated snippet and open a support request: * [github.com/Borgels/vaner/issues/new?labels=client-support](https://github.com/Borgels/vaner/issues/new?labels=client-support) --- # Client integration depth (/integrations/client-capabilities) Wiring Vaner as an MCP server is the *minimum* integration. To make sure the agent actually uses Vaner instead of just *being able to*, we install up to four layers per client. Clients differ wildly in what they support. This page is the source of truth for: * **The four-layer leverage stack**. what each layer does and why MCP alone is rarely enough. * **Per-client capability matrix**. which layers each supported client actually exposes (per their official docs, sourced 2026-05). * **Vaner's current install footprint**. which layers Vaner writes today, and the gaps we know about. ## The four layers [#the-four-layers] ### Layer 1: MCP server [#layer-1-mcp-server] The technical wiring. Adds a `vaner` entry to the client's MCP server config so the client can call `vaner.*` tools. This is the floor. Without it, nothing else matters; with it alone, you depend entirely on the model's training to know it should call Vaner. Models often *don't*. ### Layer 2: Primer [#layer-2-primer] A "system-prompt-like" markdown block telling the model **when and how** to use Vaner. Examples: * *"Before spelunking the codebase, call `vaner.resolve` with a short description of the task."* * *"At the end of any non-trivial work, call `vaner.feedback` with the resolution\_id and a rating."* Empirically: when the primer is missing, models don't reliably call `vaner.resolve` even when Vaner is wired. The primer is what turns **possible** into **actual** usage. Most clients support a per-project rules file (`CLAUDE.md`, `.cursor/rules/*.mdc`, `AGENTS.md`, etc.) that the model reads on every session. ### Layer 3: Skills (or workflows / prompts / modes) [#layer-3-skills-or-workflows--prompts--modes] An agent-callable subroutine, usually a markdown document with metadata, shipped separately from the primer. Two flavors: * **Auto-loaded** (Claude Code, Cursor, Codex CLI): the model reads each skill's description and decides when to invoke it. Vaner's `vaner-feedback` skill is auto-loaded; the model uses it whenever it's about to record feedback. * **User-invoked** (Cline workflows, Windsurf workflows, Continue prompts): the user types `/` to trigger it. Less leverage, since the model won't call it on its own. Some clients (Roo Code with `run_slash_command`) blur the line by letting the agent invoke its own slash commands. ### Layer 4: Plugins / hooks [#layer-4-plugins--hooks] The deepest integration. A plugin bundle ships **multiple layers atomically** (MCP server + primer + skills + hooks + monitors) and registers code that runs at session lifecycle moments (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `FileChanged`, etc.). Hooks are what let Vaner do active work between turns: pre-fetch context when the user starts typing, surface fresh prepared work as the session opens, record feedback after a tool call lands. **This is the layer that turns Vaner from "tool the agent can call" into "engine quietly preparing work for the agent in the background."** Plugin-system support is the most uneven layer. Some clients have rich hook APIs (Claude Code, Cursor 1.7+, Windsurf, Cline), some have plugins without hooks (Claude Desktop's MCPB), and some have neither (Zed, Continue). ## Capability matrix [#capability-matrix] What each client supports per layer (based on official docs as of 2026-05). Cells link to the doc page where the feature is described. | Client | MCP | Primer | Skills / workflows | Plugins / hooks | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **[Claude Code](/integrations/connect-your-client)** | [project + user, JSON](https://code.claude.com/docs/en/mcp) | [`CLAUDE.md`, `.claude/rules/*.md` w/ frontmatter](https://code.claude.com/docs/en/memory) | [`SKILL.md` auto-loaded](https://code.claude.com/docs/en/skills) | [Full plugin system w/ rich hooks](https://code.claude.com/docs/en/plugins) | | **[Cursor](/integrations/connect-your-client)** | [project + user, JSON](https://cursor.com/docs/context/mcp) | [`.cursor/rules/*.mdc` w/ `alwaysApply`](https://cursor.com/docs/context/rules) | [`SKILL.md` auto-loaded (2.4+)](https://cursor.com/docs/skills) | [Plugin system + 17 hooks (1.7+)](https://cursor.com/docs/hooks) | | **[VS Code Copilot](/integrations/connect-your-client)** | [workspace + user, JSON](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | [`.github/copilot-instructions.md` + `*.instructions.md` w/ `applyTo`](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) | [Agent Skills (experimental, 1.108+)](https://code.visualstudio.com/docs/copilot/customization/agent-skills) | [Extension API only — no Copilot lifecycle hooks](https://code.visualstudio.com/api/extension-guides/ai/mcp) | | **[Codex CLI](/integrations/connect-your-client)** | [user TOML, project overrides](https://github.com/openai/codex/blob/main/docs/config.md) | [`AGENTS.md` hierarchy](https://developers.openai.com/codex/guides/agents-md) | [`SKILL.md` auto-loaded](https://developers.openai.com/codex/skills) | [Plugins + hooks behind `codex_hooks` flag](https://developers.openai.com/codex/hooks) | | **[Cline](/integrations/connect-your-client)** | [user JSON](https://docs.cline.bot/mcp/configuring-mcp-servers) | [`.clinerules/` w/ optional path-glob frontmatter](https://docs.cline.bot/features/cline-rules) | [Workflows in `.clinerules/workflows/` (manual `/` invoke)](https://docs.cline.bot/features/slash-commands/workflows) | [8-event hooks in `.clinerules/hooks/`](https://docs.cline.bot/features/hooks) | | **[Continue](/integrations/connect-your-client)** | [`.continue/mcpServers/*.yaml`](https://docs.continue.dev/customize/deep-dives/mcp) | [`.continue/rules/*.md` w/ frontmatter](https://docs.continue.dev/customize/deep-dives/rules) | [Prompts (manual `/` invoke only)](https://docs.continue.dev/customize/deep-dives/prompts) | None — Hub bundles for distribution but no lifecycle hooks | | **[Zed](/integrations/connect-your-client)** | [`settings.json` `context_servers`](https://zed.dev/docs/ai/mcp) | [Auto-detects `.rules`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, etc.](https://zed.dev/docs/ai/rules) | None — extensions provide slash commands but not auto-loaded skills | [Extension API; no AI session-lifecycle hooks](https://zed.dev/docs/extensions) | | **[Windsurf](/integrations/connect-your-client)** | [user JSON](https://docs.windsurf.com/windsurf/cascade/mcp) | [`.windsurf/rules/*.md` w/ `trigger:` modes](https://docs.windsurf.com/windsurf/cascade/memories) | [Workflows in `.windsurf/workflows/` (manual)](https://docs.windsurf.com/windsurf/cascade/workflows) | [12-event hooks in `.windsurf/hooks.json`](https://docs.windsurf.com/windsurf/cascade/hooks) | | **[Claude Desktop](/integrations/connect-your-client)** | [User JSON only — no per-project](https://modelcontextprotocol.io/quickstart/user) | Cloud only (claude.ai Profile/Project Instructions) | Cloud uploads only — no local-disk integration | [MCPB bundles](https://github.com/anthropics/dxt) — MCP-only, no lifecycle hooks | | **[Roo Code](/integrations/connect-your-client)** | [Global + `.roo/mcp.json`](https://docs.roocode.com/features/mcp/using-mcp-in-roo) | [`.roo/rules/` + per-mode dirs](https://docs.roocode.com/features/custom-instructions) | [Custom Modes + Slash Commands + `run_slash_command`](https://docs.roocode.com/features/custom-modes) | None documented | ## Vaner's current install footprint [#vaners-current-install-footprint] What `vaner init` and the Vaner Desktop app actually write today, per layer: | Client | MCP | Primer | Skill | Plugin | | --------------- | --- | ------------------------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Claude Code | ✓ | `.claude/CLAUDE.md` (+ optional `~/.claude/CLAUDE.md`) | `~/.claude/skills/vaner/vaner-feedback/SKILL.md` | ✓ Full plugin (`plugins/vaner/`) — hooks + monitor + skills | | Cursor | ✓ | `.cursor/rules/vaner.mdc` (`alwaysApply: true`) | `.cursor/skills/vaner/vaner-feedback/SKILL.md` | ✓ Full plugin (`cursor-plugins/vaner/`) — `sessionStart` + `beforeSubmitPrompt` hooks | | VS Code Copilot | ✓ | `.github/copilot-instructions.md` (block-merged) | ✗ — possible (experimental in 1.108); not yet shipped | ✗ — only an extension API exists | | Codex CLI | ✓ | `AGENTS.md` (block-merged) | `~/.codex/skills/vaner-feedback/SKILL.md` | ✗ — possible (behind `codex_hooks` flag); not yet shipped | | Cline | ✓ | `.clinerules` (block-merged) | `.clinerules/workflows/vaner-feedback.md` | `.clinerules/hooks/UserPromptSubmit` (composer-submit) | | Continue | ✓ | `.continue/rules/vaner.md` (block-merged) | `.continue/prompts/vaner-feedback.md` (manual `/`) | n/a — no hooks system | | Zed | ✓ | `.rules` (block-merged) | n/a | n/a | | Windsurf | ✓ | `.windsurf/rules/vaner.md` (`trigger: always_on`) | `.windsurf/workflows/vaner-feedback.md` | `.windsurf/hooks.json` (composer-submit on `user_prompt`) | | Claude Desktop | ✓ | n/a — no local surface | n/a — no local surface | ✗ — possible (MCPB bundle); not yet shipped | | Roo Code | ✓ | `.roo/rules/vaner.md` | `.roo/commands/vaner-feedback.md` (agent-invocable via `run_slash_command`) | n/a | ## Gap analysis [#gap-analysis] After Phase C of the IDE/agent visibility plan, the leverage stack is filled in for every client where Vaner can ship today. What's left is gated on upstream releases or is UX-only: ### Awaiting upstream [#awaiting-upstream] **VS Code Copilot skill.** Agent Skills standard, currently experimental in VS Code 1.108. Will ship when the feature graduates to stable. **Codex CLI hooks.** Codex CLI exposes `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, and `Stop` events behind a `codex_hooks = true` feature flag. Will ship when the flag goes stable. ### UX-only, lower priority [#ux-only-lower-priority] **Claude Desktop MCPB bundle.** Claude Desktop has no lifecycle hooks but does have one-click MCPB install bundles. A Vaner MCPB would let users install via double-click instead of editing `claude_desktop_config.json` by hand. UX win, not a leverage win. ### Genuinely not applicable [#genuinely-not-applicable] **Zed skills/plugin**. Zed has no agent-callable subroutine concept and no AI session-lifecycle hooks for third parties. Primer-only. **Continue plugin/hooks**. Continue has no lifecycle hook system. Hub bundles cover plugin-style distribution but only for assistants/blocks, not lifecycle behaviour. **Roo plugin**. Roo Code has no documented hook API. Slash commands (invocable by the agent via `run_slash_command`) are the deepest layer Roo exposes today. **Claude Desktop primer/skill**. both are cloud-only on Claude Desktop; no local-disk surface for Vaner to write into. ## How this informs the verification UI [#how-this-informs-the-verification-ui] The desktop wizard's final "Vaner is ready" panel reports per-client status using this same matrix. A row goes green only when **every applicable layer for that client is wired**, not just MCP. A client where Vaner is in `mcp.json` but no primer is installed gets an amber chip, because the likely failure mode is "the AI can call Vaner but doesn't." See [Pass 4 plan](https://github.com/Borgels/vaner) for implementation details. This matrix is curated. When a client ships new capabilities (Cursor 2.4 added skills; VS Code 1.108 added experimental skills; Codex shipped hooks behind a flag) update this page first, then file an issue against vaner to track the install-side work. --- # ComposerAdapter (/integrations/composer-adapter) Vaner consumes explicit composer/prompt lifecycle events from supported clients via a **ComposerAdapter**. Each event carries a `DraftIntentSnapshot` plus a capability declaration, and lands on the local Vaner daemon's `POST /signals/composer` endpoint as a `SignalEvent` of kind `composer_lifecycle`. The first official adapter ships in the [Claude Code plugin](/integrations/connect-your-client) and fires on every prompt submit (Level 0). This page is the cross-language contract for adapter authors who want to wire additional clients. ## Privacy contract [#privacy-contract] * The draft text itself **never** crosses this boundary. Adapters send a `text_hash` (sha256 of the draft text) and a length, never the raw text or a preview. * Local-only by default. Cloud processing of unsent draft text is **not** enabled in v0.8.7. * No raw-draft persistence. The engine stores the snapshot, hash, lifecycle state, and counters; raw text never reaches storage. * Per-client opt-in inherits the host's plugin/extension enable/disable surface in v0.8.7. First-class per-client opt-in scaffolding lands in v0.8.8. Vaner is **not** a client. Live Intent Capture only honors explicit client-level mechanisms (hooks, plugin APIs, extension APIs, documented local-config hooks). Generic input capture, accessibility APIs, terminal scraping, and unsupported DOM injection are not acceptable adapter mechanisms. ## Capability levels [#capability-levels] Adapters MUST declare the highest lifecycle they can truthfully observe. Fabricating higher states corrupts the engine's downstream scoring; the daemon validates each event against the adapter's declared `capabilities.emits` on ingest. | Level | What the adapter can observe | Honest `emits` | | ----- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | L0 | Submit-time only (the prompt as it leaves the composer) | `["submitted"]` | | L1 | Pre-submit draft lifecycle (debounced snapshots while user types) | `["observing", "tentative", "stabilizing", "actionable", "submitted", "cleared", "abandoned"]` | | L2 | L1 + host-rendered affordance hook near the composer | same as L1 | | L3 | L2 + host-native adopt flow for prepared packages | same as L1 | ## Capability matrix (existing surfaces) [#capability-matrix-existing-surfaces] | Surface | Hook mechanism | Level | | -------------------------- | ------------------------------------ | -------- | | Claude Code (plugin) | `UserPromptSubmit` hook (v0.8.7 MVP) | L0 | | Cursor | MCP tools only (no composer hook) | — | | Claude Desktop | MCP tools only | — | | VS Code (Copilot Chat MCP) | MCP tools only | — | | Codex CLI | MCP tools only | — | | Windsurf | MCP tools only | — | | Zed | MCP `context_servers` only | — | | Continue | MCP tools only | — | | Cline | MCP tools only | — | | Roo Code | MCP tools only | — | | Vaner VS Code extension | Cockpit/webview consuming daemon SSE | excluded | The Vaner VS Code extension is **explicitly not** an adapter source. Vaner does not own a composer; doing so would violate the "Vaner is not a client" thesis. The extension surfaces prepared-package state from the daemon, it does not observe a user composer. Other clients enter the matrix only when an explicit, documented hook/plugin/extension mechanism exists in the host. ## Wire format [#wire-format] Adapters POST to the loopback daemon endpoint: ```http POST http://127.0.0.1:8473/signals/composer Content-Type: application/json ``` The endpoint envelopes the snapshot into a `SignalEvent(kind="composer_lifecycle", payload=)` and calls `engine.observe()`. The response carries a `composer_event_id` (UUID) that the adapter MAY surface to the host so subsequent adoptions can attribute back to the originating event. A snapshot looks like (L0 example): ```json { "session_id": "claude-code-session-abc123", "snapshot_id": "01HX...", "timestamp": "2026-04-25T20:14:45Z", "lifecycle_state": "submitted", "text_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "length_chars": 142, "capabilities": { "level": "L0", "emits": ["submitted"], "host_app": "claude-code", "host_kind": "ai_chat_client" }, "workspace_id": "/home/me/repos/example", "field_role": "agent_prompt" } ``` ## Authoring an adapter [#authoring-an-adapter] 1. **Pick a host that exposes an explicit composer/prompt lifecycle hook.** If the host has no such mechanism, do not invent one, wait for the host to ship one. 2. **Decide the honest capability level.** If the hook only fires at submit time, declare `level: "L0"` and `emits: ["submitted"]`. If the hook fires on every keystroke or on debounced draft updates, you can honestly declare a higher level. 3. **Compute the text hash.** `text_hash = sha256(draft_text)`. Never log, store, or transmit the raw draft text. 4. **POST the snapshot.** Send to `http://127.0.0.1:/signals/composer` (default port `8473`) with a short timeout (≤ 1 s recommended). On failure, fail silent, never block the user's prompt. 5. **Cadence.** L0 adapters emit one POST per submit. L1 adapters debounce snapshot emission (≥ 250 ms between meaningful changes) and only emit when the lifecycle state would actually change. ## Reference implementation [#reference-implementation] The [Claude Code plugin](https://github.com/Borgels/vaner/tree/main/plugins/vaner) ships the L0 reference adapter: * `plugins/vaner/hooks/hooks.json`, `UserPromptSubmit` hook registration * `plugins/vaner/scripts/composer-submit.sh`, shell shim * `plugins/vaner/scripts/composer_submit.py`, Python translator that reads stdin JSON, computes the hash, POSTs to the daemon ## JSON Schema [#json-schema] The wire-contract JSON Schema is generated from the pydantic models in [`src/vaner/signals/composer/contract.py`](https://github.com/Borgels/vaner/blob/main/src/vaner/signals/composer/contract.py) and committed at [`docs/specs/composer-adapter.schema.json`](https://github.com/Borgels/vaner/blob/main/docs/specs/composer-adapter.schema.json). Adapters in non-Python languages can validate their payloads against this schema. CI guards drift via `git diff --exit-code` after running `vaner-composer-schema`. ## What this enables in v0.8.7 [#what-this-enables-in-v087] A composer-lifecycle event flows through Vaner's signal pipeline and: * Becomes a new prediction source `composer_intent`, anchored to the composer `session_id`. * Receives a per-WorkStyle multiplier so writers/researchers (whose drafts are the most intent-revealing) get a stronger boost than coding/general/support. * Stales automatically when the user clears or abandons the draft, so no wasted preparation on dead branches. * Threads a `composer_event_id` through to `Resolution.composer_event_id` on adoption, so hit/miss telemetry attributes back to the originating composer event. The full Phase 2 (true Level-1 adapters with debounced pre-submit snapshots) and Phase 3 (inline "Prepared" affordances near the composer) work lands in subsequent releases as ecosystem hook support emerges. --- # Connect your AI client (/integrations/connect-your-client) Vaner exposes context to your AI client over [MCP](https://modelcontextprotocol.io/). The Vaner Desktop app installs the right wiring automatically when it detects a supported client. If you'd rather drive it from the CLI: ```bash vaner launch ``` Replace `` with one of: | Client | Command | | --------------------- | ----------------------------- | | **Claude Code** | `vaner launch claude-code` | | **Cursor** | `vaner launch cursor` | | **VS Code (Copilot)** | `vaner launch vscode-copilot` | | **Codex CLI** | `vaner launch codex-cli` | | **Cline** | `vaner launch cline` | | **Continue** | `vaner launch continue` | | **Zed** | `vaner launch zed` | | **Windsurf** | `vaner launch windsurf` | | **Claude Desktop** | `vaner launch claude-desktop` | | **Roo Code** | `vaner launch roo` | `vaner launch` runs every applicable [leverage layer](/integrations/client-capabilities) in one pass, MCP server entry, primer (rules file), skill / workflow / prompt, and lifecycle hooks where the client supports them. Each layer reports its own status. Re-run any time; it's idempotent. > \[!TIP] > Already running `vaner init`? It does the same thing for every > client it detects. `vaner launch ` is the per-client form. ## Prefer to wire it manually? [#prefer-to-wire-it-manually] Pick your client and Vaner will print the exact MCP entry to paste: ## Verifying the integration [#verifying-the-integration] Open your client and ask the agent something open-ended about your repo. If the model calls a `vaner.*` tool, `vaner.resolve`, `vaner.prepared_work.dashboard`, or similar, the install worked. A copy-pasteable verification phrase: > *Without searching the codebase first, check if Vaner has prepared > anything relevant to a recent change in this repo, and tell me which > `vaner.*` tool you used.* If the agent grep's the repo instead of calling Vaner, the primer isn't in place, try `vaner launch --force`. ## What gets installed per client [#what-gets-installed-per-client] See the full per-client matrix at [Client integration depth](/integrations/client-capabilities). At a glance: * **All clients** get the MCP server entry. * **Most clients** get a primer (system-instruction-like rules file) so the model knows when to call Vaner. * **Clients with skills / workflows / slash commands** get the `vaner-feedback` adapter. * **Clients with hooks** (Cline, Windsurf) get a prompt-submit hook that pre-fetches prepared work as you type. * **Claude Code** and **Cursor** also get full plugins (atomic install bundles via each client's marketplace), see `plugins/vaner/` and `cursor-plugins/vaner/` in the source repo. ## Removing Vaner from a client [#removing-vaner-from-a-client] ```bash vaner clients uninstall ``` Removes the MCP entry. Primer / skill / hook files written under `.cursor/`, `.clinerules/`, `.windsurf/`, `.roo/`, `.claude/`, etc. can be deleted by hand or by removing the entire per-client directory. --- # Context-only HTTP Mode (/integrations/context-only) > \[!TIP] > If your IDE already supports MCP tools, use [MCP mode](/integrations/mcp) > first. Context-only mode is for frameworks that want raw prepared context. ## Start context-only endpoint [#start-context-only-endpoint] ```bash vaner proxy --context-only --path . --host 127.0.0.1 --port 8472 ``` ## Example request [#example-request] ```bash curl -s http://127.0.0.1:8472/v1/context \ -H "Content-Type: application/json" \ -d '{"prompt":"review this auth flow","top_n":8}' ``` The response includes selected artefacts and rationale metadata. Your framework then decides how to inject that context into its own model call. --- # Docker (/integrations/docker) > \[!TIP] > For a single local repo, start with [MCP mode](/integrations/mcp). Use Docker > when you need a repeatable multi-service topology. ## Start services [#start-services] ```bash REPO_ROOT=. docker compose up -d ``` The default compose setup runs: * `vaner-daemon` (background preparation) * `vaner-proxy` (`:8471` injected completions) * `vaner-context` (`:8472` context-only API) ## Validate containers [#validate-containers] ```bash docker compose ps curl -s http://127.0.0.1:8472/v1/context \ -H "Content-Type: application/json" \ -d '{"prompt":"summarize current auth flow","top_n":6}' ``` --- # Integrations (/integrations) Default onboarding is MCP + cockpit (`vaner mcp`, `vaner watch`, `vaner show`). This section covers integration modes and tool-specific recipes. ## Default integration (recommended) [#default-integration-recommended] ## Advanced and compatibility modes [#advanced-and-compatibility-modes] If your client supports MCP, prefer MCP mode first and only use advanced modes when needed. --- # MCP Mode (/integrations/mcp) Vaner ships an [MCP](https://modelcontextprotocol.io/) server so MCP-aware IDEs and agents can pull Prepared Work and evidence-backed context without putting Vaner in the model hot path. ## Start the server [#start-the-server] ```bash vaner mcp --path . ``` The server speaks stdio by default. Clients invoke `vaner mcp --path .` as a subprocess and communicate over their own stdin/stdout. ## Recommended client behavior [#recommended-client-behavior] Normal clients should call `vaner.prepared_work.dashboard` first. It returns a small list of UI-safe cards and hides internal lifecycle, self-evaluation, and raw ranking fields. When the user inspects a card, call the action returned by that card. Do not infer allowed actions from type alone. Server-authoritative actions are what keep virtual diffs and exports non-mutating by default. ## Tools exposed [#tools-exposed] ### Prepared Work [#prepared-work] | Tool | Purpose | | ------------------------------- | ---------------------------------------------------------- | | `vaner.prepared_work.dashboard` | Unified Prepared Work dashboard for UI-safe cards. | | `vaner.work_products.list` | Diagnostic list of prepared artifacts. | | `vaner.work_products.inspect` | Inspect body, evidence, warnings, and allowed actions. | | `vaner.work_products.export` | Export ready content or patch payload without applying it. | | `vaner.work_products.dismiss` | Hide a prepared artifact from normal feeds. | | `vaner.work_products.feedback` | Record usefulness feedback. | ### Resolve and navigation [#resolve-and-navigation] | Tool | Purpose | | ------------------- | ---------------------------------------------------------------------- | | `vaner.status` | Health and readiness smoke test. | | `vaner.resolve` | Resolve a prompt into prepared briefing, evidence, and optional draft. | | `vaner.suggest` | Likely next prompts or work directions. | | `vaner.search` | Search Vaner's scenario graph. | | `vaner.expand` | Deepen precompute around a scenario or target. | | `vaner.inspect` | Inspect one scenario/evidence record. | | `vaner.explain` | Human-readable rationale for a resolution. | | `vaner.feedback` | Feedback for resolution/scenario flows. | | `vaner.warm` | Hint Vaner to precompute around selected targets. | | `vaner.debug.trace` | Diagnostic trace data. | ### Predictions and workspace goals [#predictions-and-workspace-goals] Predictions remain available for diagnostic and advanced clients, but Prepared Work is the normal user-facing surface. | Tool | Purpose | | ----------------------------- | ------------------------------------------------------------ | | `vaner.predictions.active` | List ready/drafting predictions. | | `vaner.predictions.adopt` | Adopt a specific prediction as the current intent. | | `vaner.predictions.dashboard` | Diagnostic prediction dashboard. | | `vaner.goals.list` | List workspace goals. | | `vaner.goals.declare` | Declare a new user-authoritative goal. | | `vaner.goals.update_status` | Move a goal between active, paused, abandoned, and achieved. | | `vaner.goals.delete` | Delete a goal. | ### Setup, policy, sources, artifacts, and Deep-Run [#setup-policy-sources-artifacts-and-deep-run] | Tool family | Purpose | | ---------------------- | --------------------------------------------------------------- | | `vaner.setup.*` | Setup questions, recommendations, apply flow, and setup status. | | `vaner.policy.show` | Current policy bundle and posture. | | `vaner.artefacts.*` | List/inspect/status/influence controls for stored artifacts. | | `vaner.sources.status` | Source health/status. | | `vaner.deep_run.*` | Start, stop, inspect, list, and default Deep-Run sessions. | All tools are scoped to the `--path` Vaner was started with. ## Want to wire it up? [#want-to-wire-it-up] * [Connect your AI client](/integrations/connect-your-client), one command per client, picker for manual setup. * [Backends](/backends), pick the LLM Vaner ponders with. ## When to use MCP vs other modes [#when-to-use-mcp-vs-other-modes] * **MCP mode**: your IDE orchestrates model calls and needs Vaner-provided Prepared Work/context. Recommended default. * **[Proxy mode](/integrations/proxy)**: tools that only speak the OpenAI `/v1/chat/completions` shape. * **[Context-only mode](/integrations/context-only)**: frameworks that call `/v1/context` directly. * **[Python SDK](/integrations/python-sdk)**: custom scripts. --- # Proxy Mode (/integrations/proxy) > \[!TIP] > If your client supports MCP tools, use [MCP mode](/integrations/mcp) instead. > Proxy mode is a compatibility fallback for OpenAI-only clients. ## Start the proxy [#start-the-proxy] ```bash vaner proxy --path . --host 127.0.0.1 --port 8471 ``` ## Minimal client config [#minimal-client-config] Point your OpenAI-compatible client to: * Base URL: `http://127.0.0.1:8471/v1` * API key: any non-empty string if your client requires one ## Quick test [#quick-test] ```bash curl -s http://127.0.0.1:8471/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model":"vaner", "messages":[{"role":"user","content":"where is auth enforced?"}] }' ``` Use proxy mode when the tool only understands `/v1/chat/completions` and you want context injection transparently. --- # Python SDK Mode (/integrations/python-sdk) > \[!TIP] > Prefer [MCP mode](/integrations/mcp) for interactive IDE agents. Use SDK mode > when you are writing your own automation code. Install from source or package first, then call Vaner directly: ```python from vaner import api package = api.query("review auth middleware", ".", client_id="agent-a") print(package.injected_context) ``` ## Good fit for SDK mode [#good-fit-for-sdk-mode] * CI checks that need deterministic context assembly * migration/review scripts that run outside an IDE * custom orchestration where you own prompt/model execution