Related Pages

Related topics: Installation Guide, apx CLI Reference, Skills System

Project Overview

Agent Powerups is an open-source CLI toolkit and plugin ecosystem designed to extend the capabilities of AI coding agents. Inspired by the "Oh My Zsh" philosophy of shared, reusable configurations, it provides a curated collection of skills, commands, MCP server configurations, hooks, and workflow templates that work across multiple agent platforms including Claude Code, OpenAI Codex, and Google Gemini CLI.

Project Purpose

The core purpose of Agent Powerups is to solve the fragmentation problem in AI-assisted development. Instead of each developer or team maintaining their own custom prompts, scripts, and agent configurations in isolation, Agent Powerups provides a community-driven library of reusable agent enhancements that can be discovered, validated, and installed through a unified CLI interface.

Key objectives:

• Provide portable, validated skills that encode best-practice workflows (debugging, code review, planning)
• Enable explicit, auditable installation of agent extensions rather than opaque粘贴
• Support multi-agent compatibility with a single codebase
• Maintain safety boundaries around secrets, shell access, and MCP server enablement
• Offer graduated onboarding through user-intent profiles and dry-run validation

Architecture Overview

Agent Powerups follows a layered architecture with three primary concerns:

1. Catalog Layer: JSON manifests (catalog.json, plugin-bundles.json, profiles.json) that index all available assets
2. CLI Layer: The apx command-line interface that provides discovery, validation, and installation
3. Asset Layer: The actual skill files, command packs, MCP configs, hooks, and workflow templates

graph TD
    A[User / Agent] -->|apx commands| B[CLI Layer: apx]
    B -->|read| C[Catalog Layer: JSON manifests]
    B -->|validate| D[Source Assets]
    C -->|index| D
    D -->|skills| E[skills/]
    D -->|commands| F[commands/]
    D -->|mcp configs| G[mcp/]
    D -->|hooks| H[hooks/]
    D -->|workflows| I[workflows/]
    D -->|agents-md| J[agents-md/]
    D -->|plugins| K[plugins/]
    B -->|install to| L[Target Agent Root]
    L -->|codex| M[Codex agents]
    L -->|claude-code| N[Claude Code agents]
    L -->|gemini| O[Gemini CLI agents]

CLI Interface (apx)

The apx CLI is the primary user interface for Agent Powerups. It is implemented in TypeScript and published as the agent-powerups npm package.

Installation

npm install -g agent-powerups

The CLI requires Node.js >= 20 and is published at npm:agent-powerups.

Core Commands

Sources: package.json:16

Asset Catalog

Skills

Skills are Markdown files that encode reusable agent workflows. Each skill follows a standardized structure with frontmatter metadata.

Current shipped skills include:

Sources: README.md:89-111

Plugin Bundles

Plugin bundles are organized collections of skills, commands, and agents tailored for specific domains. They support multi-agent formats including Claude Code manifests and Codex plugin manifests.

graph TD
    A[Plugin Bundle] --> B[skills/]
    A --> C[commands/]
    A --> D[agents/]
    A --> E[.claude-plugin/]
    A --> F[.codex-plugin/]
    B --> G[SKILL.md files]
    C --> H[command-name.md files]
    D --> I[agent-name.md files]
    E --> J[plugin.json - Claude Code Manifest]
    F --> K[plugin.json - Codex Manifest]

User-Intent Profiles

Profiles are curated collections of skills and plugins for specific use cases. They can be inspected with apx profiles list and applied during setup.

Sources: README.md:120-130

Setup Modes

Agent Powerups supports three installation modes that control the scope of what gets installed:

The setup process:

1. Creates an agent-powerups/ directory under the agent root
2. Copies relevant asset directories based on mode
3. Optionally appends agent-powerups instructions to AGENTS.md or CLAUDE.md
4. Backs up existing instruction files before modification

Sources: src/cli/commands/setup.ts:14-45

flowchart LR
    A[apx setup codex] --> B{Mode?}
    B -->|minimal| C[Bootstrap instructions only]
    B -->|recommended| D[Skills + plugins + instructions]
    B -->|full| E[All assets + docs]
    C --> F[agent-powerups/]
    D --> F
    E --> F
    F --> G{AGENTS.md exists?}
    G -->|Yes| H[Append marked block<br/>Backup first]
    G -->|No| I[Create instructions file]
    H --> J[Setup complete]
    I --> J

Supported Agents

Agent Powerups maintains explicit compatibility with three primary agent platforms:

The CLI uses --target flag to specify the destination:

apx plugins install dev-vitals --target codex --dry-run
apx plugins install dev-vitals --target claude-code --dry-run

Sources: src/cli/apx.ts:32-45

MCP Integration

Agent Powerups ships with a local-first GitHub MCP configuration that includes:

• apx mcp check - Validate MCP server configuration
• apx mcp smoke - Run smoke tests against MCP server
• apx mcp install - Explicit installation workflow

The MCP integration follows a security-first model where MCP servers require explicit user approval before enablement.

Sources: README.md:51-54

Safety Model

Agent Powerups implements several safety mechanisms:

1. Dry-run by default: Most install commands support --dry-run to preview changes
2. Explicit approval: Interactive prompts require confirmation unless --yes is passed
3. Backup before modify: Setup creates backups of existing instruction files
4. Requirement validation: apx check verifies prerequisites before installation
5. Security audit: apx security-audit scans for dangerous patterns in scripts

Dangerous patterns flagged by the security audit:

Sources: src/cli/commands/security-audit.ts:18-28

Validation and Health Checks

Doctor Command

The apx doctor command performs comprehensive health checks:

Sources: src/cli/commands/doctor.ts:35-52

Requirement Checking

The apx check command validates asset requirements:

• Missing requirements are flagged with MISSING status
• Automatic installation is attempted if --install-missing is provided
• Human approval is requested via interactive prompt unless --yes is passed

flowchart TD
    A[apx check <asset>] --> B[Check requirements]
    B --> C{All satisfied?}
    C -->|Yes| D[status=OK]
    C -->|No| E{installMissing?}
    E -->|Yes| F[installMissingRequirements]
    E -->|No| G[status=MISSING]
    F --> H{Interactive?}
    H -->|Yes| I[confirmInstall prompt]
    H -->|No --yes| J[Auto-install]
    I -->|Approved| F
    I -->|Declined| K[warnings.push]

Sources: src/cli/commands/check.ts:28-45

Directory Structure

agent-powerups/
├── skills/                    # Root-level reusable skills
├── agents-md/                 # AGENTS.md templates
├── commands/                  # Command packs
│   └── generic/              # Agent-agnostic commands
├── hooks/                     # Hook examples
├── workflows/                 # Workflow templates
├── mcp/                       # MCP configurations
│   └── generic/              # Agent-agnostic MCP configs
├── plugins/                   # Plugin bundle source
├── docs/                      # Documentation
├── scripts/                   # Validation scripts
├── .codex-plugin/            # Codex plugin manifest
├── .claude-plugin/           # Claude Code plugin manifest
├── apx.ts                     # CLI entry point
├── package.json               # Package manifest
├── catalog.json               # Asset catalog index
├── plugin-bundles.json        # Plugin bundle index
└── profiles.json              # User-intent profiles

Version and Release

Sources: package.json:1-15

Related Pages

Related topics: Project Overview, apx CLI Reference, Claude Code Integration, Codex Integration, Gemini Integration

Installation Guide

Agent Powerups provides multiple installation pathways to accommodate different workflows—from manual CLI installation for humans to agent-curated automated setup. This guide covers all supported methods, configuration options, and per-agent integration patterns.

Overview

Agent Powerups is an Oh My Zsh-style collection of reusable skills, slash commands, MCP configs, hooks, AGENTS.md templates, and workflows for coding agents. The installation system is designed with safety boundaries around external tools, secrets, shell profiles, and MCP enablement. Sources: README.md

Installation Methods

The system supports four primary installation approaches:

Sources: README.md:1-80

Prerequisites

System Requirements

• Node.js: Required for the apx CLI tool
• npm or yarn: For installing the CLI package
• Python 3.x: For validation scripts (validate-skills.py, validate-catalog.py, check-requirements.py)
• Git: For cloning the repository (optional, if using npm package)

Verification Commands

Before installation, verify your environment:

apx doctor
apx list

The doctor command checks the CLI installation and dependencies. The list command displays all available assets. Sources: examples/minimal/README.md

CLI Installation

Installing the Package

Install the agent-powerups package globally:

npm install -g agent-powerups

Or use the development version from the repository:

git clone https://github.com/yeaight7/agent-powerups.git
cd agent-powerups
npm install
npm run build
npm link

Sources: examples/minimal/README.md

Global Commands Available

After installation, the apx command provides access to all functionality:

Sources: src/cli/apx.ts:1-100

