Troubleshooting

Most of what looks like a bug in vord is actually a documented limit — a codex gap, a license state, or a path that genuinely isn’t wired up yet. This page collects the ones people hit most, with the real cause and the actual fix.

Codex status or permission-mode detection feels off

Codex runs as a first-class agent in vord — same status dots, same grid, same usage-limit detection. A few things behave differently, all rooted in one fact: claude ships a hook system vord plugs into directly, while codex’s is newer and needs a one-time trust step.

A codex tile shows a “Trust all and continue” banner. codex’s own hooks only fire after you accept that prompt once in the real terminal, per project — until then, status detection falls back to a less precise, trust-free channel, and the guard against a codex tile flashing “finished” mid-turn doesn’t fully apply. Dismiss the banner with the × once you’ve trusted it (vord remembers per project), or just answer the trust prompt in the terminal. This trust step is a codex CLI requirement, not something vord can route around.
A restored codex conversation receives another prompt. After an app restart, vord reconnects both the title and the turn stream. Follow-up turns thereby immediately supersede the previous finished status; a stop event is reported as completed and not as still working.
You can’t change a codex session’s permission mode from the cockpit or the companion app the way you can with claude. codex has no Shift+Tab mode ring — its approval state comes from approval_policy × sandbox_policy, and the only way to change it is codex’s own /permissions slash command. vord can read the mode for claude and codex (a codex session in Full Access shows the same red warning as claude’s risky modes), but direct mode changes are claude-only. kimi modes aren’t tracked at all.
Plan auto-approval never triggers on a codex session. codex has no dedicated plan mode and doesn’t produce an ExitPlanMode box, so there’s nothing for the auto-pilot’s plan rule to react to. This is a codex CLI difference, not a misconfiguration.
A running Codex child says its access token could not be refreshed. vord pauses the child, marks its account sign-in pending, and tells the parent it cannot continue. Sign in again for that account, or restart the task on another account.

Full breakdown of every claude/codex difference: Claude, Codex, Kimi, OpenCode, Grok & Muse — What Differs.

The usage-limit countdown looks wrong (or says “reset unknown”)

vord shows a ⏳ status when it sees a usage-limit message — on screen or in the agent’s own records (Claude’s conversation log, Codex’s rollout file, Kimi’s wire log, Muse’s session records). Detection works for claude, codex, kimi, grok, and muse; every entry path (1-click start, resume, and typing the CLI into a shell) feeds terminal output through the same monitor. OpenCode reports its limits as typed events. A Muse subscription quota is shown only when Muse reports one; otherwise it stays unknown.

Whether you see a countdown depends on whether the reset time is backed:

Stated by the provider — claude usually prints it, current codex says “try again at …”. The countdown ticks down to that moment.
From the account’s quota data — when the message names no time but the quota windows vord already reads for that account show a used-up window (for Kimi’s 5-hour window: that window’s reset). Same clock; the tooltip adds “per quota data, as of hh:mm”.
Unknown — no stated time and no such data. The tile says “limit reached · reset unknown”; for eligible agents with Auto-Continue on, the number counts down to the next attempt, not to a promised reset. Kimi does not continue automatically. There is no flat five-hour estimate anymore.

A few more cases:

The ⏳ stays while you or vord try to continue — it only ends when the agent provably works again, or at the reset time (plus Auto-Continue’s wait) without such proof. A tile that keeps showing ⏳ right after you typed is expected: your message was an attempt, and a new rejection keeps the limit going.
A reset time that’s already in the past, or implausibly far in the future (for example from a --resume repaint of an old conversation, or an old rejection read back from an agent’s log), is treated as stale and dropped — no countdown, no auto-continue.
Limit wording that is only quoted on screen — in a diff, a string, a code comment — doesn’t trigger ⏳.

See Usage Limits & Auto-Continue.

“New sessions are locked until a license is activated”

This means your 14-day trial ran out without a license activated. vord locks back to the full-window sign-in screen — the cockpit stays hidden until an account with an active subscription or seat signs in. Settings remain reachable via ⌘,.

Open Settings → Account & System → Account & License (⌘,).
Sign in if you haven’t, or check that your account has an active seat/subscription.
If a paid seat should be active but shows lapsed, use “Re-check.”

This is different from a paid license expiring: in that case the app keeps working fully, and only Sparkle auto-updates pause until you renew. See Account, License & Trial for the full model. Renew, add seats, or Revoke device in the Hub: Plans & invoices, Devices.

iPhone or iPad won’t pair, or keeps disconnecting

Check these in order:

