Codex Companion

A private mobile companion for Codex. Browse chat history, follow AI coding progress, review approvals and control Companion-owned chats from your phone over Tailscale HTTPS.

Published by Operandi. Codex Companion is an independent tool and is not affiliated with or endorsed by OpenAI or Microsoft.

• Browse saved chats, search conversations and review recorded changes and files.
• See observed desktop activity. Continue a desktop conversation as a separate Companion-owned chat.
• Create and control Companion-owned chats with explicit model and permission choices; review approvals and stop active turns.
• Rename chats in Companion, organize favorites and labels, and adjust text size.
• Pair approved browsers over private Tailscale HTTPS. Install the dashboard on your phone's home screen, optionally enable notifications and trust a device for 30 days.

Ordinary IDE chats remain read-only saved history. Companion does not take over their live process. Model requests use your configured Codex account and permissions; provider limits and charges apply independently.

Requirements

All targets require local desktop VS Code 1.100+, Node.js 22+, working Codex access and Tailscale. Keep the computer awake with Companion and Tailscale running. Remote SSH, WSL, containers, headless Linux and Intel Macs are not included in this preview. Phone/browser push and passkey support vary by platform.

Connection and settings

The bundled PLATFORM-SUPPORT.md guide, opened by Setup Wizard when prerequisites are missing, includes Linux/macOS setup and recovery details.

The Companion icon opens a compact settings page. Choose Open full settings to use it in an editor tab. Connection holds pairing and service controls, Devices manages browser access, Settings holds startup and automatic updates, and Help contains setup and diagnostics.

Enable Start with VS Code to start an already configured service when this extension activates. It defaults off and preserves an existing running service. Windows sign-in startup is separate. Existing commands remain available in the command palette.

Connect your phone

Install Codex Companion from the Operandi publisher, then open Codex Companion: Setup Wizard. For a manually supplied preview, use Extensions > Install from VSIX with the matching platform package. Windows offers Set up with Tailscale; Linux/macOS use that private HTTPS path directly.

First setup

1. Install missing tools. Setup checks Node.js 22+, Tailscale and Codex. Windows can install missing tools after you choose Install missing tools: Codex through VS Code and Node.js/Tailscale through Windows Package Manager. Complete installer prompts, then choose Check again. Linux/macOS require manual prerequisite installation and an unlocked desktop keyring. No source checkout or npm commands are needed for users.
2. Connect Tailscale. Setup opens its sign-in command if needed. Finish signing in through your browser and choose Check again. Sign in to Codex as usual so it can access your model provider.
3. Enable private HTTPS. Choose Set up and connect phone, complete any Tailscale HTTPS consent, then choose Check again. Companion verifies the exact Serve route, configures its loopback listener, starts the service and prepares a pairing QR. Tailscale manages the certificate: no phone certificate file, Git/OpenSSL prerequisite, router forwarding or Companion firewall rule on this path. Certificate hostnames appear in public certificate records; dashboard access stays private.
4. Scan and approve. Install Tailscale on your phone and sign in with the same account (or an allowed user-owned device in your tailnet). Connect Phone has an optional Tailscale download QR. Turn Tailscale on, scan the Companion pairing QR and tap Pair this device. The address, one-time code and suggested device name are filled. On the PC click Review phone request, compare the number and choose read-only or chat control.

Keep this PC awake, Companion running and Tailscale connected. The same HTTPS address works on Wi-Fi and cellular data. Tailnet policy must allow the phone to this PC on HTTPS port 443. Tagged Tailscale devices and public Funnel requests are deliberately rejected.

The pairing QR is private, works once and expires after five minutes. Generate another if it expires. Cannot scan? Use a code instead is the fallback. An unattended request grants no access. Read-only permits saved chats and recorded files; chat control permits Companion work under the chat's existing permissions.

Returning and additional phones

Open Connect phone and generate a pairing QR for each browser or phone. Install/connect Tailscale once per phone; no repeated PC setup or certificate import.

After pairing, optionally use Chat options > Install app, enable Notifications, or Trust this device for 30 days. Passkey login starts a session of up to seven days within the fixed enrollment deadline. PC revocation removes trusted login too. Browser and installed-app sessions may differ.

Existing installations and updates

