/setup

name: setup
description: >
  Frictionless Wenlan setup for Codex. Detects a missing local runtime, installs
  or repairs it, and verifies the plugin to MCP to local runtime round-trip. Run
  when the user says "set up wenlan", "is wenlan working", or "fix wenlan".
allowed-tools: ["Bash", "mcp__wenlan__brief"]
user-invocable: true

/setup

Self-healing setup for Codex. Default backend is local memory: no local model, no API key, no prompt ceremony. Local model and Anthropic key are optional upgrades after the basic path works.

Steps

Run in order. Stop and report at the first failure that needs human attention. Otherwise, push through automatically.

1. Health probe

for i in 1 2 3; do
  curl -fsS -m 3 http://127.0.0.1:7878/api/health && break
  sleep 1
done

• 200 OK: continue to version drift probe.
• Anything else: continue to bootstrap.

2. Version drift probe

Compare daemon version vs plugin manifest version:

PLUGIN_JSON="${CODEX_PLUGIN_ROOT:-plugin-codex}/.codex-plugin/plugin.json"
[ -r "$PLUGIN_JSON" ] || PLUGIN_JSON=".codex-plugin/plugin.json"
if command -v python3 >/dev/null 2>&1 && [ -r "$PLUGIN_JSON" ]; then
  RESP="$(curl -fsS -m 3 http://127.0.0.1:7878/api/health)"
  DAEMON_VER="$(printf '%s' "$RESP" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("version",""))')"
  EXPECTED_VER="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("version",""))' "$PLUGIN_JSON")"
  RELEASE_VER="${EXPECTED_VER%%+*}"
  printf 'daemon=%s expected=%s release=%s\n' "$DAEMON_VER" "$EXPECTED_VER" "$RELEASE_VER"
else
  echo "version_check=skipped"
fi

• Same version: continue to doctor.
• If the probe cannot run because the runtime is down: continue to bootstrap.
• If `PLUGIN_JSON` is unreadable or `python3` is missing: continue to doctor;

Codex will keep using this slice until the plugin cache is updated.

• If mismatch, check the direction before repairing. Compare the release part

of `daemon=` (strip the `+g<sha>` suffix) against `release=`, numeric per component, not lexicographic. Daemon release equal or newer → the plugin cache is stale, not the runtime: skip the repair below (it would only reinstall the same-or-latest runtime and restart a healthy daemon) and go straight to the stop message in step 4 — update the plugin, restart, rerun.

• Only if the daemon release is older than the plugin release, repair the

runtime:

PLUGIN_JSON="${CODEX_PLUGIN_ROOT:-plugin-codex}/.codex-plugin/plugin.json"
[ -r "$PLUGIN_JSON" ] || PLUGIN_JSON=".codex-plugin/plugin.json"
EXPECTED_VER="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("version",""))' "$PLUGIN_JSON")"
RELEASE_VER="${EXPECTED_VER%%+*}"
curl -fsSL https://raw.githubusercontent.com/7xuanlu/wenlan/v${RELEASE_VER}/install.sh | bash
export PATH="$HOME/.wenlan/bin:$PATH"
wenlan setup --basic
wenlan background on

Then continue to the health and version re-probe below. The installer deliberately targets the latest stable runtime. Do not downgrade a newer runtime to match a stale plugin cache.

3. Bootstrap

Detect whether the `wenlan` CLI is on PATH:

command -v wenlan >/dev/null 2>&1 && echo present || echo absent

If absent, install and configure local memory:

curl -fsSL https://raw.githubusercontent.com/7xuanlu/wenlan/v0.18.8/install.sh | bash
export PATH="$HOME/.wenlan/bin:$PATH"
wenlan setup --basic
wenlan background on

If present but the local runtime is down:

wenlan setup --basic 2>/dev/null || true
wenlan background on

`wenlan setup --basic` is idempotent. `wenlan background on` starts the managed background process.

4. Re-probe health and version

If `wenlan background on` exited non-zero, print its output and stop: it already waited for the daemon and named what went wrong. Otherwise poll for up to 240 seconds, the budget the first-run checks use, because a first boot downloads the embedding model (about 210 MB) before it answers:

healthy=
deadline=$((SECONDS + 240))
while [ "$SECONDS" -lt "$deadline" ]; do
  if curl -fsS -m 3 http://127.0.0.1:7878/api/health >/dev/null 2>&1; then
    healthy=1
    break
  fi
  sleep 1
done
if [ -z "$healthy" ]; then
  W="$(command -v wenlan || echo "$HOME/.wenlan/bin/wenlan")"
  "$W" doctor
  exit 1
fi

When the loop ends without a healthy answer, the doctor output names the daemon state and where its logs are (a file path on macOS, `journalctl` on Linux); stop there. Likely causes: the model download is still running or failed, launchd load failure, port 7878 already in use, or a local runtime crash.

Once healthy, repeat the version comparison from step 2. If the versions still differ, stop instead of claiming setup succeeded:

Runtime and plugin versions still differ after repair; update the Wenlan plugin,
restart Codex, then run /wenlan:setup again.

This usually means the runtime is newer than the plugin cached by the current Codex process. Updating the plugin is safer than silently downgrading the runtime, and the restart is required before this session can load new plugin code.

5. Doctor

Run the Wenlan CLI doctor through the resolved binary path:

W="$(command -v wenlan || echo "$HOME/.wenlan/bin/wenlan")"
"$W" doctor

Expected: local memory configured. Capture the mode string for the final report.

6. MCP round-trip

Call the Wenlan MCP `brief` tool as a read-only round-trip.

brief()

If it fails, report: "wenlan-mcp did not respond through Codex. Start a new Codex thread after reinstalling the plugin so Codex respawns the MCP server."

7. Ready report

Print:

Wenlan ready.
  Runtime:  up on 127.0.0.1:7878
  Mode:     <mode from CLI doctor>
  MCP:      connected
  Data:     ~/.wenlan/
  Try:      /brief, /capture <thing>

Optional upgrades

Mention these only if the user asks for richer synthesis:

• `wenlan models install` for local model-backed di