Are you signed in on the device? The companion app requires a signed-in vord account before the pairing step appears — if you only see a “Sign in to vord” screen, sign in (or start a free trial) first. If you paired before this requirement shipped, the app asks you to sign in once after updating; your existing pairing is kept.
Is the Mac online? Pairing requires the Mac to be connected to the relay and showing the QR code. An offline Mac times out with “is it online and showing the QR code?” rather than hanging silently.
Is this a Pro account? The companion is a Pro feature end to end — pairing is rejected server-side without an active subscription.
Are several devices paired? Two different devices (iPhone and iPad) stay paired in parallel. Untargeted updates still go to one stable default device — not whichever woke last — so pairing several can look like “drops” if you expected the last one you picked up to become the default. Close code 4409 is this same device reconnecting (token/instance collision), not a second phone taking over. And note the account cap: pairing fails outright with a device-limit error once two devices (iPhone or iPad) are paired per account and product — the limit is enforced server-side, so revoke an old device in Settings → Connections → iPhone & iPad first.
Short network blip vs. real drop: vord suppresses the reconnect banner for outages under about 1.8 seconds. Longer drops show a spinner and retry automatically with backoff (1s → 2s → … → 60s). If it ends in a displaced connection (4409, same device identity) or “pairing revoked,” you have to tap Reconnect yourself — vord won’t silently reclaim the connection.

See Pairing Your iPhone for the full pairing flow.

AI commit suggestion fails

The button shows “AI suggestion failed (claude unreachable?)” when vord can’t find a working claude CLI binary on your machine.

The AI commit-message feature runs claude headless in the background — it has nothing to do with which agent (claude or codex) your current session uses. If you don’t have the claude CLI installed at all, or it’s not on a path vord can resolve, the suggestion fails every time regardless of what session is running.

Fix: install/reinstall the claude CLI so it’s reachable on your Mac, then try again. There’s no separate API key to configure — it’s the same local binary vord uses to start claude sessions. Details: Staging & Committing.

The preview says “The page could not be loaded”

This appears when the built-in browser fails to load — a dead dev server, a DNS failure, or a TLS problem. The full message is “The page could not be loaded — is the server running?” It’s deliberately not a blank white page; you get the message plus a “Reload” button, and the raw system error is still available as a tooltip if you need it.

Confirm your dev server is actually running (npm run dev or whatever you use).
Click Reload once it’s up.

This view is purely reactive — vord doesn’t poll in the background waiting for the server to come back, so you do need to click Reload yourself. Ordinary navigation interruptions (typing a new URL mid-load, a redirect) are filtered out and won’t trigger this view. See The Built-in Browser.

A resumed session shows the wrong conversation

When you resume, vord tries to reattach to the exact conversation you were in — not just “the newest one in this folder.” If that mapping is ambiguous (for example, two claude tiles were ever opened in the same project folder), you get a conversation choice sheet listing every conversation vord found there, newest first with dates, instead of vord silently guessing.

If you’re not sure which one you want, pick the one with the most recent date and check the first-message preview in the sheet. This sheet is the safety net for ambiguity — it’s not a bug when it appears, it’s vord refusing to guess. See History & Resume.

The branch chip in the Git inspector’s header and the “Switch branch” keyboard shortcut don’t open a working popover yet — clicking the chip does nothing, and the shortcut just focuses the sidebar on the project without opening any switch UI. This is an acknowledged gap in the code, not a misconfiguration on your end.

The one path that actually works today: right-click the project in the sidebar → Switch branch → pick from the list. See Branches & Git Sync.

A spawn option is greyed out

vord only enables Codex, Kimi, Grok, OpenCode, or Muse in the project’s spawn menu when it can find the matching CLI installed on your machine. If it’s greyed out (tooltip: “Codex is not installed on this Mac.” / “Kimi is not installed on this Mac.” — and the same idea for Grok, OpenCode, and Muse), that binary isn’t on a path vord can resolve — install it, then reopen the menu (no restart needed). For Muse, install Muse Code from Meta (muse, typically ~/.local/bin/muse) and run muse login once. See Starting Sessions.

OpenCode stopped responding

An OpenCode 1.x server can hang during a long reasoning response: its process remains running, but it no longer answers requests, so vord stops receiving events. vord tries to reconnect first. For an OpenCode child started by an agent, vord can restart the hung server and resume the same session automatically once per 30 minutes; the interrupted answer is lost, and the parent is notified. If another hang happens within that window, vord asks you to resume the session yourself and tells the parent it did not restart it.

For a top-level vord session, the notice names the affected session: The OpenCode connection of “<name>” ended unexpectedly. End and resume the session to reconnect. End that session, then resume it. If the server still answers and only the event stream disconnected, vord reconnects the stream quietly.

In measurements, the free model opencode/mimo-v2.6-flash-free hung much more often. To keep automatic model selection from choosing it for child sessions, turn it off under Settings → Models → Allowed. This does not affect your own model choice.

Unsupported OpenCode version

vord supports OpenCode 1 and OpenCode 2. With a newer major version installed, OpenCode sessions do not start and show a message.

The fix is to install a supported version: curl -fsSL https://opencode.ai/install | bash puts the latest OpenCode 1 into ~/.opencode/bin. If the newer version was installed elsewhere in PATH, remove that copy first. Check with opencode --version — it should print a 1.x or 2.x version.

OpenCode does not list sessions from vord

With OpenCode 2, vord stores its sessions in its own database, vord.db in OpenCode’s data folder. An opencode you start outside vord uses OpenCode’s regular database and therefore does not list them. This is intentional: otherwise OpenCode’s background service could take over a session that vord is running and do the same work twice. Resume the session in vord instead.