Codex
Bothy for Codex CLI.
Bothy is a Mac app that runs local PHP and MySQL sites. Codex can drive it two ways: through Bothy's MCP server, registered in ~/.codex/config.toml, or directly from the shell with bothy commands and --json output. Either way Codex gets to run the code it writes against a real local site.
MCP or the CLI?
Codex is a terminal agent, so unlike a chat app it doesn't strictly need MCP. Both routes reach the same core and the same config file (~/Library/Application Support/Bothy/config.json) as the app.
- MCP tools are typed. Codex sees
bothy_set_site_iniwithname,keyandvaluefields rather than having to know the command syntax, and tool calls show up by name when you're approving them. - The CLI needs no setup beyond installing it from Integrations → Command line. Every command takes
--json, so Codex parses data rather than guessing at formatted text, and the commands it runs are ones you can copy and rerun yourself.
Many people set up both and let Codex choose. If you only do one, MCP is the better default; the CLI is the fallback that always works.
Setup
- 1Activate the Bothy app
The MCP server and CLI both use the app's activation.
- 2Add the MCP server
In Bothy, open Integrations and click Add to Codex. Bothy writes its entry into
~/.codex/config.toml. Prefer to edit the file yourself? Click Copy TOML and paste it in. The ChatGPT desktop app reads the same file, so this connects ChatGPT too. - 3Install the command line tool
Integrations → Command line symlinks
bothyonto your PATH, so Codex's shell can run it.bothy doctor --json
- 4Start a new Codex session
Codex reads its config at start-up. Ask it to list your Bothy sites to confirm both the tools and the CLI respond.
Tell Codex about the site in AGENTS.md
Codex reads AGENTS.md for project instructions. A few lines there stop it guessing which PHP binary to use or where the site lives:
## Local environment
This project runs under Bothy as `crm` at https://crm.test (PHP 8.3).
Run PHP tooling through the site's PHP:
bothy site exec crm -- php artisan migrate
bothy site exec crm -- vendor/bin/phpunit
Check errors with: bothy logs crm --kind php
Snapshot before migrations: bothy db snapshot crmbothy site exec runs in the site folder with that site's PHP first on PATH, so composer, artisan, wp and phpunit all use the right version even if your shell's default php is different. That's the single most common way terminal agents trip up on multi-version setups.
Example tasks for Codex
Codex works best on tasks with a clear finish line it can check itself. With Bothy it can check against the running site:
- “Write a migration adding soft deletes to invoices. Snapshot the database, run it, run the test suite, and show me the PHP log if anything fails.”
- “This project says it supports PHP 8.2 to 8.4. Switch the site to each version in turn, run phpunit, and report which fail.” -
bothy site php crm 8.2(orbothy_set_site_php) between runs. - “Import ~/Downloads/prod.sql.zip into crm_db, then find any rows the new validation rules would reject.” -
bothy db importstripsDEFINERclauses so production dumps load; then SQL. - “Get this repo running locally.” -
bothy site add app.client --git … --composer --db, then it reads the logs until the home page returns 200. - “After your change, check shop's 5xx count and p95 haven't got worse.” -
bothy stats shop --json.
Useful --json commands for scripts and agents
All real commands; append --json to any bothy command.
bothy doctor --json # health report: binaries, resolver, versions, services bothy status --json # services with CPU and memory bothy stats shop --json # req/h, 4xx/5xx, p95, FPM, db size bothy site add shop --php 8.3 --db --json bothy db query shop_db "SELECT COUNT(*) FROM users" --json
See the CLI reference for every command, or bothy --help.
Troubleshooting
Install the command line tool from Integrations → Command line in the app. If Codex is running commands in a restricted sandbox, commands that change your environment may need your approval or a less restrictive mode, because Bothy writes outside the project folder.
Run them through bothy site exec <site> -- … (or the bothy_exec tool) so the site's PHP comes first on PATH.
Check ~/.codex/config.toml has the Bothy entry and start a new Codex session.
Activate the app once; the CLI and MCP server share its activation.
No. bothy db query and bothy_query run as MySQL root. Snapshot first: bothy db snapshot shop_db.
