feat: Initial commit of Codex CLI Extensions (cdx) with comprehensive project structure, installation scripts, and plugin management

- Added entrypoint script `cdx/cdx.sh` for command routing and plugin execution.
- Implemented installation script `cdx/install.sh` for setting up the CLI in user environments.
- Created plugin scripts for profiles, prompts, updates, and resume functionalities.
- Introduced fast-tools prompt management in `cdx/agents/fast-tools.md`.
- Established smoke test script `cdx/smoke-test.sh` for validating installation and functionality.
- Documented repository guidelines and usage instructions in `AGENTS.md` and `README.md`.
- Added support for managing custom prompts and dependencies installation.

Author: chongdashu

AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `cdx/cdx.sh` — entrypoint; sources a `cdx` shell function and `cx` alias.
+- `cdx/plugins/` — subcommands invoked as `cdx <name>` (e.g., `profiles.sh`, `prompts.sh`, `update.sh`).
+- `cdx/prompts/` — optional prompt files (Markdown). See `cdx/plugins/prompts.sh`.
+- `cdx/agents/fast-tools.md` — reusable prompt to append to this file.
+- `cdx/scripts/` — utility scripts (e.g., `setup-fast-tools.sh`).
+- `cdx/install.sh`, `cdx/smoke-test.sh` — installer and health check.
+Note: When embedding in another repo, `tools/cdx/**` is the recommended path. Set `REPO_PROMPTS_DIR` to override prompt source if layouts differ.
+
+## Build, Test, and Development Commands
+- Load locally: `source cdx/cdx.sh && cdx help` (defines `cdx` in your shell).
+- Smoke test: `bash cdx/smoke-test.sh` (verifies sourcing, plugins, prompts, update check).
+- Install to shell: `bash cdx/install.sh [--with-prompts]`.
+- Update Codex CLI: `cdx update --check-only` or `cdx update [--sudo]`.
+- Prompts: `cdx prompts list` • `cdx prompts install` • `cdx prompts path`.
+- Profiles: `cdx profiles` or `cdx profiles --quiet`.
+
+## Coding Style & Naming Conventions
+- Bash with `set -euo pipefail`; 2‑space indent; quote variables; prefer arrays.
+- Functions/locals: `snake_case`; env: `SCREAMING_SNAKE_CASE` (e.g., `CODEX_BIN`).
+- Prefer `printf` over `echo -e` and explicit `return`/exit codes.
+- Plugins live in `cdx/plugins/<name>.sh` and are invoked as `cdx <name>`.
+
+## Testing Guidelines
+- Lint: `shellcheck cdx/**/*.sh` (aim for zero warnings).
+- Format: `shfmt -i 2 -sr -w cdx`.
+- Syntax check: `bash -n cdx/**/*.sh`.
+- Keep `cdx/smoke-test.sh` green; add focused tests near changed scripts when practical.
+
+## Commit & Pull Request Guidelines
+- No history exists yet; use Conventional Commits (e.g., `feat:`, `fix:`, `docs:`).
+- PRs should describe behavior, list key commands/output, and link issues.
+- Update `README.md`/`--help` text when CLI surfaces change; include before/after examples.
+
+## Agent-Specific Instructions
+- For repo-wide search, use `rg` (ripgrep) and `fd/fdfind`; avoid `grep/find`.
+- Cap file reads at ~250 lines; prefer `rg -n -A3 -B3` for context.
+- Use `jq` for JSON parsing.
+- Append the fast-tools prompt (idempotent): `bash cdx/scripts/setup-fast-tools.sh [--install-deps]`.
+

README.md