Updates preserve configuration, keys and device records. Defaults are %LOCALAPPDATA%\CodexCompanion on Windows, ~/.config/CodexCompanion on Linux (or XDG_CONFIG_HOME/CodexCompanion), and ~/Library/Application Support/CodexCompanion on macOS. After the updated extension activates, service updates apply automatically when idle unless disabled in settings. Active work prevents restarting; native Codex windows never reload automatically.

Upgrading from the local preview: the public ID is Operandi.codex-companion-vscode. Uninstall local.codex-companion-vscode, then close and reopen VS Code after active editor work finishes, and install the Operandi build. Keep the Companion data directory intact. The independent service can keep running during this change. Do not run both extensions together; the Operandi build waits while the old preview is installed.

Moving an IP setup to Tailscale HTTPS is a separate Setup Wizard action. It saves a config-before-serve-*.json backup, safely stops the service and retains keys/device records. The new browser address may require pairing again. Startup failures retain the applied configuration and report recovery; no public/LAN fallback. Reopen setup to continue after interruption. A Serve mapping can remain configured while Companion is stopped.

Setup refuses to replace an unrelated service on Tailscale HTTPS port 443 or work alongside enabled public Funnel sharing. Resolve those settings separately. Companion never resets Serve routes or edits tailnet access policy.

Troubleshooting and recovery

• Run Having trouble connecting? > Run connection checks. PC HTTPS checks do not prove physical phone reachability.
• Confirm Tailscale account/connection and tailnet permissions on the phone. Keep the PC awake. Never bypass a certificate warning.
• Use Connection for service status, Start/Stop, logs, device roles and revocation. Sign in to Codex if the runtime cannot access your account.
• Start at Windows sign-in remains optional. The PC still needs to stay awake.
• To restore an older IP setup, stop Companion safely, restore its saved configuration backup, then start it. Original CA/keys are retained. Disable only Companion's Serve mapping with tailscale serve --https=443 off if retiring it; do not reset unrelated routes.
• Before removal, stop the service, disable optional sign-in startup and remove its Serve mapping. Removing the extension does not delete private data or stop an independent service.

Advanced local Wi-Fi setup

Advanced: existing Wi-Fi / IP setup retains the legacy path. It requires Node.js, Codex and Git for Windows OpenSSL, a local CA trusted on each browser/phone and explicit Windows network/firewall approval. Transfer only phone-ca.crt, never private keys or desktop-token. Address repair keeps the CA but may require pairing at the new address. Legacy IP repair is blocked on a managed Tailscale HTTPS setup.

Daily use and development

Normal Codex starts independently. Native history can be browsed; Companion continuations are separate chats. Sends, resumes, approvals and retries remain explicit. Notifications are opt-in Web Push; physical background delivery needs device verification. Private chats and files are not cached offline.

Developers: npm ci in the repository and vscode-extension, then npm run package in vscode-extension. Run npm test and relevant npm run test:browser scenarios. The VSIX includes the dashboard/runtime and locked production dependencies; external tools install through the guided flow instead of bundled binaries.

This is a preview release. Native Windows, Ubuntu and macOS CI checks pass; clean-machine installation, real Android/iPhone sign-in, cellular access, physical passkeys and push remain separate acceptance checks.

Privacy

Companion runs on your computer and does not provide a hosted chat relay. Approved browsers receive data under their granted access. Private chats, API responses and attachments are not cached for offline use. Selected credentials use Windows DPAPI or Linux/macOS keyring-backed encryption; workspace files and Codex history are not covered by that encryption.

Optional push notifications contain generic alerts, not message text or chat titles. Push providers can observe delivery metadata. Tailscale and your configured model provider have their own data practices. Extension removal does not stop the independent service or erase local data; use the service controls before retiring it.

Contact

Support and privacy questions: rope.stone6688@eagereverest.com.

Report suspected security vulnerabilities privately to rope.stone6688@eagereverest.com. Do not post vulnerabilities, credentials, pairing codes or private chat logs publicly. Send only the minimum redacted details needed to describe the issue.

The Connection sidebar and full settings use the Companion phone/Twin C identity with a brief, reduced-motion-aware entrance. Light/dark palettes follow the selected VS Code theme category; high-contrast colors follow the host theme. An installed extension update becomes visible when VS Code next activates it; the dashboard service updates separately when idle.