Developing with Codex
Use plain English to change your website, see the result and publish it. This guide starts with opening the project and walks through a complete first change.
Use Codex when you want to change the website itself: its wording, photographs, layout or features. To change a price, manage an order or open a drop, use the admin website guide instead.
What you do, and what Codex does
Imagine you want the homepage to explain collection more clearly. You tell Codex which wording you want, and it changes the relevant website files. It can start a preview on your computer so you can see the result. Once you are happy, it can save and publish that version.
You remain responsible for the business decision: the message, price, promise or customer experience you want. Codex handles the technical work, but it needs you to check whether the result is right for your business.
Codex can inspect the project, explain code, make changes and run checks. Your job is to explain what the customer should experience and review the result. You do not need to write the code yourself. Treat generated changes as work to verify, not an automatic guarantee.
| Term | Plain-English meaning |
|---|---|
| Repository / repo | The folder of source files and its saved history on GitHub. |
| Branch | A separate line of changes, so unfinished work can be reviewed before joining the main version. |
| Commit | A named checkpoint in the code history. |
| Pull request / PR | A proposal to bring a branch’s changes into another branch, usually main. |
| Merge | Accepting that proposal into the target branch. |
| Build / deploy | Build prepares code to run; deploy publishes it to a hosting service. |
| API / database | The service handling bookings / the stored menu, orders and customer records. |
Which accounts do you need?
You do not need to learn every service at once. To start making a small change, you need Codex and access to the project files. Ask the project owner to help with the first setup if you have not used GitHub before.
| Service | What it is for | When you need it |
|---|---|---|
| Codex | The application where you describe the changes you want. | To work on the website. |
| GitHub | Stores the website’s source files and their history. | To get the project and save changes for review. |
| Cloudflare | Serves the website to visitors on the internet. | To publish customer, admin or documentation pages. |
| Railway | Runs the booking service and stores the shared test data. | For backend configuration or database work. Usually unnecessary for a heading or image change. |
| Steakholders admin | Your business controls for menu items, drops and orders. | For daily operation and checking test bookings. |
A website address is not the project. Codex needs the actual files to change it. Access to the admin login does not automatically give you access to GitHub or Cloudflare.
Set up Codex for this website
Before you start: have your own Codex login and an invitation to the Steakholders GitHub repository. Accept that invitation using the GitHub account you intend to use.
The following instructions use the desktop app. The exact button names may change, but the goal is to open the folder that contains the website project.
- Get access. Ask the project owner for GitHub repository access and admin login. Hosting access is only needed when you are ready to publish. Keep credentials out of these documents.
- Install and sign in to Codex. Follow the official quickstart. Use your own supported account. Availability and billing depend on your account; do not assume an API key is required for every Codex setup.
- Get a local copy of the project. Ask the project owner to clone the Steakholders repository onto your computer, or use GitHub Desktop’s repository-cloning flow after signing in. “Clone” means download the project with its change history. Choose a folder you can find again, such as a Projects folder.
- Open that folder in Codex. Use the app’s project or folder selection to choose the Steakholders folder. The correct folder contains a file called
package.jsonand folders calledappsandpackages. Do not select a single HTML file or the Downloads folder containing unrelated files. - Start a task in that project. A task is the conversation where you describe the work. Paste the setup request below into it. Read Codex’s response before approving any action you do not understand.
- Check your starting version. The preview work was proposed in PR #5. Ask Codex to check whether it has merged and choose the branch containing the deployed preview. Do not assume main contains it.
- Prepare the local tools. Ask Codex to inspect the required Node.js version, pnpm version and local configuration before installing or running anything. This project declares pnpm 9.15.0.
- Run a local preview. The customer development server uses port 7102. For a complete local backend, the repository also uses Docker/PostgreSQL and an API on port 7100.
I am new to coding. Inspect this Steakholders project and explain how to run it locally. Read its project instructions first. Check the branch against the deployed preview work in PR #5. Set up the required tools and tell me which configuration values are missing. Keep credentials in secure local storage. Before running database setup, show me which database it targets.
How you know setup worked: Codex gives you an address such as http://localhost:7102. Open it on the same computer and you should see the customer website. “Localhost” means this computer; it is not a link you can send to another person for review. Keep the local server running while you view it.
Technical setup notes for Codex
Local setup caveat: pnpm start:local starts Docker, applies database schema/seed setup and starts the apps. It is not just a website preview command. Use it only after Codex confirms it targets a local test database. Ask Codex to check dev.sh before running it.
A new computer needs its own authorised hosting login or token. A token in someone else’s Keychain will not automatically be available on yours.
Make one small change first
- Choose one outcome. Start with a heading, button label or image. Give the page address and exact desired text or asset.
- Ask for a plan. Request a short explanation of affected files, behaviour and checks before edits.
- Make the change on a branch. Ask Codex to preserve unrelated work and keep the change focused.
- Look at it locally. Open the local address supplied by Codex. Check phone and laptop layouts, keyboard focus and the relevant links.
- Run checks. Ask for type-checks, relevant tests and a build when appropriate. Ask what was actually tested and what remains unverified.
- Review the difference. Have Codex summarise the changed files in plain English and show the diff. Ask why any unexpected file changed.
- Save and propose. Ask for a commit and PR. Then explicitly decide whether to merge and where to deploy.
Your first exercise: change one heading on the preview, verify the exact text on mobile and desktop, and confirm the two public domains still redirect to Canva.
Walkthrough: change a homepage heading
Start with a wording change because it is easy to see, easy to review and does not require you to change the booking system. The wording below is an example; substitute a heading you actually want to use.
1. Explain the change
Open a new task in the Steakholders project. Tell Codex which heading to replace. Include its current text so it does not have to guess.
On the homepage, replace the heading “[paste the current heading]” with “Your next steak night starts here”. I only want the heading changed. Keep its existing style and leave the booking flow and public Canva redirect as they are. Create a branch for this change and show me the result locally. I am not a coder, so explain the result in plain English.
2. Review the result
When Codex supplies the local preview link, open it. Check spelling, line breaks and whether the text overlaps anything at a narrow screen width. Click the booking button to make sure the surrounding page still works. Ask Codex for a mobile screenshot if you cannot resize the preview easily.
If the heading wraps awkwardly, say exactly that: “On the phone view, the last word is on a line by itself. Adjust the heading width or size so it reads naturally, keeping the wording.” You do not need to identify the CSS rule.
3. Ask for checks and a saved version
The wording is correct. Check that only the intended content changed, run the relevant checks, and save it as a commit. Open a pull request and give me its link. Explain anything I still need to verify before publishing.
Expected result: a PR link and a summary of the checks. A PR is a proposed change, not proof that it is already on the website. If a check fails, ask Codex to explain and resolve it before proceeding.
4. Publish the approved result
Follow the preview publishing steps below. After publishing, open the internet preview address yourself and verify the heading. Keep the PR link as the record of what changed.
Prompts you can copy
Replace the square-bracketed details before sending. Good requests say where, what changes and how you will know it works. These examples are tailored to this project.
A small visual change
On [page URL], replace [current heading] with [new heading]. Preserve the existing design and booking behaviour. Work on a new branch. Show me a local preview on phone and desktop, run the relevant checks, and open a PR with a short explanation. Keep both public domains redirecting to Canva.
A new feature
I want customers to [outcome]. The flow should be [steps]. Success means [observable result]. First inspect the existing implementation and propose the smallest change. Explain any effects on the API, database, emails and admin tools. Then implement and test it on a branch. Ask before destructive data changes.
Report a bug
At [URL], on [device/browser], I did [steps]. I expected [result], but saw [actual result]. Here is a screenshot with personal details removed. Reproduce the issue, identify the cause, fix it and check the same steps again. Tell me what you verified.
Review before publishing
Review this PR before publication. Explain the behaviour changes and any risk to booking availability, customer data, notifications or the Canva redirect. Run the relevant tests and build. Show me the preview and report any checks you could not complete.
When you do not understand
Explain that in plain English. What will the customer see, what could go wrong, and what decision do you need from me? Give me one recommended next step.
Use screenshots for visual feedback, but do not include API tokens, passwords or customer records. Keep one change per task when possible; add follow-up feedback to the same task while it is still working.
Publish a change to the preview
There are three places a change can exist. On your computer means only your local files changed. On GitHub means the changes have been saved and shared. On the website means that version has been deployed to Cloudflare. Ask Codex which of those is complete whenever it says “done”.
Choose the exact change to publish
Review the PR link and its summary. When you are ready to accept it into the main project, say “Merge PR #[number]”, replacing the number with the actual PR. When you want to publish the preview, explicitly name preview.steakholders.uk. A merge and a deployment are separate actions; ask Codex to report both outcomes.
There is already a preview deployment from the client-preview work. Before the next change, ask Codex to check whether that work has merged into main so it starts from the correct version.
Deployment details for Codex
The customer preview has a separate Cloudflare Worker called steakholders-customer-preview. Its configuration is apps/customer/wrangler.preview.toml; the repeatable deployment script is scripts/deploy-preview.sh.
Ask Codex to run bash scripts/deploy-preview.sh from the repository root after checking the branch, credentials and build configuration. The script builds the preview and deploys it; it does not log into Cloudflare for you.
Deploy the reviewed change to preview.steakholders.uk using scripts/deploy-preview.sh and the authorised Cloudflare credentials. Verify the live homepage and menu API, the noindex header, and the active Worker version through Cloudflare CLI. Confirm steakholders.uk and www.steakholders.uk still redirect to Canva. Do not reset the database.
Check the published result
- Open the actual preview URL and check the changed feature.
- Confirm the menu loads and the booking page behaves as expected.
- Confirm the main and www domains still redirect.
- For booking changes, create an available test drop and use contact details you control.
- Check order state in admin and expected notifications separately.
The preview forwards /api requests to the existing Railway API. It shares the test database with admin. Backend or database changes can affect both sites immediately, even when only the preview frontend is deployed.
Cloudflare hosts the customer and admin frontends. Railway hosts the API and PostgreSQL database. A frontend deployment does not publish backend code. Ask Codex to identify which service each change needs before deployment.
Project reference
You do not need to memorise these folders or open them by hand. This reference helps you understand Codex’s explanation when it says which part of the system it changed.
Folders, configuration and check commands
| Folder or file | Purpose |
|---|---|
apps/customer/src | Customer pages, components, booking flow and data fetching. |
apps/admin/src | Admin pages and operational tools. |
apps/api/src | Booking rules, orders, menu, authentication and notifications. |
apps/api/prisma | Database schema and setup assets. Ask for an explanation before changes. |
packages/shared | Shared types, status rules and formatting utilities. |
apps/customer/src/middleware.ts | Hostname routing, security headers and preview indexing rules. |
scripts | Deployment and verification helpers. |
docs/client-handbook | The HTML guides you are reading and their publishing configuration. |
Useful checks to ask Codex to run
pnpm turbo type-check checks types across the project. pnpm turbo test runs configured tests. The preview deploy script also builds the customer application. A passing test suite still needs a human check of the actual changed experience.
Get unstuck without starting over
“Unauthorised” or login expired
Ask Codex which service rejected access. Reconnect that account or provide a correctly scoped token through secure storage. Do not put secrets in prompts, GitHub, HTML files or committed configuration.
The change is saved but not visible
Ask Codex to compare the current commit with the deployed version and verify the exact hostname. A commit alone does not publish anything.
Tests fail
Ask for the failing check and its cause. Do not remove tests merely to make the check green. Distinguish an existing failure from one introduced by the change.
A change needs undoing
Ask Codex to identify the specific commit, prepare a revert and redeploy the affected service after review. Restoring code does not reverse data changes or recall emails. For data recovery, use a separately agreed backup/restore plan.
You want a clean database
Specify the exact test database and records to remove, back up first, and explicitly approve the reset. “Start again” should not be interpreted as permission to delete data.
Codex asks for permission
Read the action it wants to take. Running a local check is different from publishing a website, sending emails or deleting records. If the request is unclear, ask: “Which account or website does this affect, and what changes when I approve?” Do not approve an action just because it is described as technical.
Know when to get a developer involved
For a new payment integration, a change to admin access or a database restructure, ask for a plan and an experienced review before publishing. You can still use Codex to prepare the work and explain the choices. The extra review is about the effect on the business, not your ability to write code.
Official help
For current account setup and interface guidance, use the Codex quickstart, desktop app guide and prompting documentation. The project workflow and prompt examples above are recommendations for Steakholders.