Start

Codex and Cursor (beta)

Shipyard was made for Claude Code, and it also runs in two other coding agents: OpenAI Codex and Cursor. A coding agent is an AI program that reads your files and runs commands for you. This page shows how to install Shipyard in Codex or Cursor, and what works differently. When you are done, go back to Run setup once on the Start page and follow the rest of the guide.

In the rest of the guide, read "Claude" as your coding agent, and type each command in the form for your agent (see What to type).

Before you start

You need these on your computer.

1. Codex or Cursor, signed in.
   • Codex: the Codex CLI, version 0.163 or newer. The CLI is the version of Codex you run in a terminal. Check with codex --version. To install it, or update it if it is older, run npm install -g @openai/codex@latest in a terminal (it needs Node.js, step 2 below), then check the version again. The official install page, with other ways to install it, is at learn.chatgpt.com/docs/cli. You can then use Codex in the ChatGPT desktop app or the IDE extension too, but you need the CLI once to turn on the key guard.
   • Cursor: the Cursor editor. The Cursor CLI (the agent command) is optional.
2. Node.js 20 or newer. Node.js is a free program that runs Shipyard's tools. Download the LTS version from nodejs.org. Check with node --version.
3. Git. Git keeps a history of your code. On a Mac, the computer offers to install it the first time you use it. On Windows, Codex and Cursor do not install Git for you: install Git for Windows from git-scm.com, then close your terminal and open a new one. Check with git --version.

A terminal is the text window where you type commands. On a Mac it is the Terminal app. On Windows use PowerShell, not the old Command Prompt (cmd.exe).

Install

Run these two lines in a terminal, one after the other. Or paste both into Codex or Cursor and allow it to run them.

git clone --depth 1 https://github.com/philipposk/shipyard.git "$HOME/.local/share/shipyard"
node "$HOME/.local/share/shipyard/scripts/install-agents.mjs"

The first line downloads Shipyard into a folder inside your home folder. The second line sets it up.

• It looks for Codex and Cursor on your computer. If it finds neither, or you only want one, add --agent codex, --agent cursor or --agent both to the end of the second line.
• It lists every file it will create or change, then asks "Go ahead? (y/N)". Type y and press Enter.
• If your agent ran it, there is no one to answer, so it stops and asks for --yes. Read the list it printed. If it looks right, tell the agent to run the second line again with --yes at the end.

What it changes (~ means your home folder):

• The skills. It puts Shipyard's six skills in ~/.agents/skills/, in folders named shipyard-setup, shipyard-new-app and so on. A skill is a set of instructions the agent loads when you ask for it.
• The key guard. It adds the guard to ~/.codex/hooks.json for Codex and ~/.cursor/hooks.json for Cursor. It keeps anything else in those files, and saves a backup copy of each one first.
• Nothing in Claude Code. It never changes Claude Code's files. If you also use Claude Code, keep using the Claude Code plugin there.

Codex and Cursor both read skills from ~/.agents/skills, so the skills show up in both. If you pick only one agent but the other is on your computer too, the installer adds the key guard for the other one as well and tells you, so neither agent has the skills without the guard. For the same reason, --uninstall --agent codex (or --agent cursor) stops with a message when the other agent would be left with the skills and no guard. Remove both with --uninstall.

Running it twice is safe. The second time it says everything is unchanged.

For Codex it also asks whether Codex may run Shipyard's own scripts without asking you each time. "No" is the safe answer. See Codex asks before each command.

Codex: turn on the guard

