Shren207 Nixos Config Syncing Codex Harness

Claude Code -> Codex CLI Harness Sync

이 스킬은 현재 프로젝트의 Claude Code 하니스(스킬, 에이전트, MCP, 규칙)를 Codex CLI 호환 구조(.agents/, .codex/)로 프로젝션한다.

목적과 범위

프로젝트의 Claude 하니스를 Codex가 인식 가능한 디렉토리/설정 구조로 동기화하는 절차를 제공한다.

빠른 참조

MCP 섹션 가드 예시

mcp-config는 source 옵션 없이 호출하거나 --project-mcp/--plugin-mcp/--user-mcp source 파일이 없으면 fail-fast한다. 선택적 source를 다루는 호출자는 불필요한 실패를 피하기 위해 if [ -f X ]; then ...; fi 가드를 사용한다 — set -e 환경에서도 안전하다.

# 프로젝트 MCP 섹션만
if [ -f "$PWD/.mcp.json" ]; then
  bash "$SYNC_SH" mcp-config "$PWD" --project-mcp="$PWD/.mcp.json"
fi

# User-scope MCP 투영
if [ -f "$HOME/.claude/mcp.json" ]; then
  bash "$SYNC_SH" mcp-config "$PWD" --user-mcp="$HOME/.claude/mcp.json"
fi

추가 동작 노트:

• mcp-config는 source 옵션 (--project-mcp / --plugin-mcp / --user-mcp) 중 적어도 하나가 필요하다. source 없이 호출하거나 source path 파일이 없으면 sync.sh가 non-zero로 종료하며 기존 [mcp_servers.*] 섹션을 건드리지 않는다. --plugin-mcp는 PATH:INSTALL_PATH:NAME 형식이어야 한다.
• all 경로는 인자 조립 시점에 [ -f .mcp.json ] 가드를 두어 이 문제를 피한다.
• project-skills는 <source-skills-dir> <target-skills-dir> 두 인자를 모두 명시해야 한다. sync.sh는 set -u 아래에서 동작하므로 한 인자만 넘기면 즉시 unbound variable로 실패하고 종료한다 (투영이 0개로 끝나는 게 아니라 실행 자체가 멈춘다).
• set -e 가드 패턴 (단일 SoT): 위 if 가드 형태가 본 SKILL의 표준이다. 이전 test -f X && cmd 형태는 standalone statement 위치(함수/스크립트 마지막 또는 단독 실행)에서 false 평가 시 exit 1을 propagate해 set -e caller를 abort시킨다. if 조건 내부의 [ ... ] && [ ... ]은 단일 평가식이므로 안전하며 본 가이드의 금지 대상이 아니다.

sync.sh 스크립트 경로: 현재 SKILL.md가 위치한 디렉토리의 references/sync.sh를 사용하라. 예: 이 SKILL.md의 실제 경로가 ~/.claude/skills/syncing-codex-harness/SKILL.md이면 SYNC_SH=~/.claude/skills/syncing-codex-harness/references/sync.sh

Step 1: 소스 감지 (Detection)

프로젝트의 Claude Code 하니스 유형을 파악:

# 로컬 스킬 확인
LOCAL_SKILLS=0
if [ -d ".claude/skills" ]; then
  LOCAL_SKILLS=$(ls -d .claude/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
fi

# 플러그인 확인
PLUGIN_KEYS=()
if [ -f ".claude/settings.local.json" ]; then
  # enabledPlugins에서 true인 키 추출
  PLUGIN_KEYS=($(python3 -c "
import json, sys
try:
  d = json.load(open('.claude/settings.local.json'))
  for k, v in d.get('enabledPlugins', {}).items():
    if v: print(k)
except: pass
" 2>/dev/null))
fi

Step 2: 플러그인 해석 (Plugin Resolution)

플러그인 키마다 installPath를 찾는다:

resolve_plugin() {
  local plugin_key="$1"  # e.g. "sample-plugin@sample-marketplace"
  local manifest="$HOME/.claude/plugins/installed_plugins.json"

  python3 -c "
import json, os, sys
manifest = json.load(open('$manifest'))
entries = manifest.get('plugins', {}).get('$plugin_key', [])
pwd = os.getcwd()
local_path = user_path = None
for e in entries:
    scope = e.get('scope', '')
    if scope == 'local' and e.get('projectPath', '') == pwd:
        local_path = e['installPath']
    elif scope == 'user':
        user_path = e['installPath']
result = local_path or user_path
if result and os.path.isdir(result):
    print(result)
else:
    sys.exit(1)
" 2>/dev/null
}

매칭 규칙:

• scope: "local" -> projectPath가 $PWD와 정확히 일치 (우선)
• scope: "user" -> local 매칭 없을 때 적용
• installPath 디렉토리 미존재 -> 경고 후 건너뛰기 (플러그인 캐시 stale)
• 매칭 실패 -> 경고 후 건너뛰기

Step 3: 전체 재생성 (Full Regeneration)

Step 1-2에서 감지/해석한 결과를 sync.sh all 서브커맨드에 인자로 전달한다.

Note: sync.sh all은 항상 전체 재생성을 수행한다. .agents/는 매번 삭제 후 재생성되고, 프로젝트-로컬 .codex/config.toml은 [mcp_servers.*] 섹션만 교체된다 (사용자 설정 보존). 변경이 없어도 재실행해도 안전하다 (멱등). retired Codex hooks projection에서 남긴 .codex/hooks.json과 .codex/hooks.compatibility.json 잔재는 초기화 단계에서 명시적으로 삭제한다.

계약 참고: user-scope sync.sh vs activation writer

이 스킬의 sync.sh는 기본적으로 repo-local $PWD/.codex/config.toml의 [mcp_servers.*] 섹션만 LLM 요청에 따라 교체/보존하는 멱등 runner이다. 또한 --user-mcp가 지정되면 예외적으로 ~/.codex/config.toml의 [mcp_servers.*] 섹션만 함께 교체한다 (references/sync.sh의 mcp-config target 참조). 두 경우 모두 [mcp_servers.*] 외의 설정은 건드리지 않는다.

반면 Home Manager activation이 관리하는 ~/.codex/config.toml의 그 외 모든 키 (model, approval_policy, [features], [plugins.*] 등)는 별개 계약이며, 이 스킬이 손대지 않는다. 두 경로를 혼동하지 않도록 계약을 아래와 같이 나란히 둔다.

두 계약은 축이 다르다: activation writer가 ~/.codex/config.toml의 base state (repo-managed leaf 전체)를 유지하고, user-scope sync.sh는 $PWD/.codex/config.toml 전체를 소유하며 --user-mcp 옵션이 있을 때만 ~/.codex/config.toml의 [mcp_servers.*] 섹션에도 한정적으로 MCP 항목을 덧씌운다.

인자 구성

Step 1-2의 결과를 바탕으로 sync.sh all 인자를 구성한다:

SYNC_SH="<SKILL.md가 위치한 디렉토리>/references/sync.sh"

# 기본 인자
ARGS=()

# 로컬 스킬이 있으면 (Case A, C)
if [ -d ".claude/skills" ]; then
  ARGS+=(--local-skills-dir=.claude/skills)
fi

# 각 플러그인마다 (Case B, C)
# INSTALL_PATH: Step 2에서 해석한 installPath
# PLUGIN_NAME: plugin-key에서 @ 앞부분 (e.g. "sample-plugin")
ARGS+=(--plugin-install-path="$INSTALL_PATH:$PLUGIN_NAME")

# user-scope MCP까지 함께 투영하고 싶을 때 (선택)
# 빠른 참조의 "MCP 섹션 가드 예시"와 동일한 source 파일 존재 가드 정책 적용.
if [ -f "$HOME/.claude/mcp.json" ]; then
  ARGS+=(--user-mcp="$HOME/.claude/mcp.json")
fi

# 프로젝트에 CLAUDE.md가 없고, 플러그인이 CLAUDE.md를 제공하는 경우
if [ ! -e "CLAUDE.md" ] && [ -f "$INSTALL_PATH/CLAUDE.md" ]; then
  ARGS+=(--plugin-claude-md="$INSTALL_PATH/CLAUDE.md")
fi

실행

bash "$SYNC_SH" all "$PWD" "${ARGS[@]}"

진행상황이 stderr로 출력된다:

=== syncing-codex-harness: Full Sync ===
 [1/7] Initialized .agents/ and .codex/
 [2/7] AGENTS.md: symlinked|copied|skipped
 [3/7] Local skills: N
 [4/7] Plugin skills: N, Agents: N
 [5/7] Rules -> AGENTS.override.md: N
 [6/7] MCP config updated|no sources found
 [7/7] Trust: trusted|already-trusted|skipped
=== Sync complete ===

Codex 산출물의 git 추적

.agents/(스킬 심링크 트리), AGENTS.md, AGENTS.override.md는 Codex가 자동 발견하려면 프로젝트에 존재해야 하므로 커밋하는 것이 기본 운영 방식이다. 반면 .codex/는 프로젝트 MCP 설정(config.toml)을 담고 mcp-config가 .mcp.json의 env 시크릿을 평문 기록할 수 있어 글로벌 gitignore에서 계속 무시한다. 특정 산출물의 추적 여부를 바꾸려면 프로젝트 .gitignore에서 조정한다.

User-scope MCP 투영 (Claude -> Codex)

mcp-config는 프로젝트 스코프 외에 user-scope 변환도 지원한다.

# ~/.claude/mcp.json -> ~/.codex/config.toml
if [ -f "$HOME/.claude/mcp.json" ]; then
  bash "$SYNC_SH" mcp-config "$PWD" \
    --user-mcp="$HOME/.claude/mcp.json"
fi

# target 경로를 명시적으로 지정할 수도 있음
if [ -f "$HOME/.claude/mcp.json" ]; then
  bash "$SYNC_SH" mcp-config "$PWD" \
    --user-mcp="$HOME/.claude/mcp.json" \
    --user-codex-config="$HOME/.codex/config.toml"
fi

source 파일 존재 가드 정책의 단일 진실 원천은 위 "빠른 참조 > MCP 섹션 가드 예시"다. 두 예시 모두 같은 if [ -f ]; then ... fi 패턴을 따른다.

포맷 호환:

• Claude user-scope 형식: {"mcpServers": {...}}
• 레거시 형식: { "server-name": {...} }

개별 서브커맨드 (필요시)

all 대신 개별 단계를 실행할 수도 있다:

상세 사용법은 sync.sh 상단 Usage 참조.

Edge Cases

트러블슈팅

• installPath 해석 실패 시 플러그인 캐시 경로 존재 여부를 먼저 확인한다.
• 동기화 후 스킬이 안 보이면 .agents/skills/<name>이 디렉토리 심링크인지 확인한다.
• chrome-devtools-mcp 사용 시 동일 탭을 다른 도구(예: Claude in Chrome)와 동시 제어하지 않는다.

참조 문서

• references/sync.sh — 기계적 프로젝션 셸 스크립트
• references/mcp-conversion.md — MCP JSON->TOML 변환 가이드
• references/agents-override-template.md — AGENTS.override.md 템플릿
• references/codex-structure.md — Codex 프로젝트 구조 레퍼런스

Source: shren207/nixos-config — distributed by TomeVault.