Native Install (Manual)

The apx install command performs a direct native installation, copying skills and plugin bundles into the selected agent root directory.

Basic Syntax

apx install <codex|claude|claude-code|gemini> [--verbose]
apx install <codex|claude|claude-code|gemini> --full [--verbose]

Default Install Behavior

Human output shows counts by default. Use --verbose for per-file paths.

Full Install

The --full flag additionally:

• Stages support assets under agent-powerups/
• Updates existing global instructions with a backup

apx install codex --full --verbose

Dry Run

Always preview changes before applying:

apx install codex --dry-run
apx install claude --dry-run
apx install gemini --dry-run

Per-Asset Installation

Install specific plugin bundles to specific targets:

apx install <asset-name> --target <codex|claude-code|generic> [--dry-run] [--dest <path>]

Example:

apx install dev-vitals --target codex --dry-run
apx install dev-vitals --target codex

Sources: README.md:1-150, src/cli/apx.ts:100-200

Agent-Curated Setup

The apx setup command provides an agent-curated setup path with different configuration modes.

Setup Syntax

apx setup <codex|claude-code|gemini> [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root <path>] [--instructions-file <path>] [--json]

Setup Modes

#### Minimal Mode (Bootstrap)

Minimal mode creates a bootstrap setup with essential references:

apx setup codex --mode minimal --yes

Output structure:

START_MARKER
## Agent Powerups
Agent Powerups assets are installed at `<normalized-root>`.
- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.
- Use `apx` commands to discover, inspect, validate, and extend setup.
- MCP servers require explicit user approval.
- External tools require user approval before install.
This is a minimal (bootstrap) setup. To get a recommended agent environment:
  apx setup ${profile.agent} --mode recommended --yes
END_MARKER

Sources: src/cli/commands/setup.ts:1-50

#### Recommended Mode

Recommended mode provides the main agent environment with skills, plugin bundles, and comprehensive instructions:

apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes
apx setup gemini --mode recommended --yes

This mode includes:

• All root skills from skills/
• Recommended plugin bundles based on agent profile
• Command templates and hook examples
• AGENTS.md templates
• MCP configuration guidance

#### Full Mode

Full mode performs a broad staging with maximum asset coverage:

apx setup codex --mode full --yes

Installation Workflow Diagram

graph TD
    A[Start: apx install or apx setup] --> B{Dry Run?}
    B -->|Yes| C[Preview Changes Only]
    B -->|No| D{Interactive?}
    D -->|Yes| E[Confirm Changes]
    D -->|No --yes| F[Auto-Approve]
    C --> G[Display File Operations]
    E -->|Approved| H[Execute Installation]
    E -->|Declined| I[Abort]
    F --> H
    H --> J[Copy Skills to Agent Root]
    H --> K[Copy Plugins to Agent Root]
    H --> L[Update Instructions if --full]
    J --> M[Verify with apx check]
    K --> M
    L --> M
    M --> N[Installation Complete]

Per-Agent Setup Guides

Codex Setup

# Dry run first
apx setup codex --dry-run

# Safe apply with explicit root
apx setup codex --agent-root .agent-powerups-demo\codex --yes

# Inspect after setup
apx info using-powerups
apx check using-powerups

Instruction File Behavior:

• If <codex-root>\AGENTS.md exists, setup appends a marked agent-powerups block after creating a backup
• If it does not exist, setup writes agent-powerups\instructions\agent-powerups.md and reports manual steps

Sources: examples/codex/README.md

Claude Code Setup

# Dry run first
apx setup claude-code --dry-run

# Safe apply with explicit root
apx setup claude-code --agent-root .agent-powerups-demo\claude --yes

# Inspect after setup
apx commands print ship-check --target claude-code
apx info using-powerups

Instruction File Behavior:

• If <claude-root>\CLAUDE.md exists, setup appends a marked agent-powerups block after creating a backup
• If it does not exist, setup writes agent-powerups\instructions\agent-powerups.md and reports manual steps

Sources: examples/claude-code/README.md

Gemini Setup

apx setup gemini --dry-run
apx setup gemini --mode recommended --yes

Gemini plugin bundles include gemini-extension.json and GEMINI.md.

Agent-Managed Setup

For agent-curated installation, provide the agent access to this repository and ask it to run:

apx list
apx profiles list
apx setup <codex|claude-code|gemini> --mode recommended --yes

The agent will:

1. Inspect available skills and plugins
2. Propose a configuration plan
3. Apply the setup based on the selected mode

Plugin Bundle Installation

Discovering Plugins

apx plugins list
apx plugins info dev-vitals

Validating Plugin Bundles

Before installation, validate bundle structure:

apx plugins validate --all

Installing Plugin Bundles

apx plugins install dev-vitals --target codex --dry-run
apx plugins install dev-vitals --target codex

Plugin Bundle Structure

Each plugin follows the standard agent plugin layout:

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Claude Code Manifest
├── .codex-plugin/
│   └── plugin.json      # Codex Manifest
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── agents/
│   └── <agent-name>.md
└── commands/
    └── <command-name>.md

Sources: plugins/README.md

MCP Configuration Installation

Available MCP Commands

Installing GitHub MCP

apx mcp check github-local --target generic
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run
apx mcp install github-local --target codex

Post-Installation Validation

Run Validation Scripts

python scripts/validate-skills.py
python scripts/validate-catalog.py
python scripts/check-requirements.py

Verify Setup

apx doctor
apx check using-powerups
apx hooks run no-secrets-preflight --all

Minimal Demo Walkthrough

For inspecting Agent Powerups without mutating an agent's global config:

# 1. Install and link the CLI
npm install
npm run build
npm link

# 2. Verify installation
apx doctor
apx list

# 3. Dry run setup to disposable directory
apx setup codex --agent-root .agent-powerups-demo\codex --dry-run

# 4. Apply to disposable local root
apx setup codex --agent-root .agent-powerups-demo\codex --yes

# 5. Review created structure
.agent-powerups-demo/codex/agent-powerups/skills/
.agent-powerups-demo/codex/agent-powerups/commands/
.agent-powerups-demo/codex/agent-powerups/instructions/agent-powerups.md

# 6. Rollback when done
Remove-Item .agent-powerups-demo -Recurse -Force

Sources: examples/minimal/README.md

Safety Considerations

The installation system implements safety boundaries around:

Before loading any asset, review it:

• Skills can instruct an agent to read local files or run commands
• Hooks can execute code when supported by the host agent
• MCP configs can expand tool access
• Install commands can modify the local environment

See SECURITY.md and docs/security-model.md for full security details.

Command Reference

Install Command Options

Setup Command Options

Troubleshooting

CLI Not Found

npm link
# Or reinstall globally
npm install -g agent-powerups

Dry Run vs Apply

Always prefer dry-run first:

apx install codex --dry-run
apx setup codex --dry-run
apx plugins install dev-vitals --target codex --dry-run

Rollback

If using explicit --agent-root with a disposable directory, simply delete the directory:

Remove-Item .agent-powerups-demo -Recurse -Force

Agent Instructions Not Updated

Check if the agent's instruction file exists:

• Codex: <codex-root>\AGENTS.md
• Claude Code: <claude-root>\CLAUDE.md

If the file doesn't exist, setup writes to agent-powerups\instructions\agent-powerups.md and reports manual integration steps.

Related Pages

Related topics: Project Overview, Installation Guide, Plugin Bundles

apx CLI Reference

The apx (Agent Powerups eXecutor) is the primary command-line interface for managing Agent Powerups assets, skills, plugins, and configurations for coding agents. It provides a unified entry point for installing, validating, and orchestrating agent powerups across multiple agent platforms including Codex, Claude Code, and Gemini.

Overview

The apx CLI serves as a safe local CLI with runnable local checks, enabling users to:

• Discover and install reusable skills and plugin bundles
• Configure agent-specific instruction files
• Validate tool requirements and dependencies
• Manage MCP (Model Context Protocol) server configurations
• Execute security audits and preflight checks
• Handle persistent relay sessions for multi-agent workflows

Sources: src/cli/apx.ts:1-50

Command Hierarchy

The apx CLI organizes commands into a hierarchical structure with multiple subcommand categories.

graph TD
    A[apx] --> B[Install Commands]
    A --> C[Setup Commands]
    A --> D[Information Commands]
    A --> E[MCP Commands]
    A --> F[Plugin Commands]
    A --> G[Profile Commands]
    A --> H[Validation Commands]
    A --> I[Security Commands]
    A --> J[Relay Commands]
    A --> K[Phase Commands]
    
    B --> B1[install]
    B --> B2[setup]
    
    C --> C1[setup codex]
    C --> C2[setup claude-code]
    C --> C3[setup gemini]
    
    D --> D1[list]
    D --> D2[info]
    D --> D3[doctor]
    D --> D4[check]
    
    E --> E1[mcp list]
    E --> E2[mcp print]
    E --> E3[mcp check]
    E --> E4[mcp smoke]
    E --> E5[mcp install]
    E --> E6[mcp write]
    
    F --> F1[plugins list]
    F --> F2[plugins info]
    F --> F3[plugins validate]
    F --> F4[plugins install]
    
    G --> G1[profiles list]
    G --> G2[profiles info]
    G --> G3[profiles plan]
    G --> G4[profiles install]

