code-mux-plugin

English | 简体中文

Template-driven generator for bridge skills, commands, and staged memory packs across Claude, Codex, Qoder, and experimental hosts.

Package: @moonraing7/code-mux-plugin
License: MIT

Why This Exists

code-mux-plugin generates host-specific filesystem artifacts from shared adapter templates.

Milestone 1 is intentionally narrow:

• generate files only
• support local project install and global user install
• support a central registry and registry-backed update/repair flows
• keep verified hosts separate from experimental outputs
• avoid provider execution, auth setup, background jobs, and marketplace packaging
• allow package-manager-mediated self-update only for supported npm install contexts

This package does not run external AI providers. It writes the files you can inspect, version, and rerun safely.

Host Coverage

Verified hosts

| Host | Artifacts | Output style | | --- | --- | --- | | claude | skill, command | native host paths | | codex | skill | native host paths | | qoder | skill, command | native host paths |

Experimental staged outputs

| Host | Artifacts | Output style | | --- | --- | --- | | kimi | memory-pack | .code-mux/experimental/... | | gemini | skill | .code-mux/experimental/... | | antigravity | skill | .code-mux/experimental/... |

Bridge adapters currently shipped in Milestone 1:

• kimi
• gemini
• qoder
• antigravity

Install

Using CLI (Recommended)

Install the published package globally:

npm install --global @moonraing7/code-mux-plugin

Check the current host matrix:

code-mux list-platforms

Local development from this repo

bun run build
node bin/code-mux.js list-platforms

Quick Start

Go to your project and generate one verified Codex skill:

cd /path/to/project
code-mux init --ai codex --ada kimi

This writes:

/path/to/project/.codex/skills/mux-kimi/SKILL.md

Generate all verified outputs for all adapters into the current project:

cd /path/to/project
code-mux init --ai all

Generate a staged experimental output explicitly:

cd /path/to/project
code-mux init --ai kimi --artifact memory-pack --ada kimi --include-experimental

This writes:

/path/to/project/.code-mux/experimental/kimi/mux-kimi/AGENTS.md

Refresh previously registered installs with the latest generator output:

code-mux update

Install Modes

Local project install

Writes into the current working directory. The recommended flow is:

cd /path/to/project
code-mux init --ai codex --ada kimi

Examples:

• Claude skill: .claude/skills/mux-<adapter>/SKILL.md
• Codex skill: .codex/skills/mux-<adapter>/SKILL.md
• Qoder command: .qoder/commands/mux-<adapter>.md

Global install

Writes into the current user's home-scoped host roots:

code-mux init --ai codex --ada kimi --global

Examples:

• Claude skill: ~/.claude/skills/mux-<adapter>/SKILL.md
• Codex skill: ~/.codex/skills/mux-<adapter>/SKILL.md
• Qoder command: ~/.qoder/commands/mux-<adapter>.md

Update And Registry

code-mux keeps a central registry at ~/.code-mux/registry.json so later update runs can refresh historical installs without scanning the filesystem.

Supported Milestone 1 self-update contexts:

• global npm install invoked as code-mux
• project-local npm install invoked via node_modules/.bin/code-mux

Rejected in Milestone 1 with manual instructions:

• source-checkout runs such as node bin/code-mux.js
• transient runners such as npx and npm exec
• non-npm launchers such as bunx

When code-mux update finds a missing project path, it continues healthy refreshes first and then prints simple repair commands:

code-mux relink <entry-id> /new/path
code-mux forget <entry-id>

Command Notes

• --ai is the preferred host selector and --ada is the preferred adapter selector.
• --host and --adapter remain supported for compatibility.
• --target remains supported for compatibility, but the recommended local install flow is to run from the project root.
• update refreshes registry-tracked installs and only self-updates in the supported npm contexts above.
• --ai all includes verified hosts only.
• Experimental hosts require --include-experimental.
• --artifact defaults to all.
• --ada defaults to all.

Overwrite Policy

• managed files are overwritten on rerun
• unmanaged files fail by default
• --force is required to replace unmanaged files

Development

bun run build
bun run test
bun run smoke
bun run verify
bun run clean:test-artifacts
npm run pack:dry-run

Development flow notes:

• bun run test runs under an isolated sandbox HOME and isolated test temp root so automated tests cannot write into the maintainer ~/.code-mux/registry.json.
• bun run smoke runs the local/global/update smoke flow in the same kind of isolated sandbox and cleans it afterwards.
• bun run verify runs the full build + isolated test + isolated smoke + pack dry-run sequence.
• bun run clean:test-artifacts removes leaked test-shaped registry entries and their temp directories from the maintainer machine if an older manual run polluted ~/.code-mux/registry.json.

Release

The repository uses tag-driven release automation:

1. keep package.json version aligned with the release tag
2. push a matching tag such as v<semver>
3. GitHub Actions runs build, test, and npm pack --dry-run
4. npm publish runs through Trusted Publishing
5. the matching GitHub Release is created or updated

Workflow:

• release workflow: .github/workflows/release.yml
• npm package: @moonraing7/code-mux-plugin
• GitHub repo: moonraing7/code-mux-plugin

Reference Anchors

These projects informed structure and scope decisions:

• openai/codex-plugin-cc
• nextlevelbuilder/ui-ux-pro-max-skill
• thepushkarp/cc-gemini-plugin
• Z-M-Huang/claude-codex-gemini