vibe-coding

Overview

Use vibe-client as the control surface for remote development sessions. Prefer CLI commands with --json so results are easy to inspect and reuse in follow-up steps.

Use bundled Node scripts when you want deterministic cross-platform execution instead of manually reassembling commands:

• scripts/check-vibe-client.js checks whether vibe-client is installed and whether version, list --json, and server --json respond within a timeout.
• scripts/open-vibe-coding.js resolves vibe-client, reuses or creates an instance for a directory, optionally reconnects, and optionally opens the result in a browser.
• scripts/lib-vibe-client.js provides shared path resolution, command execution, JSON parsing, directory normalization, and token redaction helpers.

Core workflow

1. Confirm the target project directory.
2. Run node scripts/check-vibe-client.js first when availability is uncertain.
3. Check existing instances first with vibe-client list --json.
4. If an instance for that directory already exists, reuse it.
5. If no instance exists, create one with vibe-client create <directory> --json.
6. Inspect the instance with vibe-client status <pid> --json.
7. If the tunnel is disconnected, run vibe-client reconnect <pid> --json and re-check status.
8. Open the remote/local entry URL with vibe-client open <pid> when the user wants the service opened in a browser.

Command selection

Open or reuse a remote dev service

Preferred deterministic path:

node scripts/open-vibe-coding.js --directory 'H:/workspace/project' --reconnect-if-needed

Equivalent manual sequence:

vibe-client list --json
vibe-client create <directory> --json
vibe-client status <pid> --json
vibe-client open <pid>

Decision rules:

• Reuse a running instance when its directory matches the requested path.
• Prefer the instance url from status when available; it represents the remotely reachable/tunneled address.
• If status returns no url, the local fallback is usually http://127.0.0.1:<port>.

Inspect current sessions

Use either:

node scripts/check-vibe-client.js

or:

vibe-client list --json
vibe-client status <pid> --json

Check these fields when present:

• pid
• directory
• status
• port
• url
• sessionId
• tunnelStatus
• health.healthy
• health.version

Recover a broken session

Use:

vibe-client reconnect <pid> --json
vibe-client status <pid> --json
vibe-client server --json

If reconnect fails:

• Verify server connectivity with server --json.
• Confirm the client still has a valid local token/session context.
• If the instance is unhealthy or missing, recreate it from the project directory.

Manage proxy settings

Only change proxy settings when the user asks or networking makes it necessary.

Use:

vibe-client proxy --json
vibe-client proxy --enable <url>
vibe-client proxy --disable

Proxy settings affect future instance creation by injecting HTTP_PROXY / HTTPS_PROXY.

Script usage

scripts/check-vibe-client.js

Purpose:

• resolve the installed vibe-client executable
• verify the binary responds to version
• probe list --json
• probe server --json
• return one JSON report with per-check success/failure

Example:

node scripts/check-vibe-client.js 20

scripts/open-vibe-coding.js

Purpose:

• normalize a target directory
• resolve vibe-client
• reuse an existing instance for the same directory when possible
• otherwise create a new instance
• fetch status
• optionally reconnect when tunnel state is not connected
• optionally open the result in the browser

Examples:

node scripts/open-vibe-coding.js --directory 'H:/workspace/component-h5/vibe-client-tauri' --reconnect-if-needed
node scripts/open-vibe-coding.js --directory 'H:/workspace/component-h5/vibe-client-tauri' --reconnect-if-needed --no-open

Operating rules

• Prefer --json for any command whose output needs to be parsed or reasoned about.
• Treat create as idempotent only after checking list; do not blindly create duplicates for the same directory.
• Avoid quit unless the user explicitly wants the whole Vibe app closed.
• Avoid stop <pid> unless the user explicitly asks to stop an instance.
• Use exact project paths, especially on Windows.
• When the user says “open remote dev” and gives only a directory, default to: list → create/reuse → status → reconnect if needed → open.

Troubleshooting

vibe-client command is missing

The desktop app normally installs vibe-client into PATH after launch. If the command is missing:

1. Ask whether Vibe Client desktop has been launched at least once.
2. If needed, have the user open the desktop app first.
3. Retry the CLI command.

Daemon is not ready

The CLI normally auto-starts the GUI and waits up to 20 seconds for the daemon. If commands still fail, retry once, then inspect desktop startup/logging before proceeding.

Tunnel remains disconnected

1. Run vibe-client status <pid> --json
2. Run vibe-client reconnect <pid> --json
3. Run vibe-client server --json
4. If still broken, recreate the instance from the target directory

opencode is not installed

create depends on a working opencode command or the home-installed fallback. If missing, fix the local opencode installation before retrying.

References

• Read references/vibe-client-cli.md when you need command semantics, output shapes, or daemon behavior details.
• Read scripts/lib-vibe-client.js, scripts/check-vibe-client.js, and scripts/open-vibe-coding.js before patching or extending the execution flow.