Annex — Codex CLI

This guide covers integrating KaKeKiKoKu with Codex CLI, OpenAI's terminal client, on Windows and Linux.

Codex CLI is the terminal surface of the same Codex host used by the ChatGPT desktop app and the IDE extension. It is installed separately, but those local surfaces share config.toml, MCP servers, and Codex authentication state when they use the same CODEX_HOME.

The Windows path is usable today, but if you do not specifically need a terminal workflow, KaKeKiKoKu recommends the ChatGPT Desktop (Codex) guide first. Keep reading this page for terminal sessions, automation, or a CLI-only setup.

The recorded Linux setup uses the Snap package and a quiet wrapper. See the client matrix for its recorded status; this is not a test of every current CLI release.

Codex CLI does not support KaKeKiKoKu channels today. KaKeKiKoKu therefore works in Precise mode: Codex can use KaKeKiKoKu MCP tools, while KaKeKiKoKu UI actions that would push messages to the AI copy text to the clipboard.

Codex CLI also has no built-in Browser, so it cannot place KaKeKiKoKu beside the terminal conversation. The MCP integration on this page still works in full; for the shared visual workspace, use ChatGPT Desktop with Codex.

The quiet wrapper is optional. openai/codex#7155 reports a Windows CLI failure with heavy diagnostic output on stderr. That report does not establish that every current CLI version or every Transport closed error has the same cause. Keep a working direct registration. If you reproduce that Windows failure, the wrapper below is a diagnostic workaround; the recorded Linux setup also uses it.

The MCP stdio transport keeps protocol messages on stdout and allows stderr for logging. The wrapper only silences diagnostic logs; it does not remove KaKeKiKoKu's MCP responses.

Windows recommendation: use ChatGPT Desktop with Codex unless you specifically want Codex CLI. The desktop app and CLI can share this MCP registration.

Requirements

Before you start:

• KaKeKiKoKu installed. Windows and Linux instructions are on the Download page. Linux installs from the Snap Store.
• Codex CLI installed or updated. OpenAI's current official CLI documentation provides standalone installers for Windows and Linux; npm remains an alternative.
• An active ChatGPT account with a plan that includes Codex access, or an OpenAI API key if you choose API-key login.
• Node.js/npm only if you choose the npm alternative. The standalone installer does not require Node.js.

Install or update Codex CLI

OpenAI now publishes standalone installers. Choose your operating system:

irm https://chatgpt.com/codex/install.ps1 | iex

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

Verify the installation:

codex --version

When your installed build supports self-update, use:

codex update

You can also rerun the standalone installer. If you prefer npm, the maintained package is still:

npm i -g @openai/codex@latest

Start Codex once so it can complete its own login flow:

codex

The first run prompts you to sign in with ChatGPT or use an API key. Authentication is handled by OpenAI; KaKeKiKoKu is not involved.

Linux npm permissions. This applies only if you choose npm instead of the standalone installer. A global npm install can target a system folder owned by root and fail with EACCES: permission denied. Two ways around it:

• Prefix the command with sudo — for example sudo npm i -g @openai/codex.
• Or install Node through a version manager such as nvm, which keeps Node under your home folder; then npm i -g never needs sudo.

On Windows the global npm folder belongs to your user, so no elevation is needed there.

1. Optional quiet KaKeKiKoKu wrapper

Use the wrapper if you are reproducing the Windows stderr failure or following the recorded wrapper-based setup. It forwards arguments and suppresses diagnostic stderr while leaving MCP responses on stdout. Suppressing logs can make other failures harder to diagnose, so do not treat it as a universal requirement.

On Linux, the same wrapper pattern is documented for consistency and clean logs. The public upstream bug report is Windows-specific; this guide does not claim the same bug exists on Linux.

The wrapper idea is the same on Windows and Linux, but the wrapper file and the KaKeKiKoKu command are different.

~/wuniq-mcp-quiet.sh

#!/usr/bin/env bash
exec /snap/bin/wuniq.wuniq-mcp "$@" 2>/dev/null

chmod +x ~/wuniq-mcp-quiet.sh

2. Register KaKeKiKoKu in Codex CLI

For a direct setup, use codex mcp add wuniq -- wuniq-mcp.exe on native Windows or codex mcp add wuniq -- /snap/bin/wuniq.wuniq-mcp on Linux. The commands below instead register the optional wrapper. Choose one setup; do not register both under different names. The recorded Linux test covers the wrapper setup, and no Windows integration test is recorded here.

Only if you are switching an existing registration to the wrapper, remove that entry first:

codex mcp remove wuniq

If it was not registered, Codex may say it cannot find the server. That is fine.

codex mcp add wuniq -- "$env:USERPROFILE\wuniq-mcp-quiet.cmd"

codex mcp add wuniq -- ~/wuniq-mcp-quiet.sh

Verify the registration

codex mcp list

It should show wuniq among the configured MCP servers.

Equivalent config.toml shape

Codex stores user-level MCP servers in ~/.codex/config.toml. The ChatGPT desktop app and IDE extension read the same file. The entry below points to the wrapper, not directly to KaKeKiKoKu.

[mcp_servers.wuniq]
command = "C:\\Users\\<you>\\wuniq-mcp-quiet.cmd"
enabled = true
startup_timeout_sec = 30

[mcp_servers.wuniq]
command = "/home/<you>/wuniq-mcp-quiet.sh"
enabled = true
startup_timeout_sec = 30

