Codex CLI: Setup and Keeping Its Work on a Board

Setting up Codex CLI takes four steps: install it, run codex and sign in, write an AGENTS.md that tells it how your project works, and add any MCP servers it should reach in ~/.codex/config.toml. The first three get it coding. The fourth is what lets it read a task board before it starts and write to it when it stops, which is the difference between an hour of agent work you can review in five minutes and an hour you have to reconstruct from the terminal.

Install it

The openai/codex README↗ (opens in a new tab) lists four ways in. Pick the one that matches how you already install tools; they all give you the same codex command.

npm install -g @openai/codex
brew install --cask codex
curl -fsSL https://chatgpt.com/codex/install.sh | sh          # macOS, Linux
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"   # Windows

To update, run the same command again. Start it from the root of the repository you want it to work in, because that is where it looks for instructions and where its file access begins.

Sign in

The first run asks how to authenticate. Choose Sign in with ChatGPT to use Codex as part of a ChatGPT plan; the README names Plus, Pro, Business, Edu and Enterprise. The alternative is an OpenAI API key, which the README notes needs additional setup. Plans and their limits change, so check your own account rather than a blog post, this one included.

Decide what it may do without asking

Before handing it anything real, run /permissions inside a session. OpenAI’s Codex CLI documentation↗ (opens in a new tab) describes it as choosing when Codex can edit files or run commands without asking, and it lets you inspect the active sandbox and the writable folders before you continue. A sensible first week is to let it read freely and ask before it writes outside the repository or runs anything with side effects. Widen it once you have seen what it does with the room it has.

Give it an AGENTS.md

Codex reads AGENTS.md files before it starts. According to the AGENTS.md guide↗ (opens in a new tab), it looks first in ~/.codex for a global file, then walks from the Git root down to your current folder, taking an AGENTS.md (or an AGENTS.override.md) at each level. Files closer to where you are come later in the combined instructions, so they win, and the whole chain stops growing at 32 KiB by default.

Keep the root file short and true: how to build and test, what never to touch, and how work is tracked. The same file is read by other agents, which is why it is worth getting right once; how GitHub Copilot handles it is covered in does GitHub Copilot read AGENTS.md. Here is the section that connects Codex to the board.

## The board
- Before any task: call fenbs_whoami, then fenbs_get_context for this project.
- Work from the board. If what I ask is not on it, file it first with fenbs_create_item
  (kind bug for a fix, feature for something new, enhancement for a change).
- Starting: move the task to In Progress (lane "doing") and comment what you will do.
- Finishing: set testStatus and testNotes, comment the commit, then move it to Completed.
- Stuck: comment what you tried and leave it in In Progress. Do not guess.

Add the board as an MCP server

Codex keeps MCP servers in ~/.codex/config.toml, or in a project’s own .codex/config.toml, one [mcp_servers.<name>] table each. You can write the table by hand or let the CLI do it. OpenAI’s Codex MCP documentation↗ (opens in a new tab) gives the commands: codex mcp add with --url for a remote server, codex mcp login to sign in to one that uses OAuth, and codex mcp list to see what is configured. Inside a session, /mcp shows the active servers.

codex mcp add fenbs --url https://fenbs.ai/api/mcp
codex mcp login fenbs
codex mcp list

The login opens a browser. On fenbs you sign in, see which app is asking and which board it will work in, and tick what it may do: read the board (always on), add and change tasks, and comment. Approve, and Codex holds a token that acts as you, narrowed by those ticks and by your role on the board. The full connection page, including the bridge for setups without a browser, is Codex CLI on fenbs.

Two options in the same table are worth setting on day one. enabled_tools is an allow-list, so a first week of reporting only can list just the read tools. default_tools_approval_mode sets how Codex treats the server’s tools: auto, prompt, approve, or writes, which asks only for tools the server has not marked read-only.

[mcp_servers.fenbs]
url = "https://fenbs.ai/api/mcp"
default_tools_approval_mode = "prompt"
enabled_tools = ["fenbs_whoami", "fenbs_get_context", "fenbs_list_items",
                 "fenbs_get_item", "fenbs_search", "fenbs_comment"]

When you trust what it reports, add fenbs_create_item and fenbs_update_item to the list and relax the approval mode. That is a one-line change, and the board’s own permissions still apply underneath: if your role cannot move tasks, neither can Codex.

What a session on the board looks like

1. You: “Take the top task in Next Up.”
2. Codex calls fenbs_whoami, reads the AI context for the project, then fenbs_list_items with lane next. It finds BUG-052, “CSV export drops the last row”.
3. It moves BUG-052 to In Progress and comments its plan: reproduce with a two-row file, check the loop bound.
4. It works, asking before commands your /permissions setting does not cover.
5. It sets testStatus to tested with a line on what it ran, comments the commit, and moves BUG-052 to Completed. It files ENH-053 for a slow query it noticed on the way.
6. You open the board’s History: each change is there under the assistant’s name, on your behalf.

If a person has pre-approved tasks for AI, there is a shorter version: tell Codex to call fenbs_next_approved_task when it has nothing else to do. It gets the next approved task with its plan and limits, holds it while it works, and hands it back with fenbs_release_task if it cannot finish. A person then checks what it did.

When the connection misbehaves

• The server times out on start. Codex waits 10 seconds by default; raise startup_timeout_sec in the server’s table. Slow tools have their own tool_timeout_sec, 60 seconds by default.
• Codex says it cannot see the tools. Run codex mcp list, then /mcp in a session. If the server is listed but empty, check enabled_tools for a typo.
• Calls fail with a sign-in error. Run codex mcp login fenbs again. Access tokens from a browser sign-in are short-lived and refresh themselves, so a repeated failure usually means the token was revoked.
• A call is refused with a named permission. That is your role or your ticks working. Widen them if the request was reasonable.

Taking it back

On fenbs, every sign-in appears by name under Settings, “Connect an AI assistant”. Revoke it there and Codex stops at once; your own sign-in is untouched and everything it did stays in History. On the Codex side, delete the table from config.toml. For the wider question of how much to give an assistant in the first place, see how to give an AI agent access to your project board.