Installation Commands

`apx install`

Installs assets, skills, or plugins to specified agent targets.

apx install <codex|claude|claude-code|gemini> [--full] [--dry-run] [--agent-root <path>] [--instructions-file <path>] [--force] [--verbose] [--json]
apx install <asset-name> --target <codex|claude-code|gemini|generic> [--dry-run] [--dest <path>]

Default Installation Paths:

Sources: src/cli/apx.ts:80-100

Native Install Behavior

The default manual install copies:

• Root skills/ → <agent-root>/skills/
• Codex/Claude plugin bundles → <agent-root>/plugins/
• Gemini plugin bundles → <agent-root>/extensions/

The --full flag additionally:

• Stages support assets under agent-powerups/
• Updates existing global instructions with a backup

Setup Commands

`apx setup`

Configures agent environments with curated skill and plugin sets using agent-curated setup paths.

apx setup <codex|claude-code|gemini> [--mode minimal|recommended|full] [--dry-run|--yes] [--agent-root <path>] [--instructions-file <path>] [--json]

Setup Modes

Instruction File Behavior

• If <agent-root>/AGENTS.md (Codex) or <agent-root>/CLAUDE.md (Claude Code) exists, setup appends a marked agent-powerups block after creating a backup.
• If the file does not exist, setup writes agent-powerups/instructions/agent-powerups.md and reports manual steps.

Sources: src/cli/commands/setup.ts:1-60

Information Commands

`apx doctor`

Runs comprehensive diagnostics on the apx installation.

apx doctor [--full] [--json]

`apx list`

Lists all available assets, skills, and plugins in the catalog.

apx list [--json]

`apx info`

Displays detailed information about a specific asset.

apx info <asset-name> [--json]

`apx check`

Checks dependency requirements for assets without installing.

apx check <asset-name> [--install-missing] [--dry-run]

Sources: src/cli/commands/list.ts:1-50

MCP Commands

The MCP (Model Context Protocol) commands manage MCP server configurations for agent integrations.

graph LR
    A[mcp list] --> B[Discover configs]
    C[mcp check] --> D[Validate syntax]
    E[mcp smoke] --> F[Test connectivity]
    G[mcp install] --> H[Deploy to target]

`apx mcp list`

Lists all available MCP configurations.

apx mcp list [--json]

`apx mcp print`

Prints MCP configuration content for review.

apx mcp print <config-name> --target <codex|claude-code|gemini|generic> [--json]

`apx mcp check`

Validates MCP configuration syntax and structure.

apx mcp check <config-name> --target <codex|claude-code|gemini|generic> [--json]

`apx mcp smoke`

Tests MCP server connectivity and basic functionality.

apx mcp smoke <config-name> [--json]

`apx mcp install`

Installs MCP configuration to the specified agent target.

apx mcp install <config-name> --target <codex|claude-code|generic> [--dry-run|--yes] [--agent-root <path>] [--dest <path>] [--force] [--json]

`apx mcp write`

Writes MCP configuration to a specified location.

apx mcp write <config-name> --target <codex|claude-code|gemini|generic> --dest <path> [--force] [--json]

Sources: src/cli/commands/mcp.ts:1-100

Plugin Commands

Plugin commands manage plugin bundles with validation, inspection, and installation capabilities.

graph TD
    A[plugins list] --> B[Discover plugins]
    A --> C[plugins info]
    C --> D[plugins validate]
    D --> E{Valid?}
    E -->|Yes| F[plugins install]
    E -->|No| G[Fix errors]
    F --> H[Deploy to target]

`apx plugins list`

Lists all available plugin bundles.

apx plugins list [--json]

`apx plugins info`

Displays detailed information about a specific plugin.

apx plugins info <plugin-name> [--json]

`apx plugins validate`

Validates plugin bundle structure and metadata.

apx plugins validate <plugin-name> [--json]
apx plugins validate --all [--json]

`apx plugins install`

Installs a plugin bundle to the specified target.

apx plugins install <plugin-name> --target <codex|claude-code|generic> [--dest <path>] [--dry-run|--yes] [--force] [--json]

Sources: src/cli/commands/plugins.ts:1-100

Profile Commands

Profiles are curated skill and plugin sets designed for specific use cases or security requirements.

`apx profiles list`

Lists all available user-intent profiles.

apx profiles list [--json]

`apx profiles info`

Displays detailed information about a specific profile.

apx profiles info <profile-name> [--json]

`apx profiles plan`

Generates an installation plan for a profile targeting a specific agent.

apx profiles plan <profile-name> --target <codex|claude-code|generic> [--json]

`apx profiles install`

Installs a complete profile to the specified target.

apx profiles install <profile-name> --target <codex|claude-code|generic> [--dry-run|--yes] [--dest <path>] [--force] [--json]

Sources: src/cli/commands/profiles.ts:1-80

Validation Commands

`apx validate`

Validates skills, catalog entries, and requirements.

apx validate [--json]
apx validate skill <skill-name> [--json]
apx validate catalog [--json]

`apx ship-check`

Runs pre-deployment checks to validate project readiness.

apx ship-check [--full] [--json]

`apx no-secrets-preflight`

Detects potential secret leaks in files before commit.

apx no-secrets-preflight [--path <path> | --all] [--json]

Sources: src/cli/commands/validate.ts:1-60

Security Commands

`apx security-audit`

Performs security analysis on project files.

apx security-audit --path <path> [--json]
apx security-audit --all [--json]

Security Checks

Sources: src/cli/commands/security-audit.ts:1-50

Relay Commands

Persistent relay sessions maintain context across multiple turns for multi-agent delegation.

`apx relay init`

Initializes a new persistent relay session.

apx relay init <session-name>

`apx relay start`

Starts a relay session with a specified provider.

apx relay start <session-name> --provider <gemini|claude|codex> [--json]

`apx relay ask`

Sends a query to an active relay session.

apx relay ask <session-name> "<query>" [--json]

`apx relay status`

Checks the status of a relay session.

apx relay status <session-name>

`apx relay stop`

Stops an active relay session.

apx relay stop <session-name>

Agent Advisor Commands

`apx ask-codex`

Queries Codex for advice or analysis.

apx ask-codex "<query>" [--json]

`apx ask-claude`

Queries Claude for advice or analysis.

apx ask-claude "<query>" [--json]

`apx ask-gemini`

Queries Gemini for advice or analysis.

apx ask-gemini "<query>" [--json]

Agent Targets

All installation and setup commands support the following target agents:

Global Flags

Exit Codes

Configuration Files

The CLI reads configuration from the following locations:

• Package-level package.json for version detection
• Agent-specific root directories for target configuration
• skills/, plugins/, mcp/, commands/, hooks/, workflows/ directories for asset discovery

Sources: src/cli/apx.ts:200-280

Quick Reference

# Setup and installation
apx install codex --dry-run
apx install codex --yes
apx setup codex --mode recommended --yes

# Discovery and inspection
apx doctor
apx list
apx info markitdown-file-intake
apx check markitdown-file-intake

# Plugin management
apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target codex --dry-run

# MCP management
apx mcp list
apx mcp check github-local --target codex
apx mcp smoke github-local --json
apx mcp install github-local --target codex --dry-run

# Profile management
apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex

# Security and validation
apx ship-check --full
apx no-secrets-preflight --all
apx security-audit --path .

Related Pages

Related topics: Project Overview, Plugin Bundles

Skills System

Overview

The Skills System is a core component of Agent Powerups, providing a collection of reusable, text-based agent workflows designed to standardize and accelerate common development tasks. Inspired by the Oh My Zsh plugin model, skills serve as modular instruction sets that coding agents can invoke to perform structured, repeatable workflows.

Skills in this system are agent-agnostic — they are designed as generic text-based instructions that can be understood and executed by various coding agent platforms including Codex, Claude Code, and Gemini.

Sources: README.md:22-24

Core Architecture

Skill Structure

Each skill follows a standardized file structure:

skills/
└── <skill-name>/
    ├── SKILL.md              # Main skill definition
    └── support-files/        # Optional referenced assets

The primary SKILL.md file contains:

• Frontmatter metadata (YAML): name, description, version, tags, compatibility
• Core workflow content: Structured instructions for the agent
• Support file references: Paths to optional helper resources

Sources: docs/catalog-schema.md

