feat(init): add Codex CLI support via AGENTS.md + RTK.md workflow by Zacaria · Pull Request #377 · rtk-ai/rtk

Zacaria · 2026-03-06T12:41:34Z

Summary

This PR adds minimal, opt-in Codex CLI support to rtk init while preserving the existing Claude default behavior.

What’s Included

Added --codex mode to init:
- rtk init --codex (local setup)
- rtk init -g --codex (global setup)
Added Codex-aware init --show and init --uninstall
Added validation for incompatible flag combinations:
- --codex + --claude-md => error
- --codex + --hook-only => error
Added idempotent AGENTS.md patching (@RTK.md is not duplicated)
Added Codex slim instructions file: hooks/rtk-awareness-codex.md
Refactored init internals for cleaner dispatch and separation:
- unified mode routing in run(...) via match
- extracted uninstall_claude(...)
- extracted show_claude_config(...)

Behavior

Codex mode

rtk init --codex
# creates/updates:
#   ./RTK.md
#   ./AGENTS.md (ensures @RTK.md exists once)

rtk init -g --codex
# creates/updates:
#   ~/.codex/RTK.md
#   ~/.codex/AGENTS.md (ensures @RTK.md exists once)

rtk init --show --codex
rtk init -g --codex --uninstall

Claude mode (unchanged)

If --codex is not passed, existing Claude flow remains unchanged.

Code Scope

src/main.rs
src/init.rs
hooks/rtk-awareness-codex.md

Validation

Ran:

rustfmt --check src/init.rs src/main.rs
cargo test --locked --bin rtk init::tests::

Result:

test result: ok. 27 passed; 0 failed

Out of Scope

No discover / learn Codex provider integration in this PR.
No broader cross-command adapter/provider refactor.

Zacaria · 2026-03-09T16:32:28Z

@FlorianBruniaux Can I do anything to push this forward ?
It should fix #169

pszymkowiak · 2026-03-11T21:02:46Z

Hi! Thanks for the contribution! Since March 6, all PRs should target the develop branch instead of master (see CONTRIBUTING.md).

Could you update the base branch? Click Edit at the top right of this PR and change it from master to develop.

Thanks!

pszymkowiak · 2026-03-11T21:54:01Z

Thanks for this @Zacaria! The AGENTS.md + RTK.md approach is exactly the right pattern — it mirrors how we do Claude Code integration and the idempotent patching is solid.

A few things to address before we can merge:

Scope — please split into 2 PRs:

The shim system (src/shim.rs, src/metadata.rs, rtk shim install) is a separate feature from Codex init support. Could you split this into two PRs?

PR A: rtk init --codex (AGENTS.md + RTK.md lifecycle) — this is what we want to merge first
PR B: rtk shim install (PATH shim system) — separate review and merge cycle

This reduces conflict surface and review risk significantly.

Must fix (for the Codex PR):

Missing .context() on file operations — fs::create_dir_all, fs::read_to_string, and fs::write in patch_agents_md / run_codex_mode need .with_context() for actionable error messages. See patch_claude_md for the pattern.
Emoji in show_codex_config output — RTK convention is plain ASCII, no emoji. Please replace 📋 ✅ ⚪ ⚠️ with text indicators (e.g., [ok], [--], [!!]).
DCO sign-off — commits need Signed-off-by line (git commit -s). See CONTRIBUTING.md.

Nice to fix:

_verbose ignored in uninstall_codex — uninstall_claude logs paths at verbose > 0. Codex uninstall should do the same.
--auto-patch silently ignored with --codex — the warning only prints with -v. Should print regardless, or bail like --claude-md does.
Test coverage — only 1 test (test_patch_agents_md_adds_reference_once). Would be great to add: uninstall idempotency, migration path, empty AGENTS.md creation.
fs::write should use atomic_write for AGENTS.md — patch_claude_md uses it to prevent truncation on interruption.

Zacaria · 2026-03-12T08:01:48Z

Thanks for the review. I addressed the points as follows:

