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