Skip to content
BranchesTags

Repository files navigation

AIW - AI CLI Unified Gateway

中文版

Version Rust License

Unified Router & Proxy for AI CLI Tools

What is AIW?

AIW is a unified gateway that acts as an AI CLI proxy router with provider switching, role injection, and transparent parameter forwarding.

┌─────────────────────────────────────────────────────────────┐
│                         AIW Gateway                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────────────┐                                     │
│  │   AI CLI Router     │                                     │
│  │                     │                                     │
│  │  aiw claude ...  ───┼───► Claude CLI                     │
│  │  aiw codex ...   ───┼───► Codex CLI                      │
│  │  aiw gemini ...  ───┼───► Gemini CLI                     │
│  │                     │                                     │
│  │  + Provider Switch  │                                     │
│  │  + Role Injection   │                                     │
│  │  + Tool Search Unlock │                                    │
│  │  + Param Forwarding │                                     │
│  │  + CWD Control      │                                     │
│  └─────────────────────┘                                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Installation

# Install from crates.io
cargo install aiw

# Verify installation
aiw --version

AI CLI Router

Basic Usage

# Interactive mode - launch AI CLI directly
aiw claude    # Launch Claude CLI in interactive mode
aiw codex     # Launch Codex CLI in interactive mode
aiw gemini    # Launch Gemini CLI in interactive mode

# Non-interactive mode - with prompt
aiw claude "explain this code"
aiw codex "write tests"
aiw gemini "translate to Chinese"

# Auto mode: automatic failover across AI CLIs
aiw auto "fix this bug"              # Try CLIs in order, auto-switch on failure
aiw auto -p auto "implement feature" # Auto-switch CLIs + auto-select provider

# Route to multiple AI CLIs
aiw all "review this code"              # All available CLIs
aiw "claude|gemini" "compare approaches" # Specific CLIs

Provider Switching (-p)

# Switch API provider without changing AI CLI
aiw claude -p openrouter "explain this"
aiw claude -p glm "explain this"
aiw claude -p anthropic "explain this"

# Auto-select compatible provider
aiw claude -p auto "explain this"     # Randomly select compatible provider
aiw auto -p auto "implement feature"  # Auto CLI + auto provider

# Provider config: ~/.aiw/providers.json

Patch Management (File & Runtime)

AIW supports both persistent file patches and runtime memory patches for Claude Code, including anti-spy / anti-telemetry patches that blind CC's local environment detection and cut off client reporting to Anthropic.

# View patch status
aiw patch status

# Apply all patches (one-shot, recommended)
aiw patch apply --max-context-tokens 500000

# Restore original binary from backup
aiw patch restore

Patch Types:

  • File Patch: Modifies the Claude CLI binary on disk (persistent across restarts, auto-backup to .aiw-backup)
  • Memory Patch: Applied at runtime when file is unpatched (automatic, best-effort)

Supported Installations:

  • Native binary (ELF): ~/.local/share/claude/versions/<version> — GCS native binary only (Bun-packaged ELF, byte-level patch target)
  • ❌ npm installation (npm install -g @anthropic-ai/claude-code) is NOT supported — different build artifact, binary layout differs, patch regex not guaranteed to match

Supported Versions (cross-version via semantic regex / stable literals):

Version Linux x64 Linux arm64
2.1.195 ✅ ✅
2.1.196 ✅ ✅
2.1.197 ✅ ✅
2.1.198 ✅ ✅
2.1.199 ✅ ✅
2.1.201 ✅ ✅

CC 2.1.195+ native binary is published on GCS for linux-x64 + linux-arm64 only. macOS/Windows native binaries are no longer published since 2.1.195 (GCS 404). Historical 2.1.72-74 supported macOS arm64 / Windows x64.

Run aiw patch status to check if your version is supported. Patches use semantic regex (wildcarding minified variable names like jUt/kre, ke/Ie, dJ/dX, jJr/jXr) and stable literals (API paths, env var names), so they work across versions without a per-version signature database.

Six Patch Layers (anti-spy + capability unlock):

