Set up Codex with ai-architecture

Step 1: Before you start

A terminal is a window where you give your computer instructions by typing short lines called commands. You type or paste one line at a time and press Return (Mac) or Enter (Windows and Linux). To paste: Cmd + V on a Mac; Ctrl + V or a right-click in Windows PowerShell; Ctrl + Shift + V on Linux. To open the terminal:

Now check what you need:

• An account that can use Codex, and its cost. Plans and prices change, so this guide quotes none. Read the official page first: https://developers.openai.com/codex/cli
• Python 3.11 or newer for the helper programs. Python is a free tool they run on; ai-architecture's continuity skill and Provenote's helpers use it. In the terminal window, run python3 --version (macOS or Linux) or py -3 --version (Windows; if that is not recognised, try python --version). Remember which one worked; step 9 uses it. It should print Python 3.11 or newer. If not, install it. On a Mac, use the macOS page, then close and reopen the terminal window. On Windows, python.org now leads with the Python install manager: download it from the Windows page, open the file and click Install. Then open a new PowerShell window and run py install 3.11. Python may prompt you to add a folder to your PATH (the list of places the terminal looks for programs); the Python documentation calls this optional. Check with python --version. If python is not found, open Windows Settings, search for Manage app execution aliases and check the Python entries there.
• Linux (if Python is missing or too old): install Python 3 with your package manager: sudo apt update && sudo apt install python3 (Debian or Ubuntu), sudo dnf install python3 (Fedora, which already has Python 3) or sudo pacman -S python (Arch). sudo runs a line with administrator rights, so it asks for your own computer password; while you type it, usually nothing appears on the screen. Type it and press Enter. If a line asks whether to continue, type y and press Enter. On Ubuntu 22.04, apt gives Python 3.10, which is below 3.11 and cannot reach 3.11 this way. If python3 --version still shows 3.10 after the install line, you can still do the copy steps in Part 2, which do not need Python; the Python-based helpers (step 9 and the installer in 7c) may not run.
• A project folder for Codex to work in. Step 4 tells you which; if you skip Part 2, step 7 uses the example folder instead.

Done when the terminal is open and Python prints 3.11 or newer. (On Ubuntu 22.04 that is not possible; see the Linux bullet above for what you can still do.)

Stuck? See Stuck? Ask for help.

Step 2: Install Codex

Codex runs in the terminal. The official page is the authority: https://developers.openai.com/codex/cli. If the line below differs from that page, follow the official page.

The install lines below download OpenAI's installer and run it. Only use lines like this from an official page.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

codex --version

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

codex --version

wsl --install

curl -fsSL https://chatgpt.com/codex/install.sh | sh

curl -fsSL https://chatgpt.com/codex/install.sh | sh

codex --version

You sign in to Codex later, in step 5, once the project folder exists (or in step 8, if you skip Part 2).

Step 3: Get ai-architecture

3a. Download it. Open the v0.4.2-preview page linked above in your web browser. Click the green Code button, then Download ZIP. You do not need Git for this route. A ZIP file is a folder packed into one file; unzipping unpacks it. It usually lands in your Downloads folder.

Done when a ZIP file from ai-architecture is in your Downloads folder.

3b. Unzip it. Your file window is called Finder on a Mac and File Explorer on Windows. On Linux, use your file manager.

In the steps below, "the ai-architecture folder" means the unzipped folder.

Done when you can open the ai-architecture folder, then skills, and you see the folders planning and continuity.

Stuck? See Stuck? Ask for help.

Step 4: Add its skills to a project

You will copy the whole folders skills/planning and skills/continuity into a folder named .agents/skills inside your project. It does not change your global configuration. For real work, use your own project folder. To try it first, make a new empty folder, for example my-project in your Documents folder; that name is this guide's own suggestion.

4a. Choose the project folder. Make the new folder, or pick your project.

Done when the folder exists and you know where it is.

4b. Show hidden files. On a Mac or Linux PC, names that start with a dot are hidden, so you would not see your .agents folder. Turn hidden files on in your file window:

• Mac (Finder): open your project folder and press Command + Shift + . (the full stop key). Press it again to hide them.
• Linux (Files): open your project folder and press Ctrl + H.
• Windows (File Explorer): click View → Show → Hidden items. (Windows 10: click the View tab and tick Hidden items.)

Done when the setting is on. (You will see it working in 4c.)

4c. Check that .agents is not already there. Open your project folder. If it already contains .agents/skills/planning or .agents/skills/continuity, stop: keep what is there and ask for help if you want both. Do not copy over a folder you have not inspected.

Done when neither folder exists yet.