Skill Lifecycle

graph TD
    A[Create SKILL.md] --> B[Validate Frontmatter]
    B --> C[Check Required Fields]
    C --> D{Valid?}
    D -->|Yes| E[Publish to Catalog]
    D -->|No| F[Fix Issues]
    F --> B
    E --> G[apx list / apx info]
    G --> H[Agent Invocation]
    H --> I[Execute Workflow]
    I --> J[Report Results]

Skill Categories

The repository ships 21 core skills organized into functional categories:

Sources: README.md:103-130

Skill Frontmatter Schema

Every skill must include valid YAML frontmatter in its SKILL.md file:

Related Pages

Related topics: Skills System, apx CLI Reference

Plugin Bundles

Overview

Plugin Bundles are the core packaging mechanism for distributing collections of reusable agent assets in the Agent Powerups ecosystem. Each bundle packages together related skills, agents, commands, templates, hooks, workflows, and MCP configurations into a single installable unit that can be validated, inspected, and deployed to coding agent environments.

The bundle system follows an Oh My Zsh-inspired philosophy: provide curated, community-verified collections of assets that extend agent capabilities without requiring manual configuration. Plugin bundles serve as the primary distribution vehicle for Agent Powerups content, enabling both automated installation via the apx CLI and manual inspection before deployment.

Sources: README.md:1-10

Architecture

Bundle Structure

Each plugin bundle follows a standardized directory layout aligned with coding agent plugin conventions. The structure ensures compatibility across multiple agent platforms while maintaining platform-specific manifest files.

<plugin-name>/
├── .claude-plugin/
│   └── plugin.json      # Claude Code/Claude manifest
├── .codex-plugin/
│   └── plugin.json      # Codex manifest
├── skills/
│   └── <skill-name>/
│       └── SKILL.md
├── agents/
│   └── <agent-name>.md
├── commands/
│   └── <command-name>.md
├── templates/           (optional)
│   └── <template-name>.md
├── hooks/               (optional)
│   └── <hook-name>.ts
├── workflows/           (optional)
│   └── <workflow-name>.yml
└── mcp/                 (optional)
    └── <mcp-config>.json

Sources: plugins/README.md:18-36

Manifest Files

The plugin manifest files define bundle metadata, dependencies, and platform-specific configurations. These manifests enable the apx CLI to validate, install, and manage plugin bundles across different agent environments.

Claude Plugin Manifest (.claude-plugin/plugin.json)

Defines the plugin for Claude Code and Claude agent platforms, including skills, agents, commands, and hooks.

Codex Plugin Manifest (.codex-plugin/plugin.json)

Provides equivalent metadata for OpenAI Codex and related Codex-based agents.

Both manifests share a common schema but may contain platform-specific instructions or configurations.

Sources: plugins/README.md:20-25

Bundle Inventory

Maturity Levels

Plugin bundles are classified into three maturity levels indicating their stability and readiness for production use.

Sources: README.md:95-105

Stable Bundles

These bundles have undergone extensive testing and are recommended for production use:

Beta Bundles

Active development bundles with functional but evolving content:

Sources: README.md:95-105

Experimental Bundles

Early-stage bundles exploring new functionality:

Bundle Schema

The plugin-bundles.json file serves as the central registry for all plugin bundles. Each bundle entry contains comprehensive metadata following a defined JSON schema.

{
  "name": "bundle-name",
  "description": "Human-readable bundle description",
  "maturity": "stable|beta|experimental",
  "version": "1.0.0",
  "skills": [
    { "name": "skill-name", "path": "skills/skill-name" }
  ],
  "agents": [
    { "name": "agent-name", "path": "agents/agent-name.md" }
  ],
  "commands": [
    { "name": "command-name", "path": "commands/command-name.md" }
  ],
  "templates": [
    { "name": "template-name", "path": "templates/template-name.md" }
  ],
  "hooks": [
    { "name": "hook-name", "path": "hooks/hook-name.ts" }
  ],
  "workflows": [
    { "name": "workflow-name", "path": "workflows/workflow-name.yml" }
  ]
}

Sources: docs/plugin-bundles-schema.json

CLI Commands for Plugin Management

The apx CLI provides comprehensive commands for discovering, inspecting, validating, and installing plugin bundles.

Discovery Commands

apx plugins list                    # List all available bundles
apx plugins info <name>             # Inspect a specific bundle
apx plugins validate --all          # Verify all bundle structures

Installation Commands

apx plugins install <name> --target <codex|claude-code|generic> --dry-run
apx install <codex|claude|gemini>   # Full manual install

Sources: README.md:85-92

Validation Workflow

graph TD
    A[apx plugins validate] --> B{Plugin exists?}
    B -->|No| C[Return error: plugin not found]
    B -->|Yes| D{Manifest files exist?}
    D -->|Missing| E[Return error: missing manifest]
    D -->|Present| F{Schema valid?}
    F -->|Invalid| G[Return validation errors]
    F -->|Valid| H[Return success]

Sources: src/cli/utils/plugins.ts:40-60

Marketplace Integration

Claude Code Marketplace

Plugin bundles can be published to the Claude Code marketplace via the .claude-plugin/marketplace.json file. This manifest defines marketplace metadata including categories, keywords, screenshots, and pricing information.

Codex Marketplace

Similarly, .codex-plugin/marketplace.json provides marketplace configuration for Codex-based agents, ensuring discoverability across the agent platform ecosystem.

Sources: .claude-plugin/marketplace.json, .codex-plugin/marketplace.json

Installation Process

Dry-Run Validation

Before installation, always perform a dry-run to preview changes:

apx plugins install <bundle-name> --target codex --dry-run

This command displays the planned file operations without modifying the filesystem, allowing review of bundle contents before committing changes.

Sources: README.md:85-88

Full Installation

For actual installation, the apx setup command stages Agent Powerups assets, including plugin bundles:

apx setup codex --mode recommended --yes
apx setup claude-code --mode recommended --yes

The installation process:

1. Creates the plugin directory structure in the agent root
2. Copies bundle files to the appropriate locations
3. Registers skills, agents, and commands with the agent
4. Updates configuration files with appropriate references

Sources: src/cli/commands/setup.ts:1-50

Safety Considerations

Plugin bundles may contain assets that modify agent behavior:

• Skills can instruct agents to read files or execute commands
• Hooks can execute code when supported by the host agent
• MCP configs can expand tool access capabilities
• Install commands can modify the local environment

Always review bundle contents before installation. The CLI provides validation commands to inspect bundle structure and content without installation.

⚠️ Warning: Review assets before loading them into a trusted agent environment. Secrets should never be pasted into agent context unless strictly necessary.

Sources: README.md:110-120

Plugin Bundle Development

Creating a New Bundle

1. Create the bundle directory structure following the standard layout
2. Add required manifest files (.claude-plugin/plugin.json, .codex-plugin/plugin.json)
3. Include at least one skill, agent, or command
4. Register the bundle in plugin-bundles.json
5. Run apx plugins validate to verify structure

Bundle Validation

The validation system checks:

• Presence of required manifest files
• Schema compliance of all JSON configurations
• Existence of referenced skill, agent, and command files
• File size limits for security scanning

apx plugin validate <plugin-path>
apx plugins validate --all

Sources: src/cli/utils/plugins.ts:40-70

Related Documentation

• Catalog Schema - Detailed schema for asset catalogs
• Security Model - Security considerations for agent assets
• Setup Guides - Platform-specific installation instructions
• CLI Reference - Complete apx command documentation

Related Pages

Related topics: Installation Guide, Claude Code Integration, Codex Integration

MCP Configurations

Overview

MCP (Model Context Protocol) Configurations in Agent Powerups provide pre-configured MCP server definitions that extend the tool access capabilities of coding agents. These configurations enable agents to interact with external services—such as GitHub—through a standardized protocol, allowing them to perform tasks like querying repositories, managing issues, or executing API operations that would otherwise require manual user intervention.

The MCP configuration system is designed with a local-first approach. Configurations are reviewed before loading, with explicit install commands and smoke tests to validate functionality before integration into an agent's environment. Sources: README.md

Purpose and Scope

Agent Powerups ships MCP configurations as part of its core asset delivery. The primary goals of these configurations are:

Currently, the shipped MCP configuration is github-local, which enables GitHub API interaction through a local MCP server setup. Sources: README.md Sources: mcp/generic/github-local.json

Architecture

Multi-Target Configuration Model

Agent Powerups maintains MCP configurations in variant-specific directories to support different agent platforms. Each variant may use a different configuration format or require platform-specific adjustments.

mcp/
├── claude-code/
│   └── github-local.json      # Claude Code manifest format
├── codex/
│   └── github-local.toml      # Codex TOML format
└── generic/
    └── github-local.json      # Generic JSON format

