ai-plugin-usage

AI Companion Plugin Usage Guide

This skill helps you get the most out of the AI Companion plugin for Claude Code. The plugin bridges Claude Code with AI backends (Codex and GitHub Copilot) for code reviews, task delegation, and background job management.

Quick Start

Installation

/plugin marketplace add NguyenNhan1610/codex-copilot-plugin-cc
/plugin install ai@ai-backends
/reload-plugins
/ai:setup

If Codex is not installed, /ai:setup can install it for you (requires npm). If Codex is installed but not authenticated, run:

!codex login

First Run

/ai:review --background
/ai:status
/ai:result

Commands Reference

Code Review

/ai:review - Standard & Aspect-Based Code Review

Runs a read-only AI review on your current work. Supports optional aspect-based focusing for deep, structured analysis with exact code snippets as evidence.

# Standard review (native when backend supports it)
/ai:review                              # Review uncommitted changes
/ai:review --base main                  # Review branch vs main
/ai:review --background                 # Run in background

# Aspect-based review (detailed, structured analysis)
/ai:review security                     # Security-focused (OWASP-style)
/ai:review python:performance           # Python performance review
/ai:review python/fastapi:security      # FastAPI-specific security review
/ai:review typescript/nextjs:performance # Next.js App Router performance review
/ai:review dart/flutter:architecture    # Flutter architecture review
/ai:review --base main python:antipatterns # Branch diff with aspect

Available aspects:

• security — injection, auth, data exposure, OWASP Top 10
• performance — hotspots, complexity, memory, I/O patterns
• architecture — coupling, cohesion, SOLID, separation of concerns
• antipatterns — language-specific bad patterns and code smells

Supported languages: python, typescript, dart

Supported techstacks:

• Python: fastapi, django
• TypeScript: nextjs
• Dart: flutter

Language prefix is optional. When provided, the review applies language/framework-specific patterns. When a techstack is specified (e.g., python/fastapi:security), a dedicated template with framework-specific checks is used.

• Read-only: never modifies code
• For custom focus text or adversarial framing, use /ai:adversarial-review

/ai:adversarial-review - Challenge Review

Runs a steerable review that questions implementation choices and design tradeoffs. Pressure-tests assumptions, failure modes, and alternative approaches.

/ai:adversarial-review
/ai:adversarial-review --base main challenge whether this caching design is right
/ai:adversarial-review --background look for race conditions

Use this when you want to:

• Challenge the direction, not just the code details
• Focus on design choices, tradeoffs, and hidden assumptions
• Pressure-test around specific risk areas (auth, data loss, rollback, race conditions)

Also read-only: does not fix code.

Multi-Agent Council

/ai:council - Multi-Agent Discussion

Runs multiple AI agents in parallel, each analyzing the codebase from a different perspective. After independent analysis, agents debate each other's findings. A synthesis agent produces the final verdict.

/ai:council --roles security,performance           # Default topic
/ai:council --roles security,performance,architecture Analyze our auth flow
/ai:council --roles attacker,defender,judge Is our API rate limiting sufficient?
/ai:council --roles security,antipatterns --background

Discussion model (Parallel -> Debate -> Synthesis):

1. Round 1: All agents explore the codebase independently in parallel
2. Round 2: Each agent sees all Round 1 findings, challenges/agrees/adds
3. Synthesis: A judge agent resolves disagreements and produces the final verdict

Predefined roles: security, performance, architecture, antipatterns, attacker, defender, judge

Custom freeform roles are also accepted. Default roles (if --roles omitted): security, performance, architecture. Maximum 7 roles.

Total backend calls: 2 * N + 1 (3 roles = 7 calls).

Task Delegation

/ai:rescue - Delegate Work to Codex

Hands a task to Codex through the ai:rescue subagent. Write-capable by default.

/ai:rescue investigate why the tests started failing
/ai:rescue fix the failing test with the smallest safe patch
/ai:rescue --resume apply the top fix from the last run
/ai:rescue --fresh start a new investigation of the auth bug
/ai:rescue --model gpt-5.4-mini --effort medium investigate the flaky test
/ai:rescue --model spark fix the issue quickly
/ai:rescue --background investigate the regression

Key flags:

• --model provider:model - Select a specific model (e.g., codex:gpt-5.4, copilot:claude-opus-4.5)
• --effort <level> - Set reasoning effort: none, minimal, low, medium, high, xhigh
• --resume - Continue the latest rescue thread for this repo
• --fresh - Force a new thread even if a previous one exists
• --background / --wait - Control execution mode

Model shortcuts: spark maps to gpt-5.3-codex-spark.

You can also delegate naturally without the slash command:

Ask Codex to redesign the database connection to be more resilient.

Job Management

/ai:status - Check Job Progress

/ai:status                    # Show all running and recent jobs
/ai:status task-abc123        # Check a specific job
/ai:status task-abc123 --wait # Poll until a specific job completes

/ai:result - Get Job Output

/ai:result                    # Show latest finished job output
/ai:result task-abc123        # Show specific job output

Includes the Codex session ID when available, so you can resume in Codex directly with codex resume <session-id>.

/ai:cancel - Cancel a Job

/ai:cancel                    # Cancel the active job
/ai:cancel task-abc123        # Cancel a specific job

Setup & Configuration

/ai:setup - Plugin Setup

/ai:setup                          # Check backend readiness
/ai:setup --enable-review-gate     # Enable the review gate
/ai:setup --disable-review-gate    # Disable the review gate

Review Gate: When enabled, a Stop hook runs a targeted Codex review on Claude's recent changes before allowing the session to end. If issues are found, the stop is blocked so Claude can address them first. Warning: this can create long-running loops and drain usage limits.

Common Workflows

Review Before Shipping

/ai:review                    # Quick review of uncommitted changes
# or for branch review:
/ai:review --base main

Get a Second Opinion on Design

/ai:adversarial-review --base main challenge whether this was the right approach

Delegate a Bug Investigation

/ai:rescue investigate why the build is failing in CI
/ai:status                    # Check progress
/ai:result                    # Get findings

Long-Running Background Work

/ai:rescue --background investigate the flaky integration test
/ai:adversarial-review --background
# Later:
/ai:status
/ai:result

Continue Previous Work

/ai:rescue --resume apply the top fix from the last run
# Or resume directly in Codex:
codex resume <session-id>

Use a Specific Model or Effort Level

/ai:rescue --model gpt-5.4-mini --effort high fix the type error
/ai:rescue --model spark quick fix for the typo

Configuration

The plugin uses your existing Codex configuration. Customize defaults in config.toml:

User-level: ~/.codex/config.toml Project-level: .codex/config.toml (requires trusted project)

Example - always use gpt-5.4-mini with high effort for a project:

model = "gpt-5.4-mini"
model_reasoning_effort = "xhigh"

Config resolution order: user-level -> project-level overrides -> command-line flags.

Supported Backends

Feature	Codex (Default)	Copilot
Type	Persistent app server	Stateless CLI
Native reviews	Yes	No (task-based)
Auth	~/.codex/config.toml	GitHub Copilot CLI auth
Models	gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark	Via Copilot CLI

Troubleshooting

• "Codex not found": Run /ai:setup to check, or install manually with npm install -g @openai/codex
• "Not authenticated": Run !codex login to authenticate
• Review takes too long: Use --background and check with /ai:status
• Want to resume in Codex UI: Get the session ID from /ai:result, then run codex resume <session-id>
• Review gate draining limits: Disable with /ai:setup --disable-review-gate