Codex Claw

Bring your own AGENTS.md and SOUL.md style context into Codex Desktop with a small local plugin.

Codex Claw installs a SessionStart hook that injects the files in plugins/codex-claw/assets/ into each new Codex session as additional context. It is meant for people moving between OpenClaw-style workspaces and native Codex who want their agent preferences, voice, and collaboration notes available without manually pasting them every time.

The repo ships with safe placeholder files. Replace them with your own files before using it seriously (or have it link to the location of your agent's workspace files where they are!).

What it changes

This package adds:

• .agents/plugins/marketplace.json, so Codex can discover the local plugin marketplace.
• plugins/codex-claw/.codex-plugin/plugin.json, the plugin manifest.
• plugins/codex-claw/hooks.json, SessionStart and UserPromptSubmit hooks that run the loader.
• plugins/codex-claw/scripts/load-context.mjs, the hook script that reads AGENTS.md and SOUL.md.
• plugins/codex-claw/assets/AGENTS.md and plugins/codex-claw/assets/SOUL.md, the files you customize.
• plugins/codex-claw/skills/codex-claw/SKILL.md, a small helper skill for testing and reviewing the loader.

You also need these local Codex settings:

[features]
plugins = true
codex_hooks = true
plugin_hooks = true

[plugins."codex-claw@codex-claw"]
enabled = true

If your ~/.codex/config.toml already has a [features] table, merge the keys into the existing table instead of adding a second [features] block.

Install from GitHub

If you want to install the plugin directly from this repo:

codex plugin marketplace add 100yenadmin/Codex-Claw

If you are using Codex Desktop on macOS and codex is not on your PATH, use the bundled binary:

/Applications/Codex.app/Contents/Resources/codex plugin marketplace add 100yenadmin/Codex-Claw

Then point the plugin at your own files by creating ~/.codex/codex-claw.json:

{
  "agentsPath": "/absolute/path/to/AGENTS.md",
  "soulPath": "/absolute/path/to/SOUL.md",
  "mode": "full",
  "userPromptReinject": "after_compact"
}

Now edit ~/.codex/config.toml and add or merge:

[features]
plugins = true
codex_hooks = true
plugin_hooks = true

[plugins."codex-claw@codex-claw"]
enabled = true

Restart Codex Desktop.

Install from a local clone

Use this path if you want to edit the bundled placeholder files directly.

Clone the repo:

git clone https://github.com/100yenadmin/Codex-Claw.git
cd Codex-Claw

Put your own context files in place:

cp /path/to/your/AGENTS.md plugins/codex-claw/assets/AGENTS.md
cp /path/to/your/SOUL.md plugins/codex-claw/assets/SOUL.md

Add this repo as a Codex plugin marketplace:

codex plugin marketplace add "$PWD"

Then edit ~/.codex/config.toml and add or merge the same settings:

[features]
plugins = true
codex_hooks = true
plugin_hooks = true

[plugins."codex-claw@codex-claw"]
enabled = true

Restart Codex Desktop.

You can run a local sanity check from this repo:

node scripts/doctor.mjs

Quick test

Start a fresh Codex session and ask:

Do not use tools. If Codex Claw context was loaded into this session, reply FOUND CODEX_CLAW_CONTEXT and name the two source file headings you can see. If it was not loaded, reply NOT FOUND.

If it works, Codex should see a CODEX_CLAW_CONTEXT block with AGENTS.md and SOUL.md sections.

The hook writes a tiny diagnostic log to:

~/.codex/codex-claw-hook.log

The hook reads file paths from ~/.codex/codex-claw.json first. If that file does not exist, it falls back to the bundled placeholder files inside the plugin.

Post-Compaction Reinjection

Codex Claw now handles compaction in two layers:

• SessionStart includes a compact matcher for runtimes that restart hook context after compacting.
• UserPromptSubmit watches the transcript for compaction markers and reinjects context on the next user prompt after a new compaction.

The default policy is:

{
  "userPromptReinject": "after_compact"
}

That means Codex Claw does not resend your full files on every normal prompt. It only uses the prompt hook as a post-compaction recovery path.

Available policies:

• after_compact: reinject once after each detected compaction. This is the default.
• every_prompt: reinject on every user prompt. This is expensive and usually unnecessary.
• off: disable prompt-time reinjection.

You can also set the policy with an environment variable:

CODEX_CLAW_USER_PROMPT_REINJECT=every_prompt /Applications/Codex.app/Contents/MacOS/Codex

Modes

By default the hook loads both files. You can change behavior with CODEX_CLAW_MODE:

• full: load both files. This is the default.
• sentinel: load only a tiny marker, useful for testing hook visibility.
• off: do not inject context.

Example:

CODEX_CLAW_MODE=sentinel /Applications/Codex.app/Contents/MacOS/Codex

Compatibility review

Before treating a personal AGENTS.md or SOUL.md as always-on context, run the review prompts in docs/codex-compatibility-check.md.

That check is important because native Codex already has system, developer, tool, and workspace instructions. Your files should add taste, preferences, and useful routines. They should not ask Codex to ignore higher-priority instructions, invent unavailable tools, mutate files without permission, or treat personality text as stronger than safety and workflow rules.

Troubleshooting

See docs/troubleshooting.md.