axexec

Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents in complete isolation, and normalizes output to a standard event stream.

What axexec Does

axexec is the translation layer between high-level tooling and agent-specific details:

• Input translation: Credentials → agent-specific files, permissions → config files, model → CLI flags
• Output normalization: Claude JSONL, Codex items, Gemini events, OpenCode SSE → unified AxexecEvent stream
• Complete isolation: Agents run in temp directories with no access to user config or global credentials

Installation

npm install -g axexec

Requirements

Install the agent CLIs you plan to use:

• Claude Code: npm install -g @anthropic-ai/claude-code (bin: claude)
• Codex: npm install -g @openai/codex (bin: codex)
• Gemini: npm install -g @google/gemini-cli (bin: gemini)
• OpenCode: npm install -g opencode-ai (bin: opencode)
• Copilot CLI: npm install -g @github/copilot (bin: copilot)

Custom Paths

If a binary is not on your PATH, set an override:

export AXEXEC_CLAUDE_PATH=/opt/claude/bin/claude
export AXEXEC_CODEX_PATH=/opt/codex/bin/codex
export AXEXEC_GEMINI_PATH=/opt/gemini/bin/gemini
export AXEXEC_OPENCODE_PATH=/opt/opencode/bin/opencode
export AXEXEC_COPILOT_PATH=/opt/copilot/bin/copilot

Usage

# Run a prompt with an agent
axexec --agent claude "Add error handling to auth.ts"
axexec -a codex "Fix the bug in main.ts"
axexec -a gemini "Refactor the utils module"
axexec -a opencode "Add logging"
axexec -a copilot "Write tests"

# Specify a model
axexec -a claude --model opus "Review this PR"
axexec -a gemini --model gemini-2.5-pro "Refactor utils"

# Set permissions
axexec -a claude --allow 'read,glob,bash:git *' "Check git history"

# Output normalized JSONL event stream
axexec -a claude -f jsonl "Add tests" | jq 'select(.type == "tool.call")'

# List available agents
axexec --list-agents

Pipeline Examples

Count event types

axexec -a claude "Summarize the change" | cut -f2 | sort | uniq -c | sort -rn

Filter tool calls

axexec -a claude -f jsonl "Audit dependencies" | jq 'select(.type == "tool.call")'

Filter available agents by package

axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'

Options

-a, --agent <id>           Agent to use (claude, codex, gemini, opencode, copilot)
-p, --prompt <text>        Prompt text (alternative to positional argument)
-m, --model <model>        Model to use (agent-specific)
--allow <perms>            Permission rules to allow (comma-separated)
--deny <perms>             Permission rules to deny (comma-separated)
-f, --format <fmt>         Output format: jsonl, tsv (default: tsv, truncated on TTY)
--raw-log <file>           Write raw agent output to file
--debug                    Enable debug mode (logs unknown events)
--verbose                  Show agent stderr output
--preserve-github-sha      Keep GITHUB_SHA env var (Gemini excludes by default)
--list-agents              List available agents
-V, --version              Show version number
--help                     Show help

Supported Agents

(†) OpenCode supports multiple providers via ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY.

Event Stream

axexec normalizes all agent output to a standard event stream:

CI/CD Usage

Using Credential Environment Variables

For CI/CD pipelines, credentials can be passed via environment variables:

# Export credentials locally (one-time setup)
axauth export --agent claude --output creds.json --no-password

# Store as repository secret (e.g., AX_CLAUDE_CREDENTIALS)

# axexec auto-detects and installs credentials to temp directory
axexec --agent claude --prompt "Review this PR"

Using Standard API Keys

You can also use standard environment variables directly:

ANTHROPIC_API_KEY=sk-... axexec -a claude "Review code"
OPENAI_API_KEY=sk-... axexec -a codex "Fix bug"
GEMINI_API_KEY=... axexec -a gemini "Refactor"
GITHUB_TOKEN=ghp_... axexec -a copilot "Write tests"

For Claude, CLAUDE_CODE_OAUTH_TOKEN (generated via claude setup-token) also works. For Copilot, token precedence is COPILOT_GITHUB_TOKEN, then GH_TOKEN, then GITHUB_TOKEN.

For OpenCode, if multiple provider API keys are set, axexec uses the model prefix (anthropic/..., openai/..., google/...) to disambiguate. When multiple keys are present and no provider prefix is available, set AX_OPENCODE_CREDENTIALS explicitly. This value must be a JSON-encoded Credentials object (not a raw API key), for example:

{
  "agent": "opencode",
  "type": "api-key",
  "provider": "openai",
  "data": { "apiKey": "sk-..." }
}

Isolation

axexec provides complete environment isolation:

1. Creates a temp directory for each session
2. Installs credentials to the temp directory
3. Generates agent-specific config files in the temp directory
4. Sets environment variables to point agents at the temp directory
5. Cleans up the temp directory after execution

Codex runs with --dangerously-bypass-approvals-and-sandbox, so --allow / --deny do not constrain Codex. Run axexec inside an external sandbox if you need enforcement.

Agents never access:

• User's home directory config (~/.claude, ~/.codex, ~/.gemini)
• System keychain or credential managers
• Global configuration files

Agent Rule

Add to your CLAUDE.md or AGENTS.md:

# Rule: `axexec` Usage

Run `npx -y axexec --help` to learn available options.

Use `axexec` when you need to run a supported agent in a fully isolated environment and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.

License

MIT