justin/ClaudeForge
1
0
Fork 0
mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 02:13:15 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
7d22a50c37978d20d4347825f6a6c9c0c5191310
ClaudeForge/command/claude-to-agents.md
T
Claude 7d22a50c37 feat(plugin): /claude-to-agents — convert CLAUDE.md to AGENTS.md for codex / gemini users 
Cross-tool adoption. Codex, Gemini Code Assist, and any AI tool honouring
the AGENTS.md convention can now read the same instructions as Claude,
without the user maintaining two files by hand.

hooks/claude-to-agents.py (new, standalone, idempotent):
  - argparse: --mode={symlink,copy,inline-chain} (default symlink),
    --source (default CLAUDE.md), --output (default AGENTS.md), --force.
  - Symlink mode: ln -s CLAUDE.md AGENTS.md. Windows falls back to
    --copy with a stderr notice.
  - Copy mode: byte-for-byte snapshot via shutil.copyfile.
  - Inline-chain mode: depth-first walk of @path imports, recursive,
    cycle-safe (each file read at most once). Output flattens every
    chained sub-file under <!-- inlined from <rel> --> markers and
    strips two flavours of Claude-only scaffolding:
      • The @path import lines themselves (other tools don't resolve
        them).
      • Backlink quote-blocks ("> Parent context: ..." /
        "> Chained import: `@../CLAUDE.md`") that we emit on every
        sub-CLAUDE.md.
  - Safety: existing AGENTS.md (file or symlink) is renamed to
    AGENTS.md.backup.<UTC-ts> before overwrite. --force skips the
    backup. Microsecond timestamp precision so back-to-back writes
    don't collide.
  - Exit codes: 0 success, 1 user error (missing source / unknown
    mode), 2 filesystem error (symlink failure).

command/claude-to-agents.md (new slash command):
  - allowed-tools: Read, Write, Glob, Bash(python3:*), Bash(ls:*),
    Bash(test:*), Bash(readlink:*).
  - disallowedTools: WebFetch, WebSearch (no exfiltration vector).
  - argument-hint and when_to_use surface the three modes.
  - Body specifies a heuristic: default to --symlink for single-file
    projects, recommend --inline-chain when find . -name CLAUDE.md
    returns more than one. Documents per-mode verification commands.

.claude-plugin/plugin.json:
  Registers ./command/claude-to-agents.md alongside the existing two.

install.sh + install.ps1:
  Banner and uninstall sections list the new command. The command
  install loop already iterates command/*.md so the file itself is
  copied automatically.

README.md:
  /claude-to-agents added to "What's Included" under Slash commands
  with a one-paragraph description covering all three modes.
  Quick Stats: "2 slash commands" -> "3 slash commands".

CHANGELOG.md:
  New "wave 5" entry under [Unreleased].

Verified (7/7 integration checks):
  - Plugin manifest registers the command; all 9 referenced paths
    resolve on disk.
  - Slash command frontmatter has all required fields including
    WebFetch in disallowedTools.
  - Script has executable bit set.
  - Both install scripts list claude-to-agents.md.
  - install.sh passes bash -n.
  - End-to-end against a synthetic chained CLAUDE.md tree with a
    deliberate back-import cycle: symlink mode creates valid symlink;
    copy mode produces bytewise-identical AGENTS.md and backs up the
    prior symlink (1 backup); inline-chain mode inlines both
    sub-files, strips backlinks AND chain-import lines, handles the
    cycle (each file read once), backs up the prior file (2 backups
    total).
  - Missing source returns rc=1 with stderr message.
2026-05-19 02:04:00 +00:00

3.2 KiB
Raw Blame History

description, argument-hint, when_to_use, allowed-tools, disallowedTools, permissions
description argument-hint when_to_use allowed-tools disallowedTools permissions
Convert the project's CLAUDE.md (and chained sub-files) into an AGENTS.md for Codex / Gemini Code Assist / other tools that follow the AGENTS.md convention. Three modes — symlink for one source of truth, copy for a snapshot, inline-chain for a self-contained flat file that doesn't depend on @-import resolution. [--symlink | --copy | --inline-chain] [--force] Use when the user asks "make an AGENTS.md", "support codex", "support gemini", "convert CLAUDE.md", "share my instructions with non-Claude tools", or when adopting ClaudeForge in a repo that already has cross-tool contributors.
Read
Write
Glob
Bash(python3:*)
Bash(ls:*)
Bash(test:*)
Bash(readlink:*)
WebFetch
WebSearch
allow
Read
Write
Glob
Bash(python3:*)
Bash(ls:*)
Bash(test:*)
Bash(readlink:*)

/claude-to-agents — convert CLAUDE.md → AGENTS.md

Wraps hooks/claude-to-agents.py so non-Claude tools (OpenAI Codex, Gemini Code Assist, anything else honouring the AGENTS.md convention) can read the same instructions as Claude.

Mode selection

Decide first by asking which guarantee the user wants:

  • --symlink (default on macOS / Linux): AGENTS.md becomes a symlink to CLAUDE.md. One source of truth — edits to CLAUDE.md show up in AGENTS.md instantly. Codex/Gemini read it transparently. On Windows the script falls back to --copy and prints a notice.
  • --copy: byte-for-byte snapshot. Use when the user wants to fork the instructions for non-Claude tooling (Codex/Gemini reading a different policy) or when their VCS / build pipeline doesn't follow symlinks.
  • --inline-chain: walk every @path/.../CLAUDE.md chain import recursively and write a single flat AGENTS.md with all sub-file content inlined. Recommended for Codex/Gemini in modular projects — those tools don't resolve @-imports, so without inlining they'd only see the root file.

If the user is silent on mode, default to --symlink for simple projects and recommend --inline-chain for projects with > 1 CLAUDE.md (run find . -name CLAUDE.md -type f -not -path '*/.git/*' -not -path '*/node_modules/*' | wc -l first to decide).

Execution

  1. Pre-flight. test -f CLAUDE.md — if missing, tell the user /enhance-claude-md is the right command first.
  2. Run the script with the chosen flags from the repo root: 
    python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/hooks/claude-to-agents.py" --mode <mode>
  3. Report. Echo whether AGENTS.md was created or backed up, its size, and which mode produced it.
  4. Verify the result:
    • For --symlink: readlink AGENTS.md should print CLAUDE.md.
    • For --copy: diff -q CLAUDE.md AGENTS.md should return clean.
    • For --inline-chain: AGENTS.md must contain content from every chained sub-file; the script strips backlinks and @-import lines automatically.

Safety

  • An existing AGENTS.md is renamed to AGENTS.md.backup.<UTC-timestamp> before overwrite. Pass --force to skip the backup (destructive).
  • The script never writes outside the current directory tree.
  • Read-only modes (--symlink) leave CLAUDE.md untouched.
Reference in New Issue View Git Blame Copy Permalink