The key guard is a hook: a small program the agent runs before each action. Shipyard's hook stops the agent from reading your keys file or your app's .env files (the files that hold an app's keys). Codex asks you to trust a new hook once before it runs it.

Do the /hooks step once in the terminal, even if you then use Codex in the ChatGPT desktop app or the IDE extension.

Done when: Shipyard setup starts and its guard check says ON (see The guard check).

Cursor: reload and start

Cursor picks up the guard and the skills when it starts, so it needs a restart.

In the Cursor CLI, run agent in a terminal, then type /shipyard-setup.

Done when: Shipyard setup starts and its guard check says ON.

What to type

The guide shows the Claude Code form of each command. Here is the same command in each agent. You can also just say the skill's name, such as "Shipyard setup".

In Codex you can also pick a skill from the /skills list.

The guard check

Once per session, before anything touches your keys, Shipyard asks the agent to run a short check. It makes a test file that looks like a keys file but holds no key, and asks the agent to read it. The guard should block that. The block message carries a short code, and a script checks the code, so the agent cannot just say it worked. In Cursor the agent tries twice, once in the shell and once with its file-reading tool, because Cursor checks those separately.

• ON: the guard works. Setup carries on.
• OFF: the guard did not block the test file. The guard is not protecting your keys right now.
• Inconclusive: the test commands did not run, so the check cannot tell. The agent runs it again.

If it says OFF:

Codex asks before each command

Codex asks before it runs a command, unless you have told it not to. When it asks to run node ".../shipyard/scripts/...", choose the option that stops it asking again for that command.

If a Shipyard script fails because Codex blocked internet or file access, the agent asks to run it again with that access and tells you why. It never changes Codex's settings on its own.

To be asked less, run the second install line again with --codex-allow-scripts at the end. It adds ~/.codex/rules/shipyard.rules, which lets Codex run Shipyard's own scripts without asking. It does not cover the installer, the guard or any other command. Be aware that Codex runs the commands this file allows outside its sandbox (the limits on what it may do on its own), so they have full access to your files and the internet, and it does not ask. Codex reads the file when it starts, so start a new Codex session after adding it. Delete that file to undo it. This part is a beta too: if Codex ignores the file, it just keeps asking.

Updating

About once a month, run this in a terminal:

node "$HOME/.local/share/shipyard/scripts/install-agents.mjs" --update

It downloads the latest Shipyard and refreshes the skills and the guard. It tells you when Codex needs you to trust the hook again in /hooks. If your copy is more than 30 days old, the agent offers this too.

• If you installed Node with a version manager (nvm, Volta or fnm) and switch Node versions, run --update again.
• If you moved the Shipyard folder, run the installer again from its new place. --check tells you when this has happened.
• If --update says the folder has changes of its own, move the folder away, run the two install lines again, and delete the old folder once the new one works.

What is different from Claude Code

Setup, new-app, design, launch, video and ops all work. A few things differ.

• Updates are not automatic. Claude Code updates the plugin for you. In Codex and Cursor you run --update.
• Working habits. Setup offers a short list of habits for your agent. In Codex it adds them to ~/.codex/AGENTS.md after you say yes. In Cursor it shows you the text to add as a User Rule: open Customize in the sidebar, then Rules, and add it there (in older Cursor versions: Cursor Settings, Rules, User Rules).
• Code review. Claude Code has a free /code-review command. In Codex or Cursor, ask your agent on the branch: "Review the changes on this branch against main and list real bugs only."
• Claude Code only: fixes inside GitHub Actions (part of module 9), pull-request auto-fix and scheduled tasks in Claude's desktop app, and the free frontend-design plugin for design. Shipyard skips these in Codex and Cursor.

Seeing Shipyard twice

Cursor can import Claude Code plugins, and Codex can import skills from Claude Code. If you also have the Claude Code plugin, you may see Shipyard's skills twice. Use the shipyard-* ones, such as $shipyard-setup or /shipyard-setup. The other copies were written for Claude Code.

--check looks in these places and tells you what to do for each one it finds: Shipyard skills in ~/.codex/skills, ~/.cursor/skills and ~/.claude/skills, the Claude Code Shipyard plugin (which Cursor loads while its setting "Include Third-Party Plugins, Skills, and Other Configs" is on), and Claude Code's Shipyard as a Codex plugin. To switch off an old Codex skill it prints three lines to add to ~/.codex/config.toml, with the real path filled in, then you restart Codex:

[[skills.config]]
path = "/path/to/the/old/skill/SKILL.md"
enabled = false

Windows

• Run the install lines in PowerShell. They do not work in the old Command Prompt.

• Install Git for Windows first (see Before you start).

• Your keys file is at %USERPROFILE%\.shipyard\secrets.env. Shipyard's own folder is %USERPROFILE%\.local\share\shipyard.

• Not yet checked on Windows: whether Codex and Cursor find skills in ~/.agents/skills. If $shipyard-setup or /shipyard-setup does nothing after a reload, move the skills to a folder both agents read, ~/.codex/skills (Codex's older skills folder, which Cursor also reads):

  node "$HOME/.local/share/shipyard/scripts/install-agents.mjs" --agent both --skills-dir "$HOME/.codex/skills"
  

  Shipyard keeps one skills folder for everything it installs, so use this one line for both agents. If you only use Cursor, you can use --agent cursor --skills-dir "$HOME/.cursor/skills" instead, and if you only use Codex, leave --skills-dir out. Do not run one command for each agent: the second one would move the skills away from the first. --check tells you when an agent does not read the skills folder Shipyard uses.

What the guard does not cover

The guard is a safety net, not a vault. It checks each action before the agent runs it. Some things it cannot see.

In Codex:

• Codex's own web search runs on OpenAI's servers, so no hook can check it.
• Text typed into a program that is already open, such as a shell or a Python session left running. Shipyard blocks starting one without a command for this reason, but it cannot see everything.
• Codex's default sandbox (the limits on what it may do without asking) can read files anywhere on your computer. A command the guard does not recognise as reading a file could still read your keys.
• In the ChatGPT desktop app and the IDE extension, the guard has not been checked yet. Run the guard check there before you trust it.

In Cursor:

• Tab (Cursor's suggestions as you type) and Cloud Agents (agents that run on Cursor's servers). New Shipyard apps get a .cursorignore file that keeps .env files away from Cursor's index and Tab, but it does not cover ~/.shipyard.
• So never open ~/.shipyard/secrets.env in Cursor's editor. If setup opens it in Cursor, close it and open it in another text editor, such as TextEdit on a Mac or Notepad on Windows.
• Cursor changes what it sends to hooks between versions. Shipyard accepts several forms, and the guard check shows you when a new version slips past.

In both: the guard check only proves the guard works when the agent runs it. The agent is told to run it every session, but an agent can still skip an instruction.

Removing Shipyard

In a terminal, run:

node "$HOME/.local/share/shipyard/scripts/install-agents.mjs" --uninstall

It removes only what it installed: its skill folders, its guard entries and the Codex rules file. Your keys in ~/.shipyard stay where they are. Then delete the folder ~/.local/share/shipyard, reload Cursor and start a new Codex session.

If you deleted the folder first, the guard entries stay behind but block nothing. To remove them by hand, open ~/.codex/hooks.json and ~/.cursor/hooks.json in a text editor and delete the entries whose command mentions guard-codex.mjs or guard-cursor.mjs. You can also delete the shipyard-* folders in ~/.agents/skills.

Back to Run setup once Troubleshooting