The CLI automatically selects the appropriate variant based on the --target parameter when executing MCP commands. Sources: src/cli/commands/mcp.ts:51-55 Sources: docs/mcp-configs.md

Configuration Resolution Flow

graph TD
    A[apx mcp command] --> B{Which target?}
    B -->|codex| C[Select TOML variant]
    B -->|claude-code| D[Select JSON variant]
    B -->|generic| E[Select JSON variant]
    C --> F[Resolve target path]
    D --> F
    E --> F
    F --> G{Command type?}
    G -->|check| H[Validate config structure]
    G -->|smoke| I[Execute smoke test]
    G -->|install| J[Copy to agent root]
    H --> K[Return validation result]
    I --> L[Run server test]
    J --> M[Write config to target]

Available MCP Configurations

github-local

The github-local MCP configuration provides GitHub API integration for coding agents. It requires environment variables for authentication and supports local-first operation without relying on cloud-based MCP routing.

#### Variant Differences

Sources: mcp/generic/github-local.json Sources: mcp/claude-code/github-local.json Sources: mcp/codex/github-local.toml

MCP CLI Commands

The apx CLI provides several commands for working with MCP configurations. Sources: src/cli/commands/mcp.ts

Command Reference

Target Parameters

Usage Examples

# Check configuration validity
apx mcp check github-local --target generic --json

# Smoke test the MCP server
apx mcp smoke github-local --json

# Preview installation
apx mcp install github-local --target codex --dry-run

# Install to Claude Code
apx mcp install github-local --target claude-code --dry-run

# Write to custom location
apx mcp write github-local --target generic --dest .agent-powerups/github-local.json

Sources: README.md Sources: src/cli/commands/mcp.ts:51-55

Configuration Validation

Check Command

The check command validates the structural integrity of an MCP configuration. It verifies:

• Required environment variables are documented
• Configuration file is valid JSON/TOML
• All referenced resources are present

export async function runMcpCheckCommand(
  service: CatalogService,
  assetName: string,
  target: InstallTarget,
  env: NodeJS.ProcessEnv = process.env,
): Promise<ExecutionResult<McpCheckData>>

The command returns the required environment variables and their current status:

{
  "required_env": [
    { "name": "GITHUB_TOKEN", "set": true }
  ]
}

Sources: src/cli/commands/mcp.ts:57-75

Smoke Test

The smoke command performs a lightweight runtime verification of the MCP configuration. It attempts to initialize the MCP server with the provided configuration to ensure it can start without errors.

Security Considerations

MCP configurations expand an agent's tool access capabilities. Review all configurations before loading them into a trusted agent environment.

Security Warnings

Sources: src/cli/commands/mcp.ts:40-45 Sources: README.md

Safety Best Practices

1. Review First: Always inspect configuration content with apx mcp print before installing
2. Dry Run: Use --dry-run to preview all installation actions
3. Smoke Test: Run apx mcp smoke to verify the configuration works
4. Environment Isolation: Use environment variables for secrets rather than hardcoding
5. Version Control: Do not commit configuration files containing real credentials

Integration with Setup Commands

MCP configurations can be installed as part of the broader agent setup process. When running apx setup, MCP configurations under agent-powerups/mcp/ are included in the staging area.

# Setup includes MCP configs by default
apx setup codex --mode recommended --yes

# MCP configs are review-only in copied files
# Do not paste tokens into copied files

Sources: examples/codex/README.md Sources: examples/claude-code/README.md

Adding New MCP Configurations

To add a new MCP configuration to Agent Powerups:

1. Create Configuration Files

Create variant-specific configurations in the appropriate subdirectories:

mcp/
├── <target1>/
│   └── <config-name>.<json|toml>
├── <target2>/
│   └── <config-name>.<json|toml>
└── generic/
    └── <config-name>.json

2. Register in Catalog

Add the configuration to the asset catalog with proper metadata:

{
  "name": "<config-name>",
  "type": "mcp-config",
  "path": "mcp/generic/<config-name>.json",
  "targets": {
    "codex": "mcp/codex/<config-name>.toml",
    "claude-code": "mcp/claude-code/<config-name>.json"
  },
  "mcp": {
    "required_env": ["API_TOKEN"],
    "warning": "Requires valid API token"
  }
}

3. Validate Structure

Test the configuration with the validation commands:

apx mcp check <config-name> --target generic --json
apx mcp smoke <config-name> --json
apx plugins validate --all  # If part of a plugin bundle

Summary

MCP Configurations in Agent Powerups provide a standardized, safe mechanism for extending coding agent capabilities through the Model Context Protocol. Key features include:

• Multi-target support for Codex, Claude Code, and generic agents
• Local-first design with explicit review and validation steps
• Comprehensive CLI tooling for check, smoke, and install operations
• Security-first approach requiring explicit approval and dry-run support
• Variant-specific configurations to accommodate different agent platforms

Related Pages

Related topics: Skills System, Plugin Bundles

Hooks and Commands

Overview

Hooks and Commands are two complementary systems within Agent Powerups that extend the capabilities of coding agents through structured automation and guided workflows. While both systems enhance agent behavior, they serve distinct purposes:

• Hooks are automated triggers that execute at specific points during agent operations, acting as pre-flight checks or post-action summaries
• Commands are structured, review-first prompts that guide agents through complex multi-step workflows

Sources: README.md

Architecture Overview

graph TD
    subgraph "Agent Environment"
        A[Agent] --> |triggers| H[Hooks System]
        A --> |invokes| C[Commands System]
    end
    
    subgraph "Hooks"
        H --> |productivity| HP1[no-secrets-preflight]
        H --> |productivity| HP2[handoff-summary]
        H --> |quality| HQ1[lint-check]
        H --> |quality| HQ2[test-gate]
    end
    
    subgraph "Commands"
        C --> |ship| CS[ship-check]
        C --> |triage| CT[triage]
    end
    
    H --> |execution| F[File System / API]
    C --> |review prompts| R[Review Output]

Hooks System

Purpose and Scope

Hooks are lightweight automation units that execute automatically at defined points in an agent's lifecycle. They serve as:

1. Pre-flight checks - Validate conditions before actions proceed
2. Post-action summaries - Generate documentation after handoffs
3. Quality gates - Ensure code meets standards before progression

Sources: hooks/productivity/no-secrets-preflight.md

Hook Categories

Available Hooks

#### no-secrets-preflight

A productivity hook that scans files for potential secret exposure before agent operations proceed.

Trigger: Before file operations or commit actions

Behavior:

• Scans specified files and paths for patterns matching API keys, tokens, and credentials
• Flags common secret formats: AWS keys, GitHub tokens, database connection strings
• Reports findings without blocking (advisory mode)

Sources: hooks/productivity/no-secrets-preflight.md

#### handoff-summary

A productivity hook that generates structured summaries during agent-to-agent or session-to-session handoffs.

Trigger: End of session or before context transfer

Output:

• Current work status
• Pending tasks and blockers
• Relevant context for the receiving agent
• File modifications summary

Sources: hooks/productivity/handoff-summary.md

#### lint-check

A quality hook that validates code style and linting compliance.

Trigger: Before commit or pull request creation

Checks:

• ESLint/Prettier compliance (TypeScript/JavaScript)
• Language-specific linting standards
• Configured rule violations

Sources: hooks/quality/lint-check.md

#### test-gate

A quality hook that ensures test coverage meets minimum thresholds before code progression.

Trigger: Before merge or deployment

Thresholds:

• Minimum coverage percentage (configurable)
• Required test categories passed
• No failing test suites

Sources: hooks/quality/test-gate.md

Hook Execution

graph LR
    A[apx hooks run] --> B[Load Hook Config]
    B --> C[Scan Target Path]
    C --> D{Hook Type?}
    D -->|preflight| E[Execute Checks]
    D -->|summary| F[Generate Report]
    D -->|quality| G[Run Validations]
    E --> H[Report Results]
    F --> H
    G --> I{Checks Pass?}
    I -->|Yes| H
    I -->|No| J[Block Action]

Hook CLI Commands

Sources: README.md

Commands System

Purpose and Scope

Commands are structured, review-first prompts designed for complex multi-step workflows. Unlike hooks which run automatically, commands are explicitly invoked by agents or users to:

1. Guide complex processes - Step-by-step workflows with checkpoints
2. Enforce review points - Mandatory review stages before progression
3. Provide safe runnable checks - Validated automation with human oversight

Sources: commands/ship-check.md

Available Commands

#### ship-check

A comprehensive pre-release validation command that ensures code is ready for shipping.

Stages:

1. Code Quality Review

• Linting compliance
• Type checking
• Formatting standards

1. Test Verification

• Unit test coverage
• Integration test status
• E2E test results

1. Security Scan

• Secret detection
• Dependency vulnerability check
• License compliance