Patch What it does Mechanism
MaxContextTokens Unlocks default context window + autoCompact threshold (200000 → configurable, e.g. 500000) Regex var \w+=200000,\w+=200000[^;]*; (tolerates 4/5/6-element blocks)
AntiTelemetry Cuts off CC client reporting (/api/event_logging/v2/batch → 404), machineID/userID/device fingerprint never sent Literal batch→xxxxx (27B equal-length)
AntiSpy (escape hatch) Patches _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL check so fu() always returns true — one-shot silences 30+ call sites: relay-station identity reporting (custom_base_url flag), attribution header discrimination (cch=00000), tool-set filtering, ToolSearch gating, model-override gating Semantic regex if(\w+._CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL)return!0 → if(1) (55B equal-length)
AntiSpy (timezone) Blinds timezone detection — Intl.DateTimeFormat().resolvedOptions().timeZone always returns UTC, real timezone never leaks Literal → "UTC"/*...*/ (48B equal-length)
AntiPromptBias Eliminates Provider context prompt bias injected to 3rd-party users (if(dJ())n.push("**Provider context:**...") → if(0)) Semantic regex if(\w+()) wildcards function name (63B equal-length)
AntiAtis Prevents x-cc-atis tracking header injection — patches atis extract function to return void 0 (side effect of escape-hatch patch activates tMi(firstParty)&&gu() gate; patching the extractor neutralizes it) Semantic regex function \w+(){let e=\w+()?.atis;...} → function zzz(){return void 0} (80B equal-length)

Design note: The escape-hatch patch is based on CC's official escape-hatch env var _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL (parsed by st() as truthy for 1/true/yes/on). Patching the check itself (instead of injecting the env var) makes it permanent and covers more call sites. CC v2.1.198 removed the exposed Hsp() explicit probe (Asia/Shanghai timezone + base64 host list); identification fell back to Cot()/fu() host comparison, which the escape-hatch patch neutralizes.

Auto Mode (Automatic Failover)

# Auto mode tries CLI+Provider combinations in configured order, switches on failure
aiw auto "fix this bug"

# Configure CLI+Provider execution order
aiw config cli-order  # TUI to manage order (↑/↓ move, r reset, q save)

Configuration (~/.aiw/config.json):

{
  "auto_execution_order": [
    {"cli": "codex", "provider": "auto"},
    {"cli": "gemini", "provider": "auto"},
    {"cli": "claude", "provider": "glm"},
    {"cli": "claude", "provider": "local"},
    {"cli": "claude", "provider": "official"}
  ]
}
  • Same CLI can be configured with multiple providers (e.g., claude+glm → claude+local → claude+official)
  • Provider "auto" means use the CLI's default provider selection
  • Order can be fully customized via TUI or direct config editing

Role Injection (-r)

# Inject role prompt before task
aiw claude -r common "write a function"
aiw claude -r security "review this code"
aiw claude -r debugger "fix this bug"

# Built-in roles + custom roles in ~/.aiw/role/*.md
aiw roles list

Working Directory (-C)

# Start AI CLI in specific directory
aiw claude -C /path/to/project "implement feature"
aiw claude -r common -C ~/myproject "fix the bug"

Git Worktree (Isolated Execution)

AIW automatically creates a git worktree for isolated AI CLI execution.

# AIW automatically creates worktree for git repositories
aiw codex -C /path/to/repo "implement feature"

# After completion, AIW outputs:
# === AIW WORKTREE END ===
# Worktree: /tmp/aiw-worktree-a1b2c3d4
# Branch: main
# Commit: abc123def456

The AI CLI works in a temporary worktree at /tmp/aiw-worktree-<hash>, keeping your working directory clean. Worktree remains after completion for manual review — merge changes or delete as needed.

Transparent Parameter Forwarding

# All unknown flags forwarded to AI CLI
aiw claude -p glm --model sonnet --debug api "explain this"
aiw claude -r security --print --output-format json "review"

# Order: aiw flags (-r, -p, -C) → AI CLI flags → prompt

Combined Example

# Full example with all options
aiw claude -r common -p glm -C ~/project --model sonnet "implement REQ-001"
#          ^^^^^^^^  ^^^^^  ^^^^^^^^^^^  ^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^
#          role      provider  cwd        forwarded     prompt

