AI Assisted Initialization

AI-Assisted Initialization

wip init --ai writes (or updates) wip.yml from a plain-language description instead of a template. It reads a bounded slice of your project, sends it and your description to a local AI server, then parses and validates whatever comes back with the exact same code path every other wip.yml goes through — nothing is saved without your y, and invalid output never touches disk.

wip init --ai [--url URL] [--config PATH]

There is no cloud call and no API key: --ai only ever talks to a server running on your own machine, over the same OpenAI-compatible /chat/completions and /models endpoints that Ollama and LM Studio already expose. That also means it works the same way on any machine — Copilot+ PC or not — once a model is pulled or loaded.

Configuring the server

Env var	Meaning	Default
WIP_AI_BASE_URL	The server's OpenAI-compatible base URL, including the version path	http://localhost:11434/v1 (Ollama)
WIP_AI_MODEL	The model name already pulled/loaded on that server	none — see auto-discovery below

--url URL on both wip init --ai and wip doctor overrides WIP_AI_BASE_URL for that one invocation, without touching your environment:

wip doctor --url http://localhost:1234/v1        # LM Studio's default port
wip init --ai --url http://localhost:1234/v1

The base URL must include the API version segment (/v1) — the same thing you'd pass as OPENAI_BASE_URL for any other OpenAI-compatible client. Leaving it off is the single most common way to get this stuck: see Troubleshooting below.

Model auto-discovery

If WIP_AI_MODEL is unset, wip asks the server's /models endpoint instead of guessing:

Chat-capable models found	Result
exactly one	used automatically — no WIP_AI_MODEL needed
zero	fails: "No model configured, and the server has no model loaded either."
more than one	fails and lists them, so you can pick one

Embedding models (anything with embed in the name) are excluded from the count, since they can't generate the chat completion wip needs.

$ wip doctor --url http://localhost:1234/v1
[WARN] No model configured, and the server has more than one loaded: openai/gpt-oss-20b,
       llama-3.2-1b-instruct, google/gemma-4-e2b, nvidia/nemotron-3-nano-4b, google/gemma-3-4b.
       Set WIP_AI_MODEL to the one to use, e.g. WIP_AI_MODEL=openai/gpt-oss-20b. `wip init --ai`
       will not work until then.

wip doctor runs this same check, so you find out before typing a whole description into a prompt that was never going anywhere.

Walkthrough

A small Express app with a package.json and a one-line README.md, no wip.yml yet:

$ wip doctor --url http://localhost:1234/v1
[OK] WSL2 is available
[OK] Architecture: linux/amd64
[FAIL] wip.yml was not found (searched from /home/me/notes-api to the filesystem root)
[OK] Git is available
[OK] Local AI server at 'http://localhost:1234/v1' is available (model: openai/gpt-oss-20b)

The [FAIL] is expected — that's what init --ai is about to fix. Running it:

$ wip init --ai --url http://localhost:1234/v1
Describe the development environment wip should run, then press Enter twice
(once after your text, once more on a blank line) to finish:
Node.js/Express app with Redis, listening on port 3000

wip: analyzing /home/me/notes-api
wip: sending 2 selected project files to openai/gpt-oss-20b at http://localhost:1234/v1
version: 1
mode: container
container: app
dependencies:
  app:
    image: node:20
    command: npm start
    workdir: /app
    env:
      NODE_ENV: production
    volumes:
      - .:/app
    ports:
      - "3000:3000"
    interactive: true
    remove: false
    restart: unless-stopped
  redis:
    image: redis:7
    command: redis-server --save "" --appendonly no
    ports:
      - "6379:6379"

Save this wip.yml? [y/N] y
wip: wrote /home/me/notes-api/wip.yml

Two things worth noticing:

• The blank line matters. The prompt takes multiple lines, so it needs an explicit terminator — type your description, press Enter, then press Enter again on nothing to finish. A single-line description still needs both.
• The YAML is shown before you're asked to save it. It already passed wip's own parser and Config validation by this point — review it anyway; the model can misread your intent even when it writes syntactically valid wip.yml.

Any other answer than y/yes leaves the existing file untouched:

$ wip init --ai --url http://localhost:1234/v1
...
Save this wip.yml? [y/N] n
wip: not saved

What gets sent

ProjectAnalyzer collects only an allow-listed set of filenames it finds next to the target wip.yml — README.md, Gemfile/Gemfile.lock, package.json, Procfile, compose.yml, Dockerfile, go.mod, Cargo.toml, pyproject.toml, requirements.txt, and a few others — capped at 24 files, 64 KiB per file, and 256 KiB total. .env and arbitrary source files are never collected, and an existing wip.yml is only ever included as the thing to update, appended after your description.

Troubleshooting

Missing /v1 in the URL

$ wip doctor --url http://127.0.0.1:1234
[WARN] Local AI server rejected the models request: Unexpected endpoint or method. (GET /models)
       — check that WIP_AI_BASE_URL/--url includes the API version path, e.g. '.../v1'.

The server is reachable (--url alone doesn't fail), but its OpenAI-compatible routes live under /v1. Add it: http://127.0.0.1:1234/v1.

Prompt too long for the model's context window

wip: Local AI server returned 400: {"error":"The number of tokens to keep from the initial prompt
is greater than the context length (n_keep: 9346>= n_ctx: 4096). Try to load the model with a
larger context length, or provide a shorter input."}

This is the server's model-load setting, not a wip limit. In LM Studio, reload the model with a larger Context Length (many models default to a small one like 4096 regardless of what they actually support); in Ollama, set OLLAMA_CONTEXT_LENGTH or the model's num_ctx parameter. A project with a very large README.md makes this more likely to come up, since that file counts against the same 64 KiB/256 KiB caps as everything else ProjectAnalyzer collects.

The model's YAML doesn't validate

Nothing is shown or saved — the failure comes back as a normal wip error, e.g.:

wip: container: must be set when dependencies: has entries
wip: dependencies.app must set image
wip: commands.commands must be a mapping

Smaller local models occasionally misplace a key (nesting dependencies directly under container:, or nesting commands: inside itself) even when the request itself was reasonable. Just run wip init --ai again — retrying often succeeds since generation isn't deterministic — and if it keeps failing the same way, spell out the exact shape you want in your description (naming the top-level keys, or pasting a tiny example) rather than only describing the stack in prose.

Related

• wip init
• wip doctor
• wip help — --ai, asking this same local AI server how to use wip instead of generating a wip.yml
• Interactions — what a generated interaction:/commands: block can contain
• Configuration Reference
• Configuration Errors — the validation errors above, in full