CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build   # tsc + postbuild shebang wrapper → dist/
npm test        # build then run node test/*.test.ts

Run a single test file:

node --test test/cli.test.ts

No linter is configured. TypeScript strict mode is the primary safety net.

After build, install globally once with npm link. Then the CLI is available as:

apx <command>

Architecture

This repo is an "Oh My Zsh"-style collection of reusable agent powerups (skills, commands, MCP configs, hooks, workflows, templates) for Claude Code, Codex, and Gemini. The APX CLI is the tool users and agents use to browse, validate, check, and install those assets.

catalog.json — single source of truth

Every shipped asset is registered in catalog.json. The Zod schema in src/cli/utils/catalog.ts enforces structure: required fields (name, type, summary, path, compatible_with, maturity), optional fields (requires, targets, mcp, run). Duplicate names are rejected. All referenced paths must exist on disk. When adding a new skill or command, add its catalog entry and verify with apx validate catalog.

Allowed compatible_with values: claude-code, codex, gemini-cli, cursor, generic. Allowed maturity values: draft, beta, stable.

The targets field holds agent-specific path variants (e.g., .toml for Codex, .json for Claude Code). The requires field declares external dependencies that apx check verifies.

CLI command routing (src/cli/apx.ts)

runCli(argv, io) is the entry point. It finds catalog.json by walking up from cwd, constructs a CatalogService, then dispatches on argv[0] to command modules under src/cli/commands/. Each command exports a run*Command function and returns ExecutionResult<T>. The --json flag switches output to structured JSON for agent consumption.

Asset directories

• skills/ — each subdirectory has a SKILL.md with YAML frontmatter (name, description) and pure Markdown workflow prose; use headings instead of XML-like top-level section tags
• commands/ — agent-specific subdirs (codex/, claude-code/, generic/); each .md is a slash-command definition
• hooks/ — recipe .md files under safety/, quality/, productivity/; review-before-use, not auto-applied
• mcp/ — MCP server configs in agent-native format (.json for Claude Code, .toml for Codex)
• agents-md/ — project-type starter templates (typescript-app, python-library, etc.) for AGENTS.md
• workflows/ — multi-step scenario guides (agent-relay, feature-iteration)

Setup and install

apx setup <codex|claude-code|gemini> copies templates and appends marked blocks to the agent's config file (AGENTS.md / CLAUDE.md / GEMINI.md). It uses START_MARKER/END_MARKER guards to prevent duplicate insertions and backs up files before modifying. Supports --dry-run.

apx install <asset-name> --target <agent> copies the asset to .agent-powerups/installed/<name> (or --dest). Agent-specific variants are resolved via the targets field in catalog.json.

Relay system (src/cli/commands/relay.ts)

Persistent secondary-agent daemon over TCP (127.0.0.1:randomPort). Three providers:

• gemini — spawns gemini --acp once; uses ACP JSON-RPC; session context persists across turns
• claude — spawns claude -p <prompt> per relay ask; no cross-turn memory
• codex — spawns codex --full-auto <prompt> per relay ask; no cross-turn memory

buildRelayBackend() returns a RelayBackend interface (prompt() / close()). GeminiAcpClient is wrapped to satisfy it; SubprocessClient implements it for Claude/Codex. State is stored in .apx/relay/<session>/relay.json. Artifacts written per turn to the same directory.

Validation scripts (Python)

scripts/validate-catalog.py, validate-skills.py, and check-requirements.py are standalone Python scripts for CI-style checks. They do not depend on the TypeScript build.

Test pattern

Tests in test/ use Node's built-in node:test + node:assert/strict. All tests call runCli(argv, { cwd, stdout, stderr }) and assert on the returned exit code and captured output. Tests run against the built dist/; rebuild before running tests after source changes.