Task Monitoring

# Show task status
aiw status

# Wait for all AI CLI tasks to complete
aiw wait

# Wait for specific process
aiw pwait <PID>

Patch Management

AIW includes a unified patching framework with five anti-spy / capability-unlock patches for Claude Code. All patches are cross-version stable (195-198) via semantic regex and stable literals — no per-version signature database needed.

Available Patches

Patch Description Scope
MaxContextTokens Configurable default context window + autoCompact threshold (default 500000) File + Memory
AntiTelemetry Cuts off client reporting (event_logging endpoint → 404), fingerprint never sent File + Memory
AntiSpy Blinds local detection: escape-hatch short-circuit (fu()→true) + timezone→UTC File + Memory
AntiPromptBias Eliminates Provider context prompt bias for 3rd-party users File + Memory

Patch Commands

# Show patch status
aiw patch status

# Apply all patches in one shot (recommended)
aiw patch apply --max-context-tokens 500000

# Apply individual patches
aiw patch set-max-tokens 500000        # max-token only
aiw patch disable-telemetry            # anti-telemetry only
aiw patch disable-spy                  # anti-spy only (escape-hatch + timezone)
aiw patch disable-prompt-bias          # anti-prompt-bias only

# Restore original binary from backup
aiw patch restore

Cross-Version Stability

Patches use two mechanisms to stay stable across CC versions (2.1.195-198):

  • Semantic regex: wildcard minified variable names (Oe/Pe config object, g7/F7/j7/dX condition function)
  • Stable literals: API paths (/api/event_logging/v2/batch), env var names (_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL), Intl.DateTimeFormat().resolvedOptions().timeZone

All patches follow the equal-length replacement iron law (byte-level equal length, no offset shifting). See SPEC/01-REQUIREMENTS.md REQ-025~028 and SPEC/CC-PROMPT-AUDIT.md for full technical details.

Update

# Update AIW itself and all installed AI CLI tools
aiw update

The update command checks and updates:

  • AIW: Updates via cargo install aiw --force if installed via cargo
  • Claude CLI: Uses native claude update (works for both npm and cargo installations)
  • Codex CLI: Updates via npm update -g openai-codex
  • Gemini CLI: Updates via npm update -g gemini-cli

Output example:

Checking for updates...
✅ AIW updated successfully!
✅ Claude CLI updated (2.1.71 → 2.1.72)
✅ Codex CLI already up-to-date
⚠️  Gemini CLI not installed

Configuration Files

File Purpose
~/.aiw/config.json AIW global configuration
~/.aiw/providers.json AI provider configurations
~/.aiw/role/*.md Custom role prompts

Global Configuration (~/.aiw/config.json)

{
  "user_roles_dir": "~/.claude/roles",
  "auto_execution_order": [
    {"cli": "codex", "provider": "auto"},
    {"cli": "gemini", "provider": "auto"},
    {"cli": "claude", "provider": "auto"}
  ]
}
Option Type Description
user_roles_dir string Custom directory for user roles (supports ~ expansion). If set, AIW will load user roles from this directory instead of ~/.aiw/role/
auto_execution_order array CLI+Provider combinations for auto mode. Each entry has cli (codex/gemini/claude) and provider (provider name or "auto"). Use aiw config cli-order TUI to manage

This allows you to manage all your roles in a single location, such as ~/.claude/roles/, and share them across different tools.

Available Roles

Run aiw roles list to see all built-in roles. Common ones:

Role Use case
common General-purpose coding (recommended as base)
frontend-standards Frontend development
database-standards Backend / database work
testing-standards Test code
security Security review
debugger Debugging
devops DevOps / infrastructure

Combine roles with commas: -r common,frontend-standards

License

MIT License - see LICENSE file for details.

GitHub | crates.io

For Developers

After cloning the repository, enable project-specific Git hooks:

git config core.hooksPath .githooks

This ensures commits follow project conventions (e.g., README must be updated when bumping version).

About

AIW (AI Warden) - Universal AI CLI management platform with intelligent process tracking, semantic memory, and provider coordination.

Resources

Readme
MIT license
Activity

Stars

13 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Used by

Contributors

Languages