Project scope. Trusted repositories can also define MCP servers in .codex/config.toml. Keep the wrapper path absolute there. Project configuration is ignored until Codex trusts the repository.

3. Startup instructions (the second piece of the integration)

Codex reads AGENTS.md files at startup. Add KaKeKiKoKu's startup instructions to the working directory you open with Codex, or to your global Codex home if you want them everywhere.

1. In your working directory, create AGENTS.md if it does not exist.
2. Add:

   # KaKeKiKoKu Studio (MCP)
   
   At the start of each conversation, use the `run` tool of the `wuniq` MCP server (KaKeKiKoKu Studio, which holds the project knowledge): run `open list`, then `help`, and work as `help` explains. Run `help` again if the conversation is compacted.

3. Save and start a new Codex CLI session from that directory.

This file only starts the connection. Don’t copy your project’s decisions into it, or into your AI’s memory or skills: they live in KaKeKiKoKu. See Avoid competing copies of project knowledge.

Global alternative. To make the same instruction apply to every Codex project, create the global file for your OS and put the KaKeKiKoKu block there.

Windows Linux

%USERPROFILE%\.codex\AGENTS.md

~/.codex/AGENTS.md

4. Open a project and verify

1. Open a terminal in your KaKeKiKoKu working directory or project folder.
2. Start Codex:

   codex

3. If your startup instructions are loaded, Codex should call KaKeKiKoKu automatically. If not, ask:

   Run open list with the KaKeKiKoKu tool.

4. Ask it to open one of the returned projects.
5. In KaKeKiKoKu, the AI-connected indicator should turn green when Codex calls the MCP tool.

Quick test

Read the project index with KaKeKiKoKu.

If Codex returns Transport closed, check the executable path, registration, installed versions, and startup diagnostics. On Windows, try the quiet wrapper if the symptoms match the linked stderr report. The error alone does not identify its cause.

5. Working in Precise mode

In Precise mode, KaKeKiKoKu cannot push messages to Codex CLI. The practical flow is:

• Start sessions through the startup instructions. They tell Codex to open KaKeKiKoKu projects immediately.
• Ask for sync. When code changes, KaKeKiKoKu detects out-of-date context in its UI; tell Codex to run sync when you want context updated.
• Paste copied prompts. KaKeKiKoKu's "Talk to AI" buttons copy text to the clipboard in Precise mode. Paste the prompt into Codex CLI.

Recommended KaKeKiKoKu configuration. Go to KaKeKiKoKu > Settings > Application > AI Sync and choose Precise mode.

6. Plan and model

KaKeKiKoKu does not require a special Codex model. Use Codex's current default or choose a model from Codex's own model controls.

KaKeKiKoKu loads context progressively with its search and read tools. It does not dump the whole project into the prompt.

OpenAI changes Codex models and defaults over time. Check OpenAI's Codex CLI documentation for current model and command-line behavior. Use --model for a one-off choice or the shared config.toml for a durable default.

7. Troubleshooting

Transport closed during tools/call

This message can have several causes. Verify the command with codex mcp list and check the client logs. If the failure matches the Windows stderr report, test the quiet wrapper. To replace a registration deliberately:

codex mcp remove wuniq

Then repeat the registration section for your OS.

codex is not recognized

Close and reopen the terminal after installation. The standalone installer normally places the command under %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows or ~/.local/bin on Linux. If you used npm, make sure the npm global bin directory is on PATH. Then run codex --version.

The installation, config, or login state looks inconsistent

Current Codex CLI builds include a diagnostic command for local installation, configuration, authentication, runtime, and thread inventory:

codex doctor

wuniq-mcp.exe is not found inside the wrapper

On Windows, check KaKeKiKoKu is installed and that %LOCALAPPDATA%\Microsoft\WindowsApps is on your PATH. Reopen the terminal after installing KaKeKiKoKu.

ChatGPT Desktop with Codex already works; should I change it?

No. Issue #7155 is a Windows CLI report, and the wrapper on this page is for the CLI host. Keep the working desktop configuration unless that surface shows its own reproducible problem.

Codex answers without using KaKeKiKoKu

1. Confirm AGENTS.md is loaded for the directory where you started Codex.
2. Ask explicitly: Use KaKeKiKoKu to read the project context before answering.
3. Run /mcp in Codex if available to inspect MCP server state.

KaKeKiKoKu can't see projects outside /home/ (Linux)

The KaKeKiKoKu snap is sandboxed by default and cannot read files outside your home folder unless you grant that permission. If your projects live in /mnt/, /media/, a USB drive, or a VM shared folder such as /mnt/hgfs/, run:

sudo snap connect wuniq:removable-media

Then reload the KaKeKiKoKu web UI and open the project again.

Hand-edited files saved with a BOM

If you created the wrapper or edited config.toml by hand and Codex fails to start KaKeKiKoKu, check the file encoding. Some editors — classic Notepad's UTF-8 option, or PowerShell's Set-Content -Encoding UTF8 — prepend a hidden 3-byte marker (a BOM) at the start of the file. It is invisible in the editor, but it breaks strict parsers and can corrupt the first line of a .cmd wrapper. Re-save the file as UTF-8 without BOM.

Still stuck?

Email support@kakekikoku.com with your OS, Codex CLI version, the wrapper content, and the KaKeKiKoKu MCP entry from ~/.codex/config.toml.