@@ -0,0 +1,77 @@
+# Codex CLI Extensions (cdx)
+
+![Bash](https://img.shields.io/badge/Bash-4%2B-1f425f?logo=gnu-bash&logoColor=white)
+![OS](https://img.shields.io/badge/OS-macOS%20%7C%20Linux-lightgrey)
+![Type](https://img.shields.io/badge/Type-CLI%20Helpers-blue)
+
+Lightweight, POSIX‑friendly helpers that enhance the Codex CLI with a single entrypoint, plugin routing, prompt management, and a quick smoke test. Use directly or vendor under `tools/cdx/` in your own repo.
+
+## Why cdx
+- Fast: source one file and get a tidy `cdx` wrapper + `cx` alias.
+- Extensible: drop scripts in `cdx/plugins/` and call `cdx <name>`.
+- Practical: ship prompts and install them to `~/.codex/prompts`.
+- Safe: smoke test validates sourcing, plugins, and update checks.
+
+## Quick Start
+- From this repo (local install):
+  ```bash
+  # Add cdx to your shell
+  bash cdx/install.sh --with-prompts   # optional: copies prompts
+  # Or for a temporary session
+  source cdx/cdx.sh && cdx help
+  ```
+- One‑liner (template for vendored copies):
+  ```bash
+  # Replace OWNER/REPO/BRANCH with your values
+  bash <(curl -fsSL https://raw.githubusercontent.com/OWNER/REPO/BRANCH/tools/cdx/install.sh) --with-prompts
+  ```
+
+## Usage
+```bash
+cdx help            # usage and discovered plugins
+cdx plugins         # list subcommands from cdx/plugins/
+cdx prompts list    # show repo and installed prompts
+cdx prompts install # install prompts to ~/.codex/prompts
+cdx profiles        # list profiles from ~/.codex/config.toml
+cdx update --check-only  # check Codex CLI updates (uses npm)
+cdx -- --profile NAME     # pass through to codex with defaults
+cdx raw <args>            # run codex without defaults
+```
+
+## Repo at a Glance
+```text
+cdx/
+  cdx.sh            # entrypoint defines `cdx` and alias `cx`
+  plugins/          # profiles.sh, prompts.sh, update.sh, resume.sh
+  prompts/          # optional Markdown prompts
+  agents/           # reusable prompts (e.g., fast-tools.md)
+  scripts/          # setup-fast-tools.sh and utilities
+  smoke-test.sh     # non-destructive health check
+```
+
+## Repository Layout
+- `cdx/cdx.sh` — entrypoint defining the `cdx` function and `cx` alias.
+- `cdx/plugins/` — subcommands (`profiles.sh`, `prompts.sh`, `update.sh`, `resume.sh`).
+- `cdx/prompts/` — optional Markdown prompts for Codex.
+- `cdx/agents/fast-tools.md` — reusable prompt you can append to `AGENTS.md`.
+- `cdx/scripts/` — utilities (e.g., `setup-fast-tools.sh`).
+- `cdx/smoke-test.sh` — non‑destructive health check.
+
+## Embed In Your Repo
+Vendor as `tools/cdx/**` and call the installer from your repo root:
+```bash
+bash tools/cdx/install.sh --with-prompts
+```
+If your prompts live elsewhere, set `REPO_PROMPTS_DIR=/path/to/prompts` before running `cdx prompts`.
+
+> Tip: Append the fast‑tools prompt to `AGENTS.md` with `bash cdx/scripts/setup-fast-tools.sh` (idempotent; add `--install-deps` to install rg/fd/jq).
+
+## Requirements & Troubleshooting
+- Bash 4+, macOS/Linux; Windows via WSL or Git Bash.
+- `npm` optional (only for `cdx update`). If `codex` is not on PATH after update, check `npm prefix -g` and your shell rc file.
+
+## Contributing
+See `AGENTS.md` for style, testing, and PR conventions. Please keep the smoke test green: `bash cdx/smoke-test.sh`.
+
+—
+Quick links: `AGENTS.md` · `cdx/README.md`

cdx/agents/fast-tools.md

@@ -0,0 +1,30 @@
+<!-- FAST-TOOLS PROMPT v1 | codex-mastery | watermark:do-not-alter -->
+
+## CRITICAL: Use ripgrep, not grep
+
+NEVER use grep for project-wide searches (slow, ignores .gitignore). ALWAYS use rg.
+
+- `rg "pattern"` — search content
+- `rg --files | rg "name"` — find files
+- `rg -t python "def"` — language filters
+
+## File finding
+
+- Prefer `fd` (or `fdfind` on Debian/Ubuntu). Respects .gitignore.
+
+## JSON
+
+- Use `jq` for parsing and transformations.
+
+## Install Guidance
+
+- macOS: `brew install ripgrep fd jq`
+- Debian/Ubuntu: `sudo apt update && sudo apt install -y ripgrep fd-find jq` (alias `fd=fdfind`)
+
+## Agent Instructions
+
+- Replace commands: grep→rg, find→rg --files/fd, ls -R→rg --files, cat|grep→rg pattern file
+- Cap reads at 250 lines; prefer `rg -n -A 3 -B 3` for context
+- Use `jq` for JSON instead of regex
+
+<!-- END FAST-TOOLS PROMPT v1 | codex-mastery -->