Scope / split into 2 PRs
The shim work has been split out of this PR. master now only contains the Codex init changes for rtk init --codex, and I moved the shim work to a separate branch: feat/codex-shim.
Missing .context() on file operations
Fixed. I added contextual error messages for the Codex file operations in run_codex_mode / patch_agents_md, following the same pattern as the Claude path.
Emoji in show_codex_config output
Fixed. The Codex config output now uses ASCII-only status markers: [ok], [--], [!!].
DCO sign-off
Fixed.
--auto-patch silently ignored with --codex
Fixed. --codex now rejects --auto-patch and --no-patch explicitly instead of silently ignoring them.
Test coverage
Expanded. I added coverage for:

codex + --auto-patch rejection
codex + --no-patch rejection
empty AGENTS.md creation
inline block migration
Codex uninstall idempotency

AndyBevan · 2026-03-13T13:54:31Z

Thanks for doing this work @Zacaria and @pszymkowiak - I came here for exactly this reason, was going to help with a contribution, but as if by magic someone had got there already. I look forward to seeing this out in the wild soon.

* fix: P1 exit codes, grep regex perf, SQLite concurrency Exit code propagation (same pattern as existing modules): - wget_cmd: run() and run_stdout() now exit on failure - container: docker_logs, kubectl_pods/services/logs now check status before parsing JSON (was showing "No pods found" on error) - pnpm_cmd: replace bail!() with eprint + process::exit in run_list and run_install Performance: - grep_cmd: compile context regex once before loop instead of per-line in clean_line() (was N compilations per grep call) Data integrity: - tracking: add PRAGMA journal_mode=WAL and busy_timeout=5000 to prevent SQLite corruption with concurrent Claude Code instances Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> * fix: address review findings on P1 fixes - tracking: WAL pragma non-fatal (NFS/read-only compat) - wget: forward raw stderr on failure, track raw==raw (no fake savings) - container: remove stderr shadow in docker_logs, add empty-stderr guard on all 4 new exit code paths for consistency with prisma pattern Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> --------- Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