4d. Create the folder .agents in your project. Make a new folder and name it .agents, with the dot. On a Mac, Finder may warn that names beginning with a dot are reserved and will be hidden: choose the button that keeps the dot. (If .agents is already there, use it.)

Done when .agents is shown inside your project folder.

4e. Create skills inside .agents. Open .agents, make a new folder, name it skills. (If it is already there, use it.)

Done when .agents/skills exists.

4f. Copy planning. Copy the whole folder skills/planning from the ai-architecture folder, with everything inside it, into .agents/skills.

Done when .agents/skills contains planning.

4g. Copy continuity. Copy the whole folder skills/continuity the same way.

Done when .agents/skills contains continuity.

4h. Compare with the listing. The result should look like this:

<project>/.agents/skills/
  planning/
  continuity/

Done when the folders look exactly like the listing above. Do not copy a folder named skills into .agents/skills: that nests it twice.

Stuck? A folder is missing or nested twice. Copy the exact folder listing and see Stuck? Ask for help.

Step 5: Check that Codex sees them

5a. Open the terminal in the project folder. In the terminal, type cd (the letters c, d and a space). In your file window, drag your project folder icon into the terminal window. This writes out the folder's path, its address on your computer. Press Return/Enter.

Done when the line you can type on now mentions your project folder.

5b. Start Codex and sign in. Type codex and press Return/Enter. The first time, choose Sign in with ChatGPT (or another sign-in method it offers), as the official page describes.

Codex may ask more questions before you can type, for example whether to trust this folder. Use the arrow keys and Enter to choose; for your project folder, pick Trust and continue. The wording may differ by version. Later, Codex may ask you to approve a command before it runs it. Read what it wants to run, and approve it only if it matches what you asked for.

Done when Codex shows a prompt where you can type a message.

Stuck? A sign-in loop or a plan error. Copy the exact text and see Stuck? Ask for help.

5c. Ask Codex which skills it has. You are now inside Codex, no longer in the normal terminal. Type this line, or type $ to see the skills you can mention.

/skills

Done when planning and continuity appear in the list.

Stuck? One is missing → close the terminal window, open a new one, go back into the project folder as in 5a (type cd, drag the folder in, press Return/Enter), then type codex again. Still missing → check the folder listing in step 4, then see Stuck? Ask for help

You are done with the main setup. The rest is for research work. If that is not you, you can stop here.

Step 6: Get Provenote

You need the Provenote download, and one folder in it.

6a. Download it. In your web browser, open Provenote's front page on GitHub. Click the green Code button, then Download ZIP. You do not need Git for this route. A ZIP file is a folder packed into one file; unzipping unpacks it. The file is called provenote-main.zip and usually lands in your Downloads folder.

Done when provenote-main.zip is in your Downloads folder.

6b. Unzip it. Your file window is called Finder on a Mac and File Explorer on Windows. On Linux, use your file manager.

In the steps below, "the extracted folder" means that folder (provenote-main), so docs/codex/SKILL.md is provenote-main/docs/codex/SKILL.md. "Download ZIP" gives you the latest version of the branch, which may be newer than the commit this guide was tested with (see About this guide).

Done when you can open provenote-main, then examples, then basic.

Stuck? See Stuck? Ask for help.

Step 7: Add the Codex adapter by copying files

This follows INSTALL.md. It installs the adapter, one self-contained Codex skill, into one project. It does not change AGENTS.md, your global configuration, or any Claude plugin. A skill is a set of instructions the assistant follows for one kind of job.

For this guide, use provenote-main/examples/basic as your project. It is a demo only: it sits inside the download, which has its own AGENTS.md at the top and is not a Git repository, so Codex may treat it a little differently from a real project. For real work, repeat this step in your own project folder.

You will make a folder named .agents (it starts with a dot) and copy files into it. The result should look like this:

Do the sub-steps one at a time. Each ends with a ✅ you can check.

7a. Show hidden files. If you did this in step 4b, it is still on: skip to 7b. On a Mac or Linux PC, names that start with a dot are hidden, so you would not see your .agents folder. Turn hidden files on in your file window:

• Mac (Finder): open the basic folder and press Command + Shift + . (the full stop key). Press it again to hide them.
• Linux (Files): open the basic folder and press Ctrl + H.
• Windows (File Explorer): click View → Show → Hidden items. (Windows 10: click the View tab and tick Hidden items.)

Done when the setting is on. (You will see it working in 7b.)

7b. Check that .agents is not already there. Open provenote-main/examples/basic. If it already contains .agents/skills/provenote, stop: back it up and compare it; do not overwrite anything you have not inspected.

Done when there is no .agents folder yet.