1. Documentation Review

• README completeness
• Changelog updates
• API documentation

1. Final Review

• Breaking change detection
• Version bump validation
• Release notes generation

Sources: commands/ship-check.md

#### triage

A command for systematic issue and PR triage workflow.

Purpose: Streamline the process of reviewing, categorizing, and prioritizing incoming issues and pull requests.

Workflow:

1. Extract issue/PR metadata
2. Assess priority and complexity
3. Assign appropriate labels
4. Route to relevant team members or skill sets
5. Document triage decision

Sources: commands/triage.md

Command CLI Commands

Sources: README.md

Integration with Agent Workflows

Hook-Command Relationship

graph TD
    subgraph "Workflow"
        C1[Start Task] --> H1[Hook: preflight check]
        H1 --> |pass| C2[Plan Review]
        H1 --> |fail| C3[Fix Issues]
        C3 --> H1
        C2 --> CMD1[Command: ship-check]
        CMD1 --> H2[Hook: quality gate]
        H2 --> |pass| CMD2[Command: triage]
        H2 --> |fail| C3
        CMD2 --> H3[Hook: handoff summary]
        H3 --> C4[Complete]
    end

Target Agent Compatibility

Tool Requirements

Hooks and Commands may require external tools for full functionality:

Required Tools by Hook

Required Tools by Command

Sources: docs/tool-requirements.md

Usage Examples

Running a Single Hook

# Check for secrets in specific file
apx hooks run no-secrets-preflight --path ./config/secrets.yaml

# Check entire project
apx hooks run no-secrets-preflight --all

Running a Command

# Execute ship-check with full output
apx commands run ship-check --full

# Get JSON output for automation
apx commands run ship-check --json

Custom Hook Integration

Hooks can be integrated into agent workflows by adding to agent configuration:

## Pre-Task Hooks
Before any file modification:
1. Run `apx hooks run no-secrets-preflight --path {target}`

## Post-Task Hooks  
After task completion:
1. Run `apx hooks run handoff-summary --path {workspace}`

Security Considerations

Warning: Hooks can execute code when supported by the host agent. Review assets before loading them into a trusted agent environment.

Sources: README.md

Security Best Practices

1. Review hooks before enabling - Examine hook logic for unintended side effects
2. Limit hook scope - Run hooks on specific paths rather than entire filesystem
3. Validate tool access - Ensure required tools are from trusted sources
4. Monitor hook output - Review all hook execution logs

Extension Points

Creating Custom Hooks

Custom hooks follow the same structure as shipped hooks:

hooks/
└── <category>/
    └── <hook-name>.md

Creating Custom Commands

Custom commands follow the command structure:

commands/
└── <command-name>.md

Both custom hooks and commands can be discovered and managed through the apx CLI using the standard list, print, and run subcommands.

Summary

Hooks and Commands form the operational backbone of Agent Powerups, enabling:

• Automated quality assurance through hooks like lint-check and test-gate
• Security pre-flight checks via no-secrets-preflight
• Workflow continuity with handoff-summary
• Guided complex workflows through ship-check and triage commands

Together, they provide a framework for maintaining code quality, security, and consistent workflows across agent interactions.

Related Pages

Related topics: Installation Guide, Codex Integration, Gemini Integration

Claude Code Integration

Claude Code Integration enables Agent Powerups assets to be installed and utilized within Claude Code agent environments. This integration provides a structured approach for staging reusable skills, plugin bundles, MCP configurations, and AGENTS.md templates specifically tailored for Claude Code workflows.

Overview

Agent Powerups positions itself as "Oh My Zsh for coding agents," and Claude Code represents one of the primary supported agent surfaces. The integration allows Claude Code to access:

• Reusable skills located at agent-powerups/skills/
• Plugin bundles under agent-powerups/plugins/
• Command packs for specialized workflows
• MCP server configurations
• AGENTS.md instruction templates

Sources: README.md:1-50

Agent Profile Configuration

Claude Code has a dedicated agent profile defined in the CLI setup system. This profile controls installation paths, environment variables, and instruction file locations.

Sources: src/cli/commands/setup.ts:50-65

Environment Variable Resolution

The setup system resolves the Claude Code root directory by checking environment variables in priority order:

1. CLAUDE_CONFIG_DIR
2. CLAUDE_HOME
3. Fallback to ~/.claude

graph TD
    A[Resolve Claude Code Root] --> B{CLAUDE_CONFIG_DIR set?}
    B -->|Yes| C[Use CLAUDE_CONFIG_DIR]
    B -->|No| D{CLAUDE_HOME set?}
    D -->|Yes| E[Use CLAUDE_HOME]
    D -->|No| F[Use ~/.claude]
    C --> G[Install assets under resolved root]
    E --> G
    F --> G

Sources: src/cli/commands/setup.ts:50-65

Installation Modes

Claude Code setup supports three installation modes that control the scope of assets deployed:

Minimal Mode

Bootstrap setup that installs only essential skills. Recommended as a starting point for new users.

apx setup claude-code --mode minimal --yes

Installed skills in minimal mode:

• using-powerups
• no-fluff
• repo-map
• writing-plans
• verification-before-completion
• search-before-building

Sources: src/cli/commands/setup.ts:95-100

Recommended Mode

Full recommended setup that installs all stable plugin bundles and the complete skill catalog.

apx setup claude-code --mode recommended --yes

This mode installs the stable plugin bundles:

• dev-vitals
• debugging-diagnostics
• quality-gates

Sources: src/cli/commands/setup.ts:100-105

Full Mode

Comprehensive staging that includes support assets under agent-powerups/ and updates existing global instructions with backup preservation.

apx setup claude-code --mode full --yes

Setup Workflow

Dry-Run Validation

Before applying any changes, perform a dry-run to preview installation actions:

apx setup claude-code --dry-run

This command displays what would be installed without making filesystem modifications.

Instruction File Handling

The setup system handles existing CLAUDE.md files with the following logic:

graph TD
    A[Setup Claude Code] --> B{CLAUDE.md exists?}
    B -->|Yes| C[Create backup of CLAUDE.md]
    B -->|Yes| D[Append agent-powerups block]
    B -->|No| E[Create instructions directory]
    B -->|No| F[Write agent-powerups.md]
    D --> G[Report manual steps]
    F --> G

When CLAUDE.md exists, the setup appends a marked block between <!-- START agent-powerups --> and <!-- END agent-powerups --> markers. When the file does not exist, setup writes instructions to agent-powerups\instructions\agent-powerups.md and reports manual steps required.

Sources: examples/claude-code/README.md:1-25

Explicit Root Installation

For safer installation to a specific directory:

apx setup claude-code --agent-root .agent-powerups-demo\claude --yes

This approach isolates the installation to a disposable location for review before committing to the actual Claude Code configuration.

Asset Deployment Structure

The setup system copies assets to the following structure under the Claude Code root:

Sources: src/cli/commands/setup.ts:150-160

MCP Configuration for Claude Code

Claude Code has a dedicated MCP target directory. MCP configurations are placed under agent-powerups/mcp/claude-code/ for review purposes.

MCP Check Command

Validate an MCP configuration for Claude Code:

apx mcp check github-local --target claude-code

MCP Smoke Test

Perform a smoke test on MCP configuration:

apx mcp smoke github-local --json

MCP Install Preview

Preview a managed Claude Code MCP installation:

apx mcp install github-local --target claude-code --dry-run

Sources: src/cli/commands/mcp.ts:1-30

Security Notes

MCP snippets under agent-powerups/mcp/ are marked as review-only. Users should not paste tokens into copied files without local substitution of placeholders.

Post-Installation Verification

After setup, verify the installation using these commands:

apx commands print ship-check --target claude-code
apx info using-powerups

Available Commands for Claude Code

Available Skills

After installation, Claude Code has access to skills including:

• systematic-debugging
• no-fluff
• writing-plans
• ai-slop-cleaner
• bigquery-cost-audit
• data-quality
• dbt-incremental-strategy-audit
• dbt-preflight
• dbt-strategy
• metric-impact-analyzer
• requesting-code-review
• receiving-code-review
• pr-triage
• repo-map
• bug-hunt
• safe-refactor
• sql-business-logic-review
• defuddle
• markitdown-file-intake
• graphify

Plugin Bundles

Claude Code supports installation of plugin bundles that group related skills, agents, and commands.

Stable Plugin Bundles

Beta Plugin Bundles

Available beta bundles include codebase-maintenance, data-engineering, documentation-systems, machine-learning-ops, codebase-intelligence, spec-driven-development, spec-quality-gates, context-efficiency, tool-integrations, and memory-optimization.

Plugin Installation

apx plugins list
apx plugins info dev-vitals
apx plugins validate --all
apx plugins install dev-vitals --target claude-code --dry-run

Rollback and Cleanup