… (rtk-ai#630) * fix: raise output caps for grep, git status, and parser fallback (rtk-ai#617, rtk-ai#618, rtk-ai#620) - grep: per-file match cap 10 → 25, global max 50 → 200 - git status: file list caps 5/5/3 → 15/15/10 - parser fallback: truncate 500 → 2000 chars across all modules These P0 bugs caused LLM retry loops when RTK returned less signal than the raw command, making RTK worse than not using it. Fixes rtk-ai#617, rtk-ai#618, rtk-ai#620 Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> * fix: update README example and add truncation tests for modified/untracked - parser/README.md: update example from 500 → 2000 to match code - git.rs: add test_format_status_modified_truncation (cap 15) - git.rs: add test_format_status_untracked_truncation (cap 10) Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> * refactor: extract output caps into [limits] config section Move hardcoded caps into config.toml so users can tune them: [limits] grep_max_results = 200 # global grep match limit grep_max_per_file = 25 # per-file match limit status_max_files = 15 # staged/modified file list cap status_max_untracked = 10 # untracked file list cap passthrough_max_chars = 2000 # parser fallback truncation All 8 modules now read from config::limits() instead of hardcoded values. Defaults unchanged from previous commit. Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> --------- Signed-off-by: Patrick <patrick@rtk.ai> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

FurkanCodes · 2026-03-16T18:50:41Z

Appreciate the hard work, eager to see this merged!

…es (rtk-ai#662) * feat(.claude): add /rtk-triage skill — orchestrated PR+issue cross-analysis New skill that runs issue-triage + pr-triage in parallel then produces a cross-analysis layer that neither skill can do individually: - Double coverage detection: identifies when 2+ PRs target the same issue (via body scan + file overlap), recommends which to keep/close - Security gap detection: for security review issues, maps each finding to a PR (or flags it as uncovered) - P0/P1 bugs without PR: groups by pattern to suggest sprint batching - Our dirty PRs: identifies probable cause (conflict with sibling PR, needs rebase, missing linked issue) Output is saved automatically to claudedocs/RTK-YYYY-MM-DD.md. Usage: /rtk-triage (French, auto-save) /rtk-triage en (English output) Signed-off-by: Florian Bruniaux <florian@bel-etage.com> Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com> * docs(architecture): update module count to 66 Sync ARCHITECTURE.md with current main.rs state. Previous count (60) was stale since several modules were added (dotnet_cmd, dotnet_format_report, dotnet_trx, npm_cmd, gt_cmd, etc.). Signed-off-by: Florian Bruniaux <florian@bel-etage.com> Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com> --------- Signed-off-by: Florian Bruniaux <florian@bel-etage.com> Signed-off-by: Florian BRUNIAUX <florian@bruniaux.com>

…tk-ai#601) - git stash: pass unknown subcommands (save, branch, clear) through instead of silently falling back to git stash push - git branch: add --show-current, --set-upstream-to, --format, --sort to flag detection so they don't get overridden by -a injection - pip: replace bail!() with passthrough for unknown subcommands (freeze, download, wheel, etc.) Fixes rtk-ai#600 Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

cargo fmt diffs in config.rs, git.rs, playwright_cmd.rs were failing the fmt CI check, which cascaded to block clippy/test/security on PRs rtk-ai#632, rtk-ai#635, rtk-ai#638. Also fixes all clippy warnings: dead code annotations, iterator simplifications, assert patterns, and unnecessary allocations. Signed-off-by: Patrick Szymkowiak <patrick@rtk-ai.app> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

…#163) (rtk-ai#518) * fix: discover classifies absolute paths like /usr/bin/grep (rtk-ai#485) Normalize absolute binary paths before classification: /usr/bin/grep → grep, /bin/ls → ls, /usr/local/bin/git → git Adds strip_absolute_path() helper + 5 tests. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> * fix: discover and rewrite support git global options -C, --no-pager, etc. (rtk-ai#163) Strip git global options (-C <path>, -c <key=val>, --git-dir, --work-tree, --no-pager, --no-optional-locks, --bare, --literal-pathspecs) before classification so git -C /tmp status is recognized as rtk git. Rewrite preserves global options: git -C /tmp status → rtk git -C /tmp status Adds GIT_GLOBAL_OPT lazy_static regex + strip_git_global_opts() helper + 6 tests. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> --------- Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

…-ai#519) When running `rtk cargo clippy -p my-crate -- -D warnings`, Clap with `trailing_var_arg = true` preserves the `--` in parsed args when flags precede it. `restore_double_dash()` then added a second `--`, producing `cargo clippy -p my-crate -- -- -D warnings`. This caused rustc to interpret `-D` as a filename instead of a lint flag. Fix: skip restoration when args already contain `--` (Clap preserved it). Fixes rtk-ai#496 Signed-off-by: Ousama Ben Younes <benyounes.ousama@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

- PR template reminds contributors to target develop - CI workflow labels PRs targeting master with 'wrong-base' and posts a comment - Excludes develop→master PRs (maintainer releases) Signed-off-by: Patrick <patrick@rtk-ai.com> Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

Add Language::Data variant for data formats (JSON, YAML, TOML, XML, CSV, etc.) with empty comment patterns to prevent comment stripping. AggressiveFilter falls back to MinimalFilter for data files. Fixes rtk-ai#464 Signed-off-by: Ousama Ben Younes <benyounes.ousama@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

…tk-ai#439) (rtk-ai#563) rtk find outputs a grouped format incompatible with pipe consumers like xargs, grep, wc, sort. Skip rewrite when find/fd is followed by a pipe, preserving native one-per-line output. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

…gh (rtk-ai#427) (rtk-ai#564) When compact_diff truncates output, append a hint line so Claude knows how to get the full diff: [full diff: rtk git diff --no-compact] Also fix --no-compact flag being passed to git (causing usage error) and remove decorative emoji from compact_diff output. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

rtk-ai#632) 4 P1 bugs where git exit codes were swallowed: - git diff: failure silently printed empty stat output - git status (with args): failure was filtered instead of propagated - git commit: failure printed "FAILED" but returned Ok(()) breaking pre-commit hooks - git branch (list mode): failure was silently ignored All now follow the established pattern: eprint stderr, track raw==raw, process::exit(code). Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

…tk-ai#635) * feat: add 5 new TOML built-in filters (ollama, nx, gradle, spring-boot, jira) New filters for commands not covered by Rust modules: - ollama: strip ANSI spinners, keep final text response (rtk-ai#624) - nx: strip Nx monorepo noise, keep build results (rtk-ai#444) - gradle/gradlew: strip UP-TO-DATE tasks, keep build summary (rtk-ai#147) - spring-boot: strip banner and verbose logs, keep startup/errors (rtk-ai#147) - jira: strip blanks, truncate wide columns (rtk-ai#524) All 5 filters pass inline tests via rtk verify (123/123). Updated builtin filter count: 47 -> 52. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> * feat: add 5 more TOML filters (turbo, mise, just, task, yadm) New filters for task runners and git wrapper: - turbo: strip cache/Tasks/Duration noise, keep task output (rtk-ai#531) - mise: strip install/download progress, keep task results (rtk-ai#607) - just: strip blanks and recipe headers, keep output (rtk-ai#607) - task: strip task headers and up-to-date lines, keep results (rtk-ai#607) - yadm: strip hint lines, compact git-like output (rtk-ai#567) All verified with fake binaries through catch-all TOML engine. 137/137 TOML tests pass, 934 Rust tests pass. Updated builtin filter count: 52 -> 57. Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu> --------- Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

…rtk-ai#638) Git status output used emojis (📌, 📝, ❓, ✅, ⚠️) that confuse non-Claude LLMs (GPT, etc.) causing retry loops. Replace with plain text labels (branch:, modified:, staged:, untracked:, conflicts:). Also add "clean — nothing to commit" when working tree is clean, so LLMs understand the repo state without ambiguity. Before: 📌 master After: branch: master clean — nothing to commit Fixes rtk-ai#603 Signed-off-by: Patrick szymkowiak <patrick.szymkowiak@innovtech.eu>

Add --codex mode to rtk init for Codex CLI integration using AGENTS.md + RTK.md, while keeping the newer develop init/opencode flow intact. Includes Codex install/show/uninstall handling, ASCII status output, stricter flag validation, and expanded tests for Codex AGENTS lifecycle and patch-mode rejection. Signed-off-by: Zacaria <havesomecode@gmail.com>

Signed-off-by: Zacaria <havesomecode@gmail.com>

Zacaria mentioned this pull request Mar 6, 2026

Add support/installation for Codex #169

Open

Zacaria mentioned this pull request Mar 10, 2026

[feat] Add shim to make rtk work with Codex #424

Open

pszymkowiak mentioned this pull request Mar 11, 2026

feat: add Codex CLI integration via skill #357

Open

Zacaria changed the base branch from master to develop March 12, 2026 07:27

Zacaria force-pushed the master branch 2 times, most recently from 18b3a57 to a3505f0 Compare March 12, 2026 07:59

Zacaria mentioned this pull request Mar 12, 2026

feat(init): add Codex CLI init support via AGENTS.md + RTK.md #529

Closed

pszymkowiak requested a review from aeppling March 13, 2026 09:21

Zacaria force-pushed the master branch from 174a65d to 8a52c98 Compare March 13, 2026 09:49

pszymkowiak added 2 commits March 16, 2026 14:58

FlorianBruniaux and others added 13 commits March 17, 2026 15:35

docs: fix validation metadata

2e9b1f1

Signed-off-by: Zacaria <havesomecode@gmail.com>

Zacaria force-pushed the master branch from 8a52c98 to 2e9b1f1 Compare March 17, 2026 18:05

pszymkowiak force-pushed the develop branch from d400e71 to 8fae5b0 Compare March 18, 2026 09:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(init): add Codex CLI support via AGENTS.md + RTK.md workflow#377

feat(init): add Codex CLI support via AGENTS.md + RTK.md workflow#377
Zacaria wants to merge 16 commits intortk-ai:developfrom
Zacaria:master

Zacaria commented Mar 6, 2026

Uh oh!

Zacaria commented Mar 9, 2026

Uh oh!

pszymkowiak commented Mar 11, 2026

Uh oh!

pszymkowiak commented Mar 11, 2026

Uh oh!

Zacaria commented Mar 12, 2026

Uh oh!

AndyBevan commented Mar 13, 2026 •

edited

Loading

Uh oh!

FurkanCodes commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

Zacaria commented Mar 6, 2026

Summary

What’s Included

Behavior

Codex mode

Claude mode (unchanged)

Code Scope

Validation

Out of Scope

Uh oh!

Zacaria commented Mar 9, 2026

Uh oh!

pszymkowiak commented Mar 11, 2026

Uh oh!

pszymkowiak commented Mar 11, 2026

Uh oh!

Zacaria commented Mar 12, 2026

Uh oh!

AndyBevan commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FurkanCodes commented Mar 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

AndyBevan commented Mar 13, 2026 •

edited

Loading