The support layer for Codex Mobile: session snapshots, tracked previews, latest ngrok links, desktop screenshots, proof bundles, project memory, final-flow gates, and phone-readable handoffs.
MobileCodex helps Codex users keep real software work moving from a phone. It teaches Codex to inspect the repo, run the right commands, start and track local preview servers, surface the latest ngrok link when one is running, capture desktop screenshots and logs, bundle proof, and hand back the useful state in chat.
No "check your terminal." No mystery localhost. No giant log dumps. Just the current state, the change, the preview, the proof, and the next useful move.
MobileCodex is designed for natural requests, not memorized commands. After the skill is installed, short prompts should be enough:
Show me the website.
Codex should infer that you want the app started if needed, setup checked if needed, a local preview verified, the latest ngrok phone URL when safe or already running, a desktop screenshot/proof artifact, and a compact handoff.
Other useful natural requests:
- "Can I open this on my phone?"
- "Fix the failing test and show proof."
- "Does it look right on mobile?"
- "What is running right now?"
- "I'm stepping away, leave me the state."
- Continue from a phone: Codex Mobile becomes the control surface while the workspace stays on the development machine.
- See real state: Snapshot branch, dirty files, candidate commands, ports, servers, recent proof, and next references.
- Trust previews: Start tracked local servers, verify URLs, capture desktop screenshots for chat, and expose or reuse ngrok only when safe.
- See both views from a phone: Open the ngrok link for the live mobile-responsive view, and review the posted desktop screenshot for the wider layout.
- Keep proof: Save screenshots, logs, changed files, command output, and server state into one reviewable bundle.
- End cleanly: Run a final-flow gate that checks preview, test result, proof artifact, proof bundle, project memory, and ngrok status before the final response.
- Remember the project: Store preferred commands, preview ports, package manager, ngrok domain, and stack quirks in local
.mobilecodex/memory. - Resume cleanly: End every session with result, preview, proof, state, and next action.
- Codex Mobile handoff workflow
- Mobile preview workflow
- Server registry
- UX proof examples
- Proof bundle examples
MobileCodex is especially useful to test with real Codex Mobile workflows. Feedback is welcome from:
- people using Codex Mobile away from their laptop
- developers who need local previews visible from a phone
- skill authors building repeatable Codex workflows
- teams that need proof artifacts and resumable handoffs
Open an issue using the templates in this repo, or start a discussion with the prompt, project type, what worked, what failed, and what proof would have made the handoff easier to trust.
MobileCodex is built as the practical partner workflow for Work with Codex from anywhere and Codex Mobile. Codex Mobile gives you access to the live development environment from your phone; this skill makes that environment behave like a continuous, inspectable work session instead of a black box.
Use it when your phone is the control surface and Codex needs to:
- inspect the repo before asking questions
- run safe commands and summarize the output
- start local servers and report their status
- create an ngrok phone preview when safe
- capture browser proof and screenshots
- keep local state visible while work continues
- create session snapshots, proof bundles, and registered server handoffs
- return a compact mobile handoff
Before relying on phone previews, run setup once on the machine Codex controls:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py setup --root .Setup checks the practical pieces that make away-from-laptop work dependable:
- Python, Node/npm, and git availability
ngrokinstallation and local authtoken configuration- Playwright/browser proof tooling
- common preview ports
- session snapshot readiness
- server registry health
- proof directory health
- installed skill copy drift
- project memory and context-cache readiness
- mobile UX proof readiness
- required skill files and Codex skill validation when the local validator exists
- README install path and first-time setup copy
If something is missing, setup reports the blocker in the same mobile handoff style Codex should use later. For example, if ngrok is not installed or authenticated, it explains that you need an ngrok account, the local ngrok agent, and ngrok config add-authtoken <token> before public phone previews can work.
MobileCodex uses ngrok when a user needs to open a local preview from a phone. Set it up once on the machine Codex controls:
- Visit https://dashboard.ngrok.com/get-started/setup/mac-os.
- Sign in or create an ngrok account.
- Install or update the ngrok agent. MobileCodex setup expects ngrok
3.20.0or newer. - Copy your authtoken from the dashboard.
- Run:
ngrok config add-authtoken <token>After setup passes and a local preview is running, ask Codex for a phone URL. MobileCodex should start ngrok, extract the real HTTPS forwarding URL, verify that URL responds, and then include it in the handoff.
MobileCodex should make both views inspectable without a laptop:
- Mobile view: open the latest ngrok URL on the phone. If ngrok is already running for the project, Codex should always include the latest link.
- Desktop view: read the desktop screenshot posted in chat. MobileCodex posts desktop screenshots by default because the phone can already show the responsive mobile view through ngrok.
Mobile screenshots are reserved for explicit mobile layout diagnostics.
Most coding workflows assume you can see the desktop, browser, terminal, and file tree. MobileCodex flips that assumption.
Codex should do the local work itself, then bring the important evidence back to you:
- runnable commands and exit codes
- concise stdout/stderr summaries
- browser screenshots for visual changes
- local server status and ports
- session snapshots for resumable state
- server registry entries with PID, port, URL, and log path
- proof bundles with screenshots, logs, changed files, and snapshot state
ngrokphone previews with real URL extraction when safe- latest running ngrok links included automatically in preview handoffs
- desktop screenshots posted to chat so mobile users can inspect the wider layout
- exact blockers when previewing is not possible
- final handoffs that are short enough to read on the go
Every meaningful handoff should answer four things:
Result: what changed, ran, or was created
Preview: what you can open or inspect from your phone
Proof: commands, screenshots, logs, exit codes, or artifact paths
Next: the 1-3 most useful follow-up options
That simple contract is the product. It keeps Codex accountable, keeps you unblocked, and makes remote development feel continuous instead of blurry.
This is the kind of final response MobileCodex is designed to produce: short, proof-backed, and readable from a phone.
Done.
Removed:
- `Work keeps moving while you are away`
Updated the palette:
- `#ffafcc` Blush Pop: primary CTA gradient lead
- `#ffc8dd` Pastel Petal: CTA softness and glass highlight
- `#a2d2ff` Sky Blue: icon/interactive accent
- `#bde0fe` Icy Blue: proof/preview border accents
- `#cdb4db` Pink Orchid: glass borders and ambient depth
Verification passed with MobileCodex final-flow:
- Preview: https://website.ngrok-free.dev
- Proof bundle: proof/mobilecodex-YYYYMMDD-HHMMSS/proof.md
The important part is the shape: result first, exact change, latest preview link, desktop screenshot proof, and proof bundle path.
Codex Mobile is the control surface; the workspace stays on the machine Codex is already using. This skill pushes Codex to:
- keep working unless approval, sensitive exposure, destructive side effects, or a real blocker stops it
- make local state visible in chat with URLs, screenshots, output, paths, ports, process status, and errors
- label previews and artifacts so multiple mobile Codex sessions stay easy to distinguish
- leave incomplete work resumable with workspace, branch, changed files, running servers, last proof, last failure, and next action
- ask only targeted approval questions that can be answered from a phone
Ask Codex to install the skill from GitHub:
install the MobileCodex skill from https://github.com/spduk/mobilecodex
Or install with the Skills CLI:
npx skills add SPDUK/MobileCodex --skill mobile-codex-devCodex should place the installed skill under a local Codex skills directory such as ~/.agents/skills/mobile-codex-dev or ~/.codex/skills/mobile-codex-dev, depending on the Codex install being used.
Then restart Codex and ask normally. A first request like this should trigger setup automatically when readiness is unknown:
Show me the website.
Or:
Can I open this project on my phone?
MobileCodex is packaged as an open agent skill at skills/mobile-codex-dev/SKILL.md. Skill directories and tools such as find-skills and skills.sh discover it through:
- the public GitHub repository URL:
SPDUK/MobileCodex - the skill name:
mobile-codex-dev - the
SKILL.mdfrontmatter description agents/openai.yamlinterface metadatallms.txt, README copy, GitHub topics, and the landing page metadata
Best search terms: Codex Mobile, mobile codex, phone preview, ngrok preview, desktop screenshot from phone, remote coding agent, proof bundle, session handoff, UX proof, and project memory.
To check how discovery currently sees the repository:
npx skills add https://github.com/SPDUK/MobileCodex --skill mobile-codex-dev --list
npx skills find "mobile codex"
npx skills find "phone preview ngrok"Users should ask for the outcome they want. MobileCodex maps that intent to setup, preview, proof, memory, and handoff commands.
| Natural request | What MobileCodex should infer |
|---|---|
| "Show me the website." | Start or reuse the app, verify it locally, capture desktop UX proof, and provide the latest ngrok phone link when safe or already running. |
| "Can I open this on my phone?" | Check setup/ngrok readiness, expose the running preview safely, and report the public URL plus proof. |
| "Does it look right on mobile?" | Provide the live ngrok link for the mobile view, capture a desktop screenshot for chat, and summarize console/network status. |
| "Fix the failing test." | Run the focused failing command, patch the issue, rerun proof, and summarize exit codes. |
| "What is going on?" | Snapshot branch, dirty files, servers, ports, recent proof, and suggested next actions. |
| "Bundle this up." | Create a proof bundle and final handoff so the session is resumable later. |
| "Remember how this project runs." | Save stable dev/test commands, port, package manager, and stack quirks in .mobilecodex/. |
Run the capability menu any time you want the current list of MobileCodex actions:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py menuThe menu is designed for phone handoffs. It shows the intent, what helper command Codex can run behind the scenes, and what proof or state comes back.
| Natural request | What Codex should do | Helper command |
|---|---|---|
| "What is going on?" | Summarize workspace, branch, changed files, ports, servers, recent proof, and suggested references. | snapshot --root . |
| "Show me the website." | Start a tracked local server with PID, port, URL, command, and log path; then verify and expose if safe. | server-start --root . --name app --port <port> -- <cmd> |
| "What previews are still running?" | List MobileCodex-owned preview servers and status. | server-list --root . |
| "Does it look right on mobile?" | Save a desktop screenshot for chat, plus browser evidence when local Playwright is available. | ux-proof --root . --url <local-url> |
| "Bundle this up." | Create one proof.md with snapshot state, artifacts, logs, changed files, and server state. |
proof-bundle --root . |
| "Can this machine do phone previews?" | Run readiness checks for runtimes, ngrok, proof tooling, registry health, proof storage, and skill drift. | setup --root . |
| "Can I open this on my phone?" | Start ngrok only after local verification and safety checks, then report the real forwarding URL. | ngrok-preview --port <port> |
| "Where did we land?" | Produce a compact Result / Preview / Proof / State / Next handoff. | handoff ... |
| "Check everything before you stop." | Gate the final response on preview/proof/test state, refresh memory, and bundle proof. | final-flow --root . --ui-work --test-result "<result>" |
| "Remember how this project runs." | Persist preferred commands, preview port, package manager, ngrok domain, and stack quirks. | memory-update --root . ... |
| "Save tokens next time." | Write a compact local project context cache from memory and current snapshot. | context-cache --root . |
| "Check for MobileCodex updates." | Compare this checkout with upstream and installed skill copies; optionally sync installed copies. | version-check --root . --update-installed |
For meaningful work, especially UI work, ask Codex to run the final-flow gate before the final response:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py final-flow --root . --ui-work --test-result "npm run build exited 0"The gate reuses a running MobileCodex preview server, reuses an existing ngrok tunnel when one is active, captures desktop UX proof when possible, creates a proof bundle, refreshes project memory/context cache, and exits nonzero if UI work is missing a preview, test result, screenshot/proof artifact, or proof bundle.
To start a new ngrok tunnel from final-flow, pass --public-preview only after the app has passed the public-preview safety gate.
MobileCodex stores local project memory under .mobilecodex/, which is ignored by git. Use it to avoid rediscovering stable facts:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py memory-update --root . --infer
py .\skills\mobile-codex-dev\scripts\mobile_dev.py memory-update --root . --dev-command "npm run dev" --test-command "npm run build" --preview-port 5173
py .\skills\mobile-codex-dev\scripts\mobile_dev.py context-cache --root .The context cache is a compact local summary of commands, ports, running previews, quirks, and recent learnings. Future sessions should read it before broad scans to save tokens and reduce repeated setup work.
| Workflow | What Codex is guided to do |
|---|---|
| Frontend apps | Start or reuse the dev server, verify in browser, capture desktop screenshots, summarize console/network issues, and keep preview servers running when useful. |
| Backend APIs | Run tests or a local service, exercise representative endpoints, report status codes and key responses. |
| CLIs and scripts | Run safe sample commands, include exit codes, summarize decisive stdout/stderr, report generated files. |
| Rust, Go, Python, Node | Prefer local project scripts and standard verification commands for each stack. |
| Session snapshots | Summarize workspace, branch, dirty files, detected stack, ports, registered servers, and recent proof artifacts. |
| Server registry | Track Codex-started preview servers with PID, port, URL, command, and log path outside git. |
| Proof bundles | Gather snapshot state, artifacts, server status, changed files, and log tails into one proof.md. |
| Desktop UX proof | Capture desktop screenshots with Playwright tooling, plus browser metadata when available. Users see the mobile view through the ngrok link. |
| Mobile handoffs | Keep progress updates and final replies concise, evidence-backed, resumable, and useful from a phone. |
| Public previews | Use ngrok http <port> only, after local verification and safety checks, with helper-based URL extraction. |
MobileCodex intentionally uses one tunnel provider: ngrok.
That keeps preview behavior predictable. It also prevents Codex from reaching for random tunnel services, deployment shortcuts, router changes, or editor-specific port forwarding.
If ngrok is missing, unauthenticated, rate limited, or unsafe for the current app, Codex should say exactly what blocked it and still provide local proof where possible.
For public previews, the helper command starts ngrok, polls the local ngrok API, extracts the real forwarding URL for the requested port, verifies that the public URL responds, reports the process/log status, and leaves the tunnel running when successful:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py ngrok-preview --port 5173MobileCodex/
|-- README.md
|-- index.html
|-- .gitignore
`-- skills/
`-- mobile-codex-dev/
|-- SKILL.md
|-- agents/
| `-- openai.yaml
|-- references/
| |-- command-proof.md
| |-- mobile-handoff.md
| |-- stack-playbooks.md
| |-- verification-checklists.md
| `-- web-previews.md
`-- scripts/
`-- mobile_dev.py
The root index.html is a single-file demo page for the skill. The skill itself lives entirely under skills/mobile-codex-dev, with SKILL.md at that folder root.
The bundled helper is intentionally small. It gives Codex quick, repeatable checks without replacing normal engineering judgment.
Show the phone-readable capability menu:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py menuRun first-time setup checks:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py setup --root .Detect project shape:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py detect --root . --format markdownCreate a resumable session snapshot:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py snapshot --root . --format markdownStart, inspect, and stop a registered preview server:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py server-start --root . --name app --port 8000 -- py -m http.server 8000 --bind 127.0.0.1
py .\skills\mobile-codex-dev\scripts\mobile_dev.py server-list --root .
py .\skills\mobile-codex-dev\scripts\mobile_dev.py server-stop --root . --name appCreate a proof bundle:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py proof-bundle --root . --format markdownCapture desktop UX proof for a local preview:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py ux-proof --root . --url http://127.0.0.1:8000/index.htmlWhen a project has a local Playwright dependency, ux-proof can collect console, failed request, and horizontal-scroll checks. Without a local dependency, it uses the npx playwright screenshot path for screenshot proof and basic page metadata.
Check ngrok availability:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py ngrok-checkStart an ngrok phone preview and extract the real forwarding URL:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py ngrok-preview --port 5173Format a compact handoff:
py .\skills\mobile-codex-dev\scripts\mobile_dev.py handoff `
--result "Updated the CLI parser" `
--preview "CLI output summarized below" `
--proof "tests exited 0" `
--state "No servers left running" `
--next "Add JSON output"Run the Codex skill validator:
$validator = "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py"
if (Test-Path $validator) {
py $validator .\skills\mobile-codex-dev
}Compile-check the helper:
py -m py_compile .\skills\mobile-codex-dev\scripts\mobile_dev.pyThis skill is intentionally lean:
SKILL.mdholds the core behavior and routing.references/holds deeper playbooks that Codex loads only when needed.scripts/mobile_dev.pyhandles repeatable inspection and handoff formatting.- local Codex installs, caches, screenshots, logs, and secrets stay out of git.
MIT License. See LICENSE.