kronael-install

name	kronael-install
description	Install/update Kronael (bundle + CLI tools rig/udfix/clp/dockbox); bridge global/project CLAUDE.md, skills, and hooks into Codex.

Kronael Install

ALWAYS install the existing Claude Code bundle from the marketplace source snapshot. NEVER copy or port the bundle into the Codex plugin directory.

The installed Codex plugin contains only this installer skill. It does NOT contain the Kronael Claude skills. Codex sees those skills only through the Codex Bridge (~/.agents/skills or project .agents/skills). For install requests from Codex, create the global bridge and install Codex hook wiring automatically after the Claude install succeeds.

Invocation

Users usually invoke:

Use @kronael-install to install/update Kronael.

If the user says "install kronael" without naming this skill, still run this workflow.

If the user asks only to make Codex see the installed skills, or says skills are missing after install, skip the install workflow and use the Codex Bridge section.

Source Root

For install/update requests, find the source root by checking, in order:

1. Ancestors of cwd.
2. Ancestors of this skill's path.
3. Codex marketplace snapshots:
   • $CODEX_HOME/.tmp/marketplaces/*
   • ~/.codex/.tmp/marketplaces/*

The source root is the first directory where all of these exist:

• kronael/install/SKILL.md
• kronael/install/reference.md
• skills/
• agents/
• hooks/
• codex-hooks.json
• settings-recommended.json
• RECLAUDE.md
• codex/AGENTS.md

NEVER use the installed plugin cache as the bundle source unless it contains all files above; normal plugin installs cache only this bridge skill.

If no source root is found, ask the user to run codex plugin marketplace add kronael/tools or codex plugin marketplace upgrade kronael (kronael-local for older installs), then start a fresh Codex thread. NEVER invent paths. The Codex plugin is only an installer bridge; the GitHub marketplace snapshot owns the bundle.

For Codex Bridge-only requests, discover the source root when the requested bridge step needs source-owned files (codex-hooks.json or per-skill symlinks). Skip source-root discovery only for global/project CLAUDE.md bridging or the simple ~/.agents/skills -> ~/.claude/skills symlink case.

Install

1. Read kronael/install/SKILL.md completely, plus the kronael/install/reference.md it points to (tool commands + prune list).
2. Follow them as the source of truth.
3. Treat the discovered source root as the canonical install source. NEVER run /kronael:install; that is a Claude Code slash command.
4. Execute the canonical installer's steps exactly as written there — the new-install plan/consent questionnaire, sync protocol, backup, copy assets (incl. the create-* prune list), install wisdom, merge the Claude hooks block, install Codex hook wiring, external tools, CLI tools (rig/udfix/clp/dockbox — the marketplace snapshot carries their source dirs), verify. Present the questionnaire inline as numbered options. NEVER restate or fork those steps here; that file is the only source of truth and copies drift.
5. After successful install from Codex, run the global guidance, installed skills, and hooks bridges below. This is part of the Codex install path.

Codex Bridge

Use these steps when the user asks Codex to use Claude global/project guidance or installed skills. Bridge with symlinks instead of copying.

Global CLAUDE.md

Codex loads global instructions from ~/.codex/AGENTS.override.md, or from ~/.codex/AGENTS.md when no override exists. It does not discover ~/.claude/CLAUDE.md globally. If both Codex files are absent, create:

ln -s ~/.claude/CLAUDE.md ~/.codex/AGENTS.md

If the symlink already resolves to ~/.claude/CLAUDE.md, report "already bridged". Treat any other existing AGENTS.md or AGENTS.override.md as a conflict and ask whether to replace, merge, or skip. NEVER overwrite it.

Project CLAUDE.md

To make Claude-only projects work in Codex, add CLAUDE.md as a fallback instruction filename in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

ALWAYS keep this as a top-level TOML key: insert it before the first [table] header, or append CLAUDE.md to the existing top-level fallback array. NEVER hand-append it after the current table header; in TOML that makes it part of the table. NEVER leave CLAUDE.md under [tui] or [tui.model_availability_nux] — move it to the top-level key.

If a project already has AGENTS.md, Codex will not also load CLAUDE.md as a fallback in the same directory. The installed global Kronael block in ~/.codex/AGENTS.md therefore ALWAYS tells Codex to actively read applicable CLAUDE.md files in addition to loaded AGENTS.md files. For repositories shared without Kronael, ALSO add a short project AGENTS.md pointer.

Example pointer:

# AGENTS.md

Read `CLAUDE.md` first. Those are project conventions for every coding agent,
not Claude-specific behavior.

Global installed skills

Codex scans .agents/skills and ~/.agents/skills, not .claude/skills or ~/.codex/skills.

For global Kronael skills installed by this workflow, bridge with:

mkdir -p ~/.agents
ln -s ~/.claude/skills ~/.agents/skills

Run this automatically after a successful Codex install/update. It is fast:

• If ~/.agents/skills already symlinks to ~/.claude/skills, report "already bridged".
• If ~/.agents/skills is missing and ~/.claude/skills exists, create the symlink.
• If ~/.agents/skills is a directory, add individual symlinks for each installed Kronael skill where the destination name is missing.
• If ~/.agents/skills is a symlink elsewhere, ask whether to replace, leave it, or skip.
• If an individual destination already exists and is not the same symlink, leave it alone and report the conflict count.

NEVER copy the skill tree into ~/.codex/skills. Codex's user skill location is ~/.agents/skills; symlinking preserves one editable installed copy, including scripts and references.

Use the discovered source root to decide which installed skills are source-owned: every skills/*/ except skills/global/. Do not symlink installed-only overlays from ~/.claude/skills.