To remove an Agent Powerups installation from Claude Code:

Remove-Item .agent-powerups-demo -Recurse -Force

Replace .agent-powerups-demo with the actual installation path if a custom root was specified.

Example: Complete Setup Workflow

graph LR
    A[apx doctor] --> B[apx list]
    B --> C[apx setup claude-code --dry-run]
    C --> D[apx setup claude-code --mode recommended --yes]
    D --> E[apx commands print ship-check --target claude-code]
    E --> F[apx plugins install dev-vitals --target claude-code]

``powershell apx doctor ``

1. Run system diagnostics:

``powershell apx list ``

1. List available assets:

``powershell apx setup claude-code --dry-run ``

1. Preview setup:

``powershell apx setup claude-code --mode recommended --yes ``

1. Apply recommended setup:

``powershell apx commands print ship-check --target claude-code ``

1. Verify command availability:

``powershell apx plugins install dev-vitals --target claude-code ``

1. Install desired plugin bundle:

Sources: examples/claude-code/README.md:1-30

Limitations and Considerations

• The integration does not modify Claude Code's core configuration files directly
• MCP server tokens must be replaced locally and should never be committed
• External tools require explicit user approval before installation
• Skills may instruct Claude Code to read local files or run commands—review assets before loading them into a trusted agent environment
• Shell profiles, secrets, background processes, hooks, and MCP servers are not automatically enabled

Related Pages

Related topics: Installation Guide, Claude Code Integration, Gemini Integration

Codex Integration

Overview

The Codex Integration module provides native installation, configuration, and management capabilities for deploying Agent Powerups assets into a Codex agent environment. Codex, developed by OpenAI, is a coding agent that can read and modify codebases, execute commands, and assist with software development tasks. The integration layer bridges Agent Powerups' skill system, plugin bundles, MCP configurations, and command templates with Codex's agent surface.

Agent Powerups acts as an "Oh My Zsh for coding agents" — providing reusable workflows, skills, and configurations that extend the native capabilities of supported agent platforms. For Codex specifically, the integration handles:

• Copying skills and plugin bundles to the appropriate directory structure
• Managing the AGENTS.md instruction file with marked powerups blocks
• Configuring MCP server snippets for GitHub integration
• Validating requirements and performing pre-flight checks
• Providing a safe, review-first workflow before any mutations occur

Sources: README.md

Architecture

Agent Profile Configuration

The Codex agent profile defines the target environment for all installation operations. The profile is defined in setup.ts and establishes critical path mappings:

Sources: src/cli/commands/setup.ts:46-58

Directory Structure

After successful integration, the following structure is created under <codex-root>/agent-powerups/:

<codex-root>/
├── agent-powerups/
│   ├── skills/                    # Reusable agent workflows
│   ├── plugins/                   # Plugin bundles
│   ├── agents-md/                 # AGENTS.md templates
│   ├── commands/codex/            # Codex-specific commands
│   ├── mcp/codex/                 # MCP server configurations
│   ├── hooks/                     # Hook examples
│   ├── workflows/                 # Workflow templates
│   └── docs/setup/                # Setup documentation
└── AGENTS.md                      # Updated with powerups block

Sources: src/cli/commands/setup.ts:120-135

Installation Modes

Agent Powerups supports three installation modes for Codex, each catering to different use cases and risk tolerances.

Mode Comparison

Sources: README.md

Minimal Mode Skills

The minimal mode installs a curated set of essential skills that provide fundamental capabilities without overwhelming the agent with specialized workflows:

const MINIMAL_SKILLS = [
  "using-powerups",           // Orientation to Agent Powerups system
  "no-fluff",                 // Concise, actionable responses
  "repo-map",                 // Repository structure understanding
  "writing-plans",            // Structured planning capabilities
  "verification-before-completion",  // Output validation
  "search-before-building",   // Existing code investigation
] as const;

Sources: src/cli/commands/setup.ts:80-87

Recommended Mode Additions

The recommended mode includes the minimal skills plus stable plugin bundles that enhance development productivity:

const RECOMMENDED_PLUGIN_BUNDLES = [
  "dev-vitals",              // Development health metrics
  "debugging-diagnostics",   // Systematic debugging workflows
  "quality-gates",           // Code quality checkpoints
] as const;

Sources: src/cli/commands/setup.ts:89-93

Workflows

Manual Native Install

The primary installation path for humans is the apx install command, which writes native skills and plugin bundles directly to the agent root.

# Dry run to preview changes
apx install codex --dry-run

# Standard install with output summary
apx install codex

# Verbose mode showing per-file paths
apx install codex --verbose

# Full install including support assets and instruction updates
apx install codex --full

Sources: README.md

Agent-Curated Setup

For agent-managed installations, the setup workflow provides an interactive planning phase:

# Preview what will happen
apx setup codex --dry-run

# Apply recommended setup
apx setup codex --mode recommended --yes

The agent will inspect available skills and plugins, propose a plan, and apply it after user approval.

Sources: README.md

MCP Server Integration

The GitHub MCP server can be integrated with Codex for extended GitHub functionality:

# Check MCP configuration validity
apx mcp check github-local --target codex --json

# Smoke test the MCP setup
apx mcp smoke github-local --json

# Dry run before installation
apx mcp install github-local --target codex --dry-run

# Print MCP configuration for review
apx mcp print github-local --target codex

Sources: README.md

Plugin Bundle Installation

Individual plugin bundles can be installed for specific functionality:

# List available bundles
apx plugins list

# Inspect a specific bundle
apx plugins info dev-vitals

# Validate bundle structure
apx plugins validate --all

# Install to Codex with dry run
apx plugins install dev-vitals --target codex --dry-run

Sources: README.md

Instruction File Management

Block Format

The integration uses HTML comment markers to wrap the Agent Powerups section in AGENTS.md:

<!-- START agent-powerups -->

## Agent Powerups

Agent Powerups assets are installed at `<codex-root>/agent-powerups/`.

Use these local assets when relevant:
- Read `agent-powerups/skills/using-powerups/SKILL.md` before first use.
- Use `apx` commands to discover, inspect, validate, and extend setup.
- Skills are at `agent-powerups/skills/`.
- Plugin bundles are at `agent-powerups/plugins/`.

<!-- END agent-powerups -->

Instruction Generation Logic

The instruction block content varies based on the selected mode:

Sources: src/cli/commands/setup.ts:20-50

Safe Update Behavior

The system implements safe update patterns to protect existing configurations:

1. If AGENTS.md exists, a backup is created before modification
2. The system searches for existing agent-powerups blocks
3. If a block exists, it is replaced; otherwise, a new block is appended
4. If AGENTS.md does not exist, instructions are written to agent-powerups/instructions/agent-powerups.md with manual steps reported

Sources: examples/codex/README.md

Validation and Health Checks

Doctor Command

The apx doctor command performs comprehensive health checks on the installation:

apx doctor

Doctor checks include:

• Validating SKILL.md frontmatter (name and description required)
• Verifying support file references exist
• Checking referenced support files are present

const frontmatter = parseFrontmatter(content);
if (!frontmatter?.name || !frontmatter?.description) {
  issues.push(`${entry.name}: missing required frontmatter`);
}

for (const ref of referencedSupportFiles(content)) {
  if (!(await supportRefExists(skillDir, ref))) {
    issues.push(`${entry.name}: missing referenced support file ${ref}`);
  }
}

Sources: src/cli/commands/doctor.ts:60-75

Requirement Checks

The apx check command validates that requirements are met:

apx check

This includes:

• Parsing requirement declarations from skill and command files
• Verifying installed versions match requirements
• Optionally installing missing requirements with user approval

const hasFailures = statuses.some((status) => status.status === "MISSING");
if (hasFailures) {
  failures += 1;
  if (installOptions?.installMissing) {
    const installResult = await installMissingRequirements(...);
  }
}

Sources: src/cli/commands/check.ts:45-60

Security Audit

The security audit command scans for potential vulnerabilities in configuration files:

apx security-audit

Detectable patterns include:

• Unpinned :latest container images
• Broad filesystem write patterns
• Install commands without --dry-run guards
• Exposed secrets in configuration

