/use-avibe

name: use-avibe
slug: use-avibe
description: Safely inspect and modify local Avibe configuration, routing, runtime settings, watches, scheduled tasks, Avibe Cloud remote access, and operational state.
version: 0.5.0

Use Avibe

Use this skill when the user asks you to configure, repair, explain, or operate a local Avibe installation.

Typical requests include:

• enable a Slack, Discord, Telegram, Lark/Feishu, or WeChat scope
• route one channel or DM user to OpenCode, Claude, or Codex
• set a working directory for a channel or DM user
• choose a backend model, subagent, or reasoning level
• show or hide intermediate message types
• configure an outbound proxy (`proxy_url`) for an IM platform that cannot reach its API directly
• pair, start, stop, or inspect Avibe Cloud remote Web UI access
• create, update, inspect, pause, resume, or remove a managed background watch with `vibe watch`
• create, inspect, run, pause, resume, or remove a scheduled task with `vibe task`
• run a one-shot Agent job with `vibe agent run`, including async background runs
• inspect or cancel concrete Agent Run records with `vibe runs`
• check or apply Avibe updates (`vibe check-update`, `vibe upgrade`)
• inspect logs, run doctor, check service status, or explain where Avibe stores state
• decide whether a requested change belongs in Avibe config or in the host backend's own config

Follow this skill as an operations playbook for agents, not as end-user marketing copy.

Core Rules

1. Prefer the Web UI API for Avibe configuration changes. Do not hand-edit config files for routine work. 2. Read current API state before mutating. Merge the user's requested change into the current payload. 3. Preserve unrelated scopes, platforms, users, and secrets. 4. Treat secrets as opaque. Do not print, invent, rotate, or overwrite tokens unless the user explicitly provides replacements. 5. Use the smallest viable API call and verify by reading back the API response. 6. For `POST /settings`, preserve every existing channel for that platform; the endpoint replaces the platform's channel map. 7. For `POST /api/users`, merge each edited user with its current user payload first; missing user fields are not a patch. 8. Make every persistent-state change through the Web UI API or the `vibe` CLI. Avibe's internal storage is opaque — do not read, query, or hand-edit it. 9. `POST /config` persists the new payload but does not restart running platform adapters by itself. When the change is platform credentials, `proxy_url`, or other transport-level settings, plan an explicit restart afterwards; prefer the delayed CLI form (`vibe restart --delay-seconds 60`) when triggering it from inside an active conversation. The only credential save that restarts on its own is the WeChat QR-login completion through `POST /wechat/qr_login/poll`. 10. Do not restart the service by default. Use `POST /doctor`, `GET /status`, and read-back checks first. 11. Only start, stop, restart, or reload Avibe when the user explicitly asks or when a change cannot take effect otherwise; explain why before doing it. 12. If an agent must restart Avibe from an active conversation, use `vibe restart --delay-seconds 60` so the current session can receive the reply before the restart lands. 13. Tell the user whether the change is global or scope-specific.

API First Workflow

Use this order when changing Avibe configuration:

1. Determine the Web UI base URL.

• Default is `http://127.0.0.1:5123`.
• If the user has a custom UI host or port (from `ui.setup_host` / `ui.setup_port`), use that exact origin.
• When Avibe Cloud remote access is active, the public origin (e.g. `https://<slug>.avibe.bot`) also speaks the same API and requires OIDC session cookies — prefer the local origin from the host running Avibe.
• Check liveness with `GET /health` or `GET /status`.

2. Decide whether the request belongs in:

• `POST /config` for global defaults, platform credentials, runtime config, agent defaults, UI config, remote-access provider settings, update policy, or global display toggles
• `POST /settings` for channel-level routing, working directory, visibility, enablement, and mention policy
• `/api/users` and `/api/bind-codes` for DM user binding and user-scope settings
• `/remote-access/*` for Avibe Cloud pairing and tunnel control
• host backend config instead of Avibe when the request is OpenCode, Claude Code, or Codex native behavior

3. Fetch the current state from the matching GET endpoint. 4. Merge the requested change in memory. 5. Send the mutating request through the Web UI API with CSRF protection. 6. Read back the changed resource and verify the effective payload. 7. Run `POST /doctor` only when the change affects runtime health, platform credentials, or backend availability. 8. Report the changed scope or global keys and whether a restart was avoided or still required.

Calling the Web UI API

Mutating API calls require:

• same-origin `Origin` or `Referer` header
• CSRF cookie named `vibe_csrf_token`
• matching `X-Vibe-CSRF-Token` header

Use this local curl pattern:

BASE="http://127.0.0.1:5123"
COOKIE_JAR="$(mktemp)"
CSRF="$(
  curl -fsS -c "$COOKIE_JAR" "$BASE/api/csrf-token" \
    | python3 -c 'import json,sys; print(json.load(sys.stdin)["csrf_token"])'
)"

curl -fsS -b "$COOKIE_JAR" -c "$COOKIE_JAR" \
  -H "Origin: $BASE" \
  -H "X-Vibe-CSRF-Token: $CSRF" \
  -H "Content-Type: application/json" \
  -X POST "$BASE/doctor" \
  --data '{}'

For `DELETE`, use the same cookie jar, `Origin`, and CSRF header.

When the Web UI is served through Avibe Cloud, the same calls require an authenticated OIDC session cookie issued by `/auth/callback`. Prefer hitting `127.0.0.1:5123` directly from the local machine for maintenance work.

Do not log full request bodies when they contain tokens or secrets.

Reusable local API helper

For multi-step maintenance, use the bundled helper at `scripts/vibe_api.py` instead of hand