Protocol:

mkdir -p "$HOME/.agents"

if [ -L "$HOME/.agents/skills" ] &&
   [ "$(readlink -f "$HOME/.agents/skills")" = "$(readlink -f "$HOME/.claude/skills")" ]; then
  echo "already bridged"
elif [ ! -e "$HOME/.agents/skills" ]; then
  ln -s "$HOME/.claude/skills" "$HOME/.agents/skills"
elif [ -d "$HOME/.agents/skills" ]; then
  for d in "$SOURCE_ROOT"/skills/*/; do
    name="$(basename "$d")"
    [ "$name" = "global" ] && continue
    [ -e "$HOME/.claude/skills/$name" ] || continue
    [ -e "$HOME/.agents/skills/$name" ] && continue
    ln -s "$HOME/.claude/skills/$name" "$HOME/.agents/skills/$name"
  done
else
  echo "conflict: ~/.agents/skills exists but is not a directory or symlink"
fi

Codex hooks

Codex supports native lifecycle hooks from ~/.codex/hooks.json, ~/.codex/config.toml, project .codex/ config, and enabled plugins. Kronael uses ~/.codex/hooks.json as the user-level install target.

After the Claude hook scripts are copied, install Codex hook wiring:

mkdir -p "$HOME/.codex"
cp "$SOURCE_ROOT/codex-hooks.json" "$HOME/.codex/hooks.json"

This config calls ~/.claude/hooks/codex_hook.py, which normalizes Codex hook payloads and delegates to the installed Kronael hooks. The wrapper also rewrites Kronael nudge references from /skill to @skill and suppresses Claude-style context-only output for Codex PreCompact, where Codex only accepts block decisions. Do not point Codex directly at the Claude hook scripts unless the wrapper is removed intentionally.

Codex requires changed command hooks to be reviewed and trusted. After install, report that the user must open /hooks in a fresh Codex TUI session and trust the Kronael hooks. Use --dangerously-bypass-hook-trust only for automation or verification that already vets the source.

Project .claude/skills

For a project that stores Claude skills under .claude/skills, bridge with:

mkdir -p .agents
ln -s ../.claude/skills .agents/skills

Use this only when .claude/skills exists and .agents/skills does not. If .agents/skills already exists, ask whether to leave it alone, add individual symlinks, or skip the bridge.

Report

Report only:

• canonical install result from kronael/install/SKILL.md if install ran
• Codex bridge paths changed: ~/.codex/AGENTS.md, ~/.codex/config.toml, project AGENTS.md, ~/.agents/skills, .agents/skills, ~/.codex/hooks.json
• whether Codex can now see global guidance, installed skills, and hook wiring; tell the user to start a new thread, use /skills or @skill-name, and open /hooks once to trust changed hooks

NEVER duplicate the full installer report in the bridge. Link paths and say whether each bridge step was applied or skipped.