W Code

SSH-first Codex launcher with local-or-remote workspace picking.

This repository provides an SSH-first toolkit for running Codex locally or over SSH in a clean, efficient, open-source-friendly way.

MIT licensed. Built for fast reconnects, clean operator workflows, and straightforward self-hosted SSH setups.

The design goals are simple:

• Codex should feel native inside an SSH workflow.
• Interactive sessions should be fast and reusable.
• Operational files should live in the places SSH users expect.
• The repository should stay easy to review, fork, and extend.

What this gives you

• A reusable tmux-backed Codex session launcher.
• A local wcode entrypoint that asks Folder or SSH.
• A remote workspace selector for SSH sessions.
• A clean install script for user-level deployment.
• A macOS Apple Silicon app build and installer.
• An environment file template for host-specific tuning.
• Ready-to-copy SSH integration snippets for sshd and authorized_keys.
• A remote benchmark script for validating SSH behavior on a real host.
• Documentation for structure, rollout, and merge strategy.

Repository layout

bin/
  wcode
  wcode-ssh
  wcode-ssh-attach
  wcode-ssh-select-workspace
  codex-ssh
  codex-ssh-attach
  codex-ssh-select-workspace
  codex-open
config/
  env/
  ssh/
docs/
  architecture.md
  merge-strategy.md
scripts/
  doctor.sh
  install.sh

Recommended flow

1. Install the scripts and config template.
2. Tune the env file for your host.
3. Hook SSH into bin/codex-ssh with either ForceCommand or authorized_keys command=....
4. Connect over SSH and land directly in a persistent Codex session.
5. In selection mode, choose the remote folder first and then attach to the matching session.

Quick start

./scripts/install-macos.sh
$EDITOR "$HOME/Library/Application Support/W Code/w-code.env"
./scripts/doctor.sh
~/.local/bin/wcode

To build the macOS app bundle:

./scripts/build-macos-app.sh
open "dist/W Code.app"

To benchmark the full flow against a real SSH host:

./scripts/benchmark-ssh.sh winstwaker-server

If you want SSH logins to open Codex directly, use one of the examples from config/ssh/.

Main runtime behavior

bin/wcode does the following:

• shows a first choice between Folder and SSH
• for Folder, lets you pick a local directory and starts local Codex there
• for SSH, lets you pick a configured SSH host and then a remote folder
• launches the remote wcode-ssh session for that chosen folder
• supports --last, --mode, --host, --local-dir, and --remote-dir

This matches the flow of choosing a host first and then a folder on that SSH host.

bin/wcode-ssh does the following:

• loads config from ~/.config/codex-ssh/codex-ssh.env
• prefers CODEX_SSH_SELECTED_WORKSPACE when the caller already chose a remote folder
• resolves a workspace from fixed config or an interactive remote selector
• creates the workspace and log directories if missing
• derives a stable tmux session name from the selected remote folder
• reuses that folder-specific session when one already exists
• starts Codex only once inside the session
• attaches the SSH client to that session
• falls back to direct execution when tmux is unavailable and CODEX_SSH_TMUX_MODE=auto

This avoids repeated startup cost and makes reconnects cheap.

Platform Support

• Local desktop and app bundle support: Apple Silicon macOS only
• Remote SSH host support: POSIX shell environments with tmux

Intel Macs are intentionally not supported for the local W Code experience.

Files to customize

• ~/.config/codex-ssh/codex-ssh.env
• config/ssh/sshd_config.d/10-codex-ssh.conf.example
• config/ssh/authorized_keys/codex-forced-command.example

Remote folder selection

If you want SSH users to pick a folder after they choose the SSH target, set:

CODEX_SSH_WORKSPACE_MODE=select
CODEX_SSH_WORKSPACE_ROOT=$HOME/projects
CODEX_SSH_WORKSPACE_DEPTH=4

The selector runs on the SSH host itself. Each chosen folder gets its own stable tmux session, so reconnecting to the same remote folder is fast.

Folder or SSH chooser

Run:

wcode

Or drive it directly:

wcode --mode SSH --host winstwaker-server --remote-dir /srv/project
wcode --last

That gives you:

1. Folder
2. SSH

If you choose SSH, the script lists hosts from your local ~/.ssh/config, connects to the chosen host, then asks that host for the remote folder list.

If the remote host keeps its config in a non-default place, set CODEX_OPEN_REMOTE_ENV_FILE.

Linux Codex install

If the SSH host does not already have the Codex CLI:

npm install -g @openai/codex

Some Linux hosts install that binary into ~/.npm-global/bin/codex. The wrapper and doctor script detect that path automatically.

Merge-friendly conventions

• runtime code lives in bin/
• operator automation lives in scripts/
• deployment examples live in config/
• longer rationale stays in docs/

That separation keeps infrastructure changes isolated and easier to evolve in a standalone repository.

Notes

• tmux is strongly recommended for persistent reconnects, but the default auto mode still works without it.
• The scripts are POSIX sh-compatible for easier portability.
• The examples assume a user-level install by default.

Read docs/architecture.md for the deeper design and docs/merge-strategy.md for repository hygiene.