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 Linux path installs KaKeKiKoKu from the Snap Store and has been validated with Codex CLI.

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.

Important: this guide includes a wrapper workaround. As of July 20, 2026, openai/codex#7155 remains open. The upstream report is about Codex CLI on Windows: it can fail with Transport closed when a stdio MCP server writes a lot of diagnostic output to stderr. KaKeKiKoKu uses the .NET MCP SDK, which can emit informational stderr lines, so Windows CLI users should register KaKeKiKoKu through a tiny quiet wrapper.

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. Create the quiet KaKeKiKoKu wrapper

On Windows, do not register the KaKeKiKoKu MCP command directly in Codex CLI while openai/codex#7155 is still open. Register a wrapper that forwards all arguments and redirects stderr away from Codex.

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

If you previously registered KaKeKiKoKu directly, remove the old 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 (Knowledge Engine)
   
   At the start of every session, run `open list` using the KaKeKiKoKu MCP tool. If it returns projects, `open` each one. If the list is empty, proceed normally — the user may open projects later from the KaKeKiKoKu UI. Never assume the working directory is a KaKeKiKoKu project; the working directory may be a container folder holding multiple projects. Only open paths that `open list` explicitly returns.
   
   Before working on any code file, `read` its KaKeKiKoKu sidecar for context. After changing code, run `sync`.

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

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, go back to the wrapper section. That error means Codex is probably still starting KaKeKiKoKu directly instead of through the quiet wrapper.

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 drift 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 is the known Codex CLI stderr transport issue reported for Windows. Confirm that codex mcp list points to your quiet wrapper, not directly to the KaKeKiKoKu MCP command. Remove and re-add if needed:

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.