> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codealive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Share the plugin with Codex CLI

> Reuse the Claude Code plugin's skill from Codex CLI and other skill-aware agents, with a launchd agent that follows every plugin update.

## Overview

The [CodeAlive Claude Code plugin](/integrations/plugin-claude-code) ships the
`codealive-context-engine` skill along with a subagent and authentication
hook. Claude Code installs it into a versioned cache directory. Other
skill-aware agents — Codex CLI, Gemini CLI, Cursor, Windsurf — look for skills
in their own user directories and don't read the Claude Code plugin cache.

This guide sets up a one-time bridge so those agents pick up the exact same
skill files the plugin installs, and keeps following new versions every time
you run `claude plugin update`.

<Info>
  You only need this if you want a single source of truth for the skill across
  multiple agents. If you use Codex (or another agent) in isolation, the simpler
  option is to run the universal installer:

  ```bash theme={null}
  npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine
  ```

  See the [Agent Skills & Plugins](/integrations/skills) page for details.
</Info>

## How it works

A symlink from `~/.codex/skills/codealive-context-engine` points into the
plugin's versioned cache at `~/.claude/plugins/cache/codealive-marketplace/codealive/<version>/skills/codealive-context-engine`.
Codex CLI loads the skill through the symlink.

Each `claude plugin update` writes a new versioned directory and leaves the old
one in place, so the symlink's target becomes stale. A `launchd` agent watches
the parent cache directory and re-runs a short shell script that rewrites the
symlink to the highest version currently on disk.

## Prerequisites

* macOS with the [Claude Code plugin installed](/integrations/plugin-claude-code)
* Codex CLI (or another skill-aware agent)
* The `codealive-skills` repository cloned locally, so you can run the bridge scripts:

  ```bash theme={null}
  git clone https://github.com/CodeAlive-AI/codealive-skills.git
  ```

## Install (macOS)

<Steps>
  <Step title="Run the installer">
    ```bash theme={null}
    cd codealive-skills/tools/plugin-bridge
    ./install-macos.sh
    ```

    The installer renders `com.codealive.plugin-bridge.plist`, writes it to
    `~/Library/LaunchAgents/`, bootstraps the agent, and creates the symlink
    once synchronously so it's ready immediately.
  </Step>

  <Step title="Verify the symlink">
    ```bash theme={null}
    ls -la ~/.codex/skills/codealive-context-engine
    ```

    The output should show a symlink pointing into
    `~/.claude/plugins/cache/codealive-marketplace/codealive/<version>/skills/codealive-context-engine`.
  </Step>

  <Step title="Confirm the launchd agent">
    ```bash theme={null}
    launchctl print "gui/$(id -u)/com.codealive.plugin-bridge" | head
    ```

    You should see `state = waiting` (the expected idle state for a `WatchPaths`
    agent) and the watched path listed.
  </Step>

  <Step title="Test with a plugin update">
    From any shell, run:

    ```bash theme={null}
    claude plugin update codealive@codealive-marketplace
    ```

    Then re-check the symlink — it should now point at the newer version.
    The bridge also writes a line per relink to `/tmp/codealive-plugin-bridge.log`.
  </Step>
</Steps>

## Targeting a different agent

The scripts default to Codex CLI. Every path is driven by an environment
variable, so you can point the bridge at any agent.

| Variable                   | Default                                                   |
| -------------------------- | --------------------------------------------------------- |
| `CODEALIVE_PLUGIN_CACHE`   | `~/.claude/plugins/cache/codealive-marketplace/codealive` |
| `CODEALIVE_PLUGIN_SUBPATH` | `skills/codealive-context-engine`                         |
| `CODEALIVE_AGENT_LINK`     | `~/.codex/skills/codealive-context-engine`                |

Example for Gemini CLI:

```bash theme={null}
CODEALIVE_AGENT_LINK=~/.gemini/skills/codealive-context-engine ./install-macos.sh
```

<Warning>
  `launchd` starts `update-symlink.sh` through `/bin/bash` and does not inherit
  your interactive shell environment. If you customise a variable, either edit
  the defaults inside `update-symlink.sh`, set them in `~/.zshenv` (which is
  read by non-login bash on macOS when sourced explicitly), or add an
  `EnvironmentVariables` dictionary to the plist before installing.
</Warning>

## Linux

A `systemd --user` path unit gives the equivalent behaviour. See the
[Linux section of the bridge README](https://github.com/CodeAlive-AI/codealive-skills/tree/main/tools/plugin-bridge#linux)
for ready-to-use unit files.

## Uninstall

```bash theme={null}
cd codealive-skills/tools/plugin-bridge
./uninstall-macos.sh
```

This removes the `launchd` agent. The existing symlink stays in place; delete
it manually if you want to remove it as well:

```bash theme={null}
rm ~/.codex/skills/codealive-context-engine
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Codex doesn't see the skill after install">
    Confirm the symlink resolves to a directory that contains `SKILL.md`:

    ```bash theme={null}
    ls -la "$(readlink ~/.codex/skills/codealive-context-engine)"
    ```

    If the link is dangling, check that the Claude Code plugin is installed
    (`claude plugin list`) and that
    `~/.claude/plugins/cache/codealive-marketplace/codealive/` contains at
    least one version directory.
  </Accordion>

  <Accordion title="Symlink didn't update after `claude plugin update`">
    Inspect the bridge log:

    ```bash theme={null}
    tail /tmp/codealive-plugin-bridge.log /tmp/codealive-plugin-bridge.err
    ```

    Re-run the updater manually to confirm the logic:

    ```bash theme={null}
    bash codealive-skills/tools/plugin-bridge/update-symlink.sh
    ```

    If the manual run relinks correctly but the `launchd` agent didn't fire,
    reload it:

    ```bash theme={null}
    launchctl bootout "gui/$(id -u)/com.codealive.plugin-bridge" || true
    launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.codealive.plugin-bridge.plist
    ```
  </Accordion>

  <Accordion title="launchctl bootstrap fails with 'Input/output error'">
    Another `launchd` job is already loaded under the same label. Boot it out
    first:

    ```bash theme={null}
    launchctl bootout "gui/$(id -u)/com.codealive.plugin-bridge"
    ./install-macos.sh
    ```
  </Accordion>

  <Accordion title="Old plugin versions pile up in the cache">
    `claude plugin update` doesn't delete prior versions. The bridge always
    picks the highest version by `sort -V`, so older directories don't affect
    behaviour. Remove them manually if you want to reclaim disk space:

    ```bash theme={null}
    ls ~/.claude/plugins/cache/codealive-marketplace/codealive
    # keep the latest, remove anything older
    ```
  </Accordion>
</AccordionGroup>

<Tip>
  For general integration issues, see the [Troubleshooting Guide](/troubleshooting).
</Tip>

## Related resources

<CardGroup cols={2}>
  <Card title="Claude Code Plugin" icon="puzzle-piece" href="/integrations/plugin-claude-code">
    Install the plugin this bridge depends on
  </Card>

  <Card title="Agent Skills & Plugins" icon="graduation-cap" href="/integrations/skills">
    Install the skill directly via the universal installer
  </Card>

  <Card title="Bridge source" icon="github" href="https://github.com/CodeAlive-AI/codealive-skills/tree/main/tools/plugin-bridge">
    Scripts, launchd template, and Linux unit files
  </Card>

  <Card title="Codex MCP setup" icon="plug" href="/integrations/mcp/codex">
    Direct tool access for Codex via MCP
  </Card>
</CardGroup>