cx-prompts : Manage per-project Codex prompts overlay

WARNINGS:

• This is an unofficial tool, not affiliated with OpenAI.
• Use at your own risk !
• Codex may change its behavior at any time, breaking this tool.
• Always backup your prompts before using this tool.
• This tool have only been tested on Linux.

Automatic per-project Codex prompts overlay

Use custom prompts from each project's .codex/prompts/ without manually copying them to ~/.codex/prompts/.

🎯 Problem Solved

Codex only looks for prompts in ~/.codex/prompts/ (home directory). This script creates automatic hardlinks from your projects to this global directory.

📦 Installation

# Install as global tool with uv (recommended)
uv tool install git+https://github.com/Hotion13/cx-prompts

# Or use directly with uvx (no installation)
uvx --from git+https://github.com/Hotion13/cx-prompts cx-prompts --help

# Local installation (development)
uv tool install .

🚀 Usage

1. Activate overlay for a project

# From project directory
cd /my/project
cx-prompts link

# Or from anywhere
cx-prompts link -p /my/project

Effect: All *.md files from /my/project/.codex/prompts/ are linked to ~/.codex/prompts/

2. Deactivate overlay

cx-prompts unlink

Effect: Removes only hardlinks created by this project (keeps others)

3. Check active overlays

cx-prompts status

Output:

Active overlays (2):

  • /home/user/projects/web-app
    5 linked prompts

  • /home/user/projects/api
    3 linked prompts

Index: /home/user/.codex/prompts/.cx_overlay.json

4. Temporary sub-shell (useful for testing)

cx-prompts shell

Effect:

1. Activates overlay
2. Launches bash sub-shell
3. Automatically cleans up on exit

📁 Expected Structure

my-project/
├── .codex/
│   └── prompts/
│       ├── review.md
│       ├── test.md
│       └── deploy.md
└── ...

After cx-prompts link:

~/.codex/prompts/
├── review.md   → /my-project/.codex/prompts/review.md
├── test.md     → /my-project/.codex/prompts/test.md
└── deploy.md   → /my-project/.codex/prompts/deploy.md

🔧 Features

✅ Hardlinks (Codex-compatible, no copying, no duplication) ✅ Idempotent (can run link multiple times safely) ✅ Smart index (tracks overlays per project) ✅ Automatic detection of project root (searches for .codex/) ✅ Safe cleanup (removes ONLY this project's hardlinks) ✅ Python 3.14+ (uses suggest_on_error, modern Path)

🛠️ Development

# Clone the repo
git clone https://github.com/Hotion13/cx-prompts
cd cx-prompts

# Install in dev mode with uv
uv tool install .

# Lint
uv run ruff check cx_prompts/

# Format
uv run ruff format cx_prompts/

🤔 Why Hardlinks?

Codex only supports hardlinks, not symlinks. Hardlinks provide:

• ✅ Automatic synchronization (same inode = same file)
• ✅ Compatible with Codex restrictions
• ⚠️ Requires source and destination to be on the same filesystem

📝 TODO / Future Improvements

• Automatic cd hook (fish/bash/zsh)
• Name conflict detection between projects
• Support subdirectories in .codex/prompts/
• cx-prompts doctor command (integrity check)

📄 License

MIT