7c. Create the folder .agents inside examples/basic. Make a new folder and name it .agents, with the dot. On a Mac, Finder may warn that names beginning with a dot are reserved and will be hidden: choose the button that keeps the dot.

Done when .agents is shown inside basic.

python3 scripts/install-codex.py --project /absolute/path/to/project

python .\scripts\install-codex.py --project C:\path\to\project

7d. Create skills inside .agents. Open .agents, make a new folder, name it skills.

Done when examples/basic/.agents/skills exists.

7e. Create provenote inside skills. Open skills, make a new folder, name it provenote. This is the "final folder"; the rest of the copying goes into it.

Done when examples/basic/.agents/skills/provenote exists and is empty.

7f. Copy SKILL.md. Copy the file provenote-main/docs/codex/SKILL.md into the final provenote folder. Keep the name SKILL.md. Windows may show it as just SKILL; that is the same file.

Done when provenote contains SKILL.md.

7g. Copy bin. Copy the folder bin from provenote-main/plugins/provenote/ into the final provenote folder.

Done when provenote contains bin.

7h. Copy templates. Copy the folder templates from the same plugins/provenote/ folder into the final provenote folder.

Done when provenote contains templates.

7i. Copy agents. Copy the folder agents from the same plugins/provenote/ folder into the final provenote folder.

Done when provenote contains agents.

7j. Copy skills (the whole folder). Copy the whole folder provenote-main/plugins/provenote/skills into the final provenote folder.

Done when provenote contains a folder named skills.

7k. Rename that copy to workflows. Rename only the copy inside .agents/skills/provenote/; the original skills folder in plugins/provenote/ keeps its name.

Done when provenote contains workflows, and the original plugins/provenote/skills is still called skills.

7l. Compare with the picture. The final folder should look exactly like this listing:

<project>/.agents/skills/provenote/
  SKILL.md
  bin/
  templates/
  agents/
  workflows/

Done when the folder looks exactly like the listing above and like the "After" part of the picture. Do not copy a folder named provenote into the final provenote folder: that nests it twice.

Stuck? A folder is missing or nested twice. Copy the exact folder listing and see Stuck? Ask for help. If the installer from 7c printed an error, copy that too.

Step 8: Check 1: discovery

8a. Open the terminal in the example folder. If you are still inside Codex, close the terminal window and open a new one (step 1). Type cd (the letters c, d and a space). In your file window, open provenote-main, then examples, and drag the basic folder icon into the terminal window. Press Return/Enter.

Done when the line you can type on now mentions basic.

8b. Start Codex. Type codex and press Return/Enter. If you did step 5, you are already signed in. If not, choose Sign in with ChatGPT (or another sign-in method it offers), as the official page describes. Codex may ask whether to trust this folder; for this demo folder, pick Trust and continue (the wording may differ by version). Approve a command only if it matches what you asked for.

Done when Codex shows a prompt where you can type a message.

8c. Ask for the workflows. You are now inside Codex, no longer in the normal terminal. Type the line below including the $ at the start; it belongs to the message, so do not skip it.

$provenote show me the available Provenote workflows; do not run helpers yet.

Done when Codex lists Provenote workflows. This proves discovery only: Codex can find the skill. Whether the helper programs run is Check 2.

Stuck? Nothing is listed. Close the terminal window, open a new one, go back to 8a, and try once more. Still nothing: see Stuck? Ask for help. The Provenote authors have not tested live Codex discovery (adapters.md), so this check may fail on your Codex version even when the files are right.

Step 9: Check 2: the installed adapter helper

This runs the helper from the installed adapter folder, $provenoteKit/bin, on the bundled example, so you see real PASS and FAIL lines. It follows codex/SKILL.md. First leave Codex: close the terminal window and open a new one (step 1). In that normal terminal window, go into your project again as in 8a (type cd, then drag the basic folder into the window and press Return/Enter). The first line below sets provenoteKit to the installed adapter folder inside the folder you are in ($PWD stands for the folder you are in); type it exactly as shown. Here $provenoteKit is a variable name, unrelated to the $ in step 8c.

provenoteKit="$PWD/.agents/skills/provenote"
python3 "$provenoteKit/bin/verify-quotes" --strict 01_notes/lit/*.md
python3 "$provenoteKit/bin/verify-quotes" --strict 01_notes/negative/*.md

$provenoteKit = "$PWD\.agents\skills\provenote"
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/lit/lei2023financial.md
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/lit/kireyev2026pricebench.md
& python "$provenoteKit\bin\verify-quotes" --strict 01_notes/negative/lei2023financial.md

Done when you see 14 PASS, then the one expected FAIL.

Stuck? A different count of PASS lines, no FAIL, or a Python error. Do not trust the result. Copy the exact output and see Stuck? Ask for help.