{
  name: "broad-filesystem-write",
  severity: "P1",
  pattern: /(?:rm\s+-rf\s+\/|"path"\s*:\s*"\*\*|write_file\s+\/\*\*)/i,
  detail: () => `broad filesystem write or recursive delete pattern`,
},
{
  name: "missing-dry-run",
  severity: "P1",
  pattern: /(?:npm\s+install|pip\s+install|cargo\s+install|gem\s+install)\b(?!.*(?:--dry-run|-n\b))/i,
  detail: (m) => `install command without --dry-run guard: ${m.trim().slice(0, 60)}`,
},

Sources: src/cli/commands/security-audit.ts:25-40

Example Workflow

Setting Up for Codex Review

A typical workflow for staging Agent Powerups for Codex review:

# 1. Preview installation changes
apx setup codex --dry-run

# 2. Apply with explicit root directory
apx setup codex --agent-root .agent-powerups-demo\codex --yes

# 3. Inspect installed skills
apx info using-powerups
apx check using-powerups

# 4. List available commands
apx commands list

# 5. Run pre-flight checks
apx commands run ship-check
apx hooks run no-secrets-preflight --all

# 6. Validate MCP configuration
apx mcp check github-local --target codex --json
apx mcp smoke github-local --json

Sources: examples/codex/README.md

Rollback Procedure

To remove the integration and restore the original state:

Remove-Item .agent-powerups-demo -Recurse -Force

Sources: examples/minimal/README.md

Safety Model

The integration implements safety boundaries around several areas:

Sources: README.md

The security audit further enforces safety by detecting:

• Unpinned container images in CI configurations
• Dangerous filesystem operations
• Install commands without dry-run guards

Sources: src/cli/commands/security-audit.ts:25-45

Requirements Installation

When requirements are missing, the system can automatically install them:

apx check --install-missing --yes

The installation flow:

1. Identifies supported installers for the platform (npm, pip, cargo, gem)
2. Generates dry-run output if --dry-run is specified
3. Prompts for confirmation in interactive mode
4. Executes approved installers with appropriate arguments

const approved = options.yes || (await confirmInstall(assetName, installers));
if (!approved) {
  return {
    output: "install-missing: declined or non-interactive without --yes",
    warnings: [`${assetName}: install-missing not approved`],
    actions: [],
  };
}

Sources: src/cli/utils/requirements.ts:35-55

External Commands Execution

When running external commands (e.g., during doctor checks or requirement installation), the system handles platform differences:

const launchCommand = process.platform === "win32" && command.endsWith(".cmd")
  ? "cmd.exe"
  : command;
const launchArgs = process.platform === "win32" && command.endsWith(".cmd")
  ? ["/d", "/s", "/c", command, ...args]
  : args;

This ensures proper execution on Windows while maintaining cross-platform compatibility.

Sources: src/cli/commands/doctor.ts:78-83

Related Pages

Related topics: Installation Guide, Claude Code Integration, Codex Integration

Gemini Integration

Overview

Gemini Integration in Agent Powerups provides a persistent secondary-agent delegation system that enables coding agents to leverage Google's Gemini AI as a reliable backup or complementary reasoning engine. The integration supports both one-shot queries via the ask CLI command and persistent relay sessions that maintain context across multiple conversation turns.

The Gemini integration follows the same Oh My Zsh-style philosophy as the rest of Agent Powerups—providing reusable, composable assets that extend agent capabilities without requiring deep configuration or manual setup. Sources: README.md

Architecture

The Gemini Integration consists of three primary layers working in concert:

graph TD
    subgraph "CLI Layer"
        A["apx ask-gemini"] --> B["ask.ts"]
        C["apx relay"] --> D["relay.ts"]
    end
    
    subgraph "Integration Layer"
        B --> E["Gemini API"]
        D --> E
        F["gemini-extension.json"] --> G["Plugin Bundle"]
    end
    
    subgraph "Agent Layer"
        G --> H["Claude Code"]
        G --> I["Codex"]
        E --> J["Persistent Context"]
    end

Core Components

Sources: gemini-extension.json | src/cli/commands/ask.ts | src/cli/commands/relay.ts

Setup and Configuration

Prerequisites

Before using Gemini Integration, ensure the following are available:

• Node.js environment with apx CLI installed
• Valid Google AI API credentials (Gemini API key)
• Agent Powerups installed via npm install && npm run build && npm link

Sources: docs/setup/gemini.md

Installation Methods

Agent Powerups supports multiple installation paths for Gemini integration:

#### Manual Native Install

apx install gemini --dry-run
apx install gemini
apx install gemini --full --verbose

The --full flag stages support assets under agent-powerups/ and updates existing global instructions with a backup. Sources: README.md

#### Agent-Curated Setup

apx setup gemini --dry-run
apx setup gemini --mode minimal --yes    # bootstrap only
apx setup gemini --mode recommended --yes  # recommended setup
apx setup gemini --mode full --yes       # broad staging

The setup process appends a marked agent-powerups block to the agent's instructions file after creating a backup. Sources: docs/setup/gemini.md | src/cli/commands/setup.ts

Environment Variables

The following environment variables are required or optional:

One-Shot Query Mode

The ask-gemini command provides immediate delegation for single queries without maintaining conversation state:

apx ask-gemini "Return OK only" --json

Usage Patterns

# Basic query with JSON output
apx ask-gemini "Review this plan" --json

# Check dependencies without execution
apx check ask-gemini

# Preview missing dependencies
apx check ask-gemini --install-missing --dry-run

Sources: README.md

Data Flow

sequenceDiagram
    participant User
    participant CLI as apx ask-gemini
    participant API as Gemini API
    participant Output as JSON Response
    
    User->>CLI: apx ask-gemini "query" --json
    CLI->>API: POST request with prompt
    API->>Output: JSON response
    Output-->>User: Structured result

Persistent Relay Sessions

The relay system maintains persistent context across multiple conversation turns, enabling more coherent multi-turn workflows:

apx relay init second-opinion
apx relay start second-opinion --provider gemini
apx relay ask second-opinion "Review this plan" --json
apx relay status second-opinion
apx relay stop second-opinion

Session Lifecycle

Sources: workflows/agent-relay.md | src/cli/commands/relay.ts

Relay Workflow Architecture

graph LR
    A[User Request] --> B[Relay Init]
    B --> C[Relay Start]
    C --> D[Context Established]
    D --> E[Relay Ask Query]
    E --> F[Gemini API]
    F --> G[Response + Updated Context]
    G --> E
    G --> H[Relay Stop]

Plugin Bundle Structure

The Gemini extension plugin bundle includes manifests for multiple agent surfaces:

gemini-extension/
├── .claude-plugin/
│   └── plugin.json      # Claude Code Manifest
├── .codex-plugin/
│   └── plugin.json      # Codex Manifest
├── GEMINI.md            # Context instructions
└── skills/
    └── ask-gemini/
        └── SKILL.md

Manifest Validation

The apx doctor command validates plugin bundle integrity across all agent targets:

apx doctor --full --json

Validation checks include:

• File existence in all required paths
• Manifest name consistency
• Manifest version alignment (must be 0.1.0)
• Context filename verification (GEMINI.md for Gemini)

Sources: src/cli/commands/doctor.ts | plugins/README.md

Integration with Profiles

Gemini Integration can be accessed through user-intent profiles that bundle relevant skills and plugins:

apx profiles list
apx profiles info safe-core
apx profiles plan safe-core --target codex

Profiles provide curated skill/plugin sets optimized for specific use cases, potentially including ask-gemini as part of a secondary-opinion workflow. Sources: README.md

Safety Considerations

Security Warnings

The Gemini integration follows Agent Powerups security model:

• External Tools: Require explicit user approval before installation
• API Keys: Never paste tokens directly into agent context unless strictly necessary
• MCP Servers: Require explicit user approval via apx mcp check and apx mcp smoke before enabling

# Verify MCP configuration before enabling
apx mcp check github-local --target generic
apx mcp smoke github-local --json

Sources: README.md | docs/setup/gemini.md

Dry-Run First

Always preview operations before execution:

# Preview setup without applying
apx setup gemini --dry-run

# Preview installation without writing
apx install gemini --dry-run

Dry-run mode shows the planned actions without modifying any files, allowing review of changes before acceptance. Sources: docs/setup/gemini.md

Command Reference

Quick Reference Table

Workflow Integration

The Gemini integration supports the agent-relay workflow for complex multi-turn scenarios:

apx workflows list
apx workflows print feature-iteration
apx workflows print agent-relay

This enables using Gemini as a persistent second opinion during feature development iterations. Sources: workflows/agent-relay.md | README.md

Doramagic Pitfall Log

Doramagic extracted 9 source-linked risk signals. Review them before installing or handing real data to the project.

1. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: identity.distribution | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | repo=agent-powerups; install=markitdown

2. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | host_targets=mcp_host, claude, claude_code

3. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | README/documentation is current enough for a first validation pass.

4. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | last_activity_observed missing

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | no_demo; severity=medium

7. Security or permission risk: v0.1.4

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v0.1.4. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/yeaight7/agent-powerups/releases/tag/v0.1.4

8. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | issue_or_pr_quality=unknown

9. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1222971895 | https://github.com/yeaight7/agent-powerups | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using agent-powerups with real data or production workflows.

• v0.1.4 - github / github_release
• v0.1.2 - github / github_release
• Project risk needs validation - GitHub / issue