axexec

Execution engine for AI coding agents. Translates abstract inputs to agent-specific formats, runs agents with credential/config isolation (not an OS sandbox), 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
• Credential/config isolation: Agents are pointed at temp directories instead of your local agent config/credential locations

axexec is not a security boundary. It does not restrict filesystem or network access; many adapters run in permissive non-interactive modes to avoid prompts. For real enforcement, run inside an external sandbox (container/VM).

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"

# Run with explicit credentials JSON (from axauth export)
axexec -a claude --credentials-file ./creds.json "Review this PR"

# 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"  # best-effort

# 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)
--cwd <path>               Working directory for the agent process
--credentials-file <path|-> Read credentials JSON from file (or '-' for stdin)
-p, --prompt <text>        Prompt text (alternative to positional argument)
-m, --model <model>        Model to use (agent-specific)
--provider <provider>      Provider for OpenCode (e.g., anthropic, openai, google, opencode)
--allow <perms>            Allow permissions (best-effort, comma-separated)
--deny <perms>             Deny permissions (best-effort, 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

| Agent | Package | API Key Env Var | | -------- | ------------------------- | ----------------------- | | claude | @anthropic-ai/claude-code | ANTHROPIC_API_KEY | | codex | @openai/codex | OPENAI_API_KEY | | gemini | @google/gemini-cli | GEMINI_API_KEY | | opencode | opencode-ai | AX_OPENCODE_CREDENTIALS | | copilot | @github/copilot | GITHUB_TOKEN |

OpenCode requires AX_OPENCODE_CREDENTIALS with provider-specific credentials (see CI/CD Credentials).

Event Stream

axexec normalizes all agent output to a standard event stream:

| Event Type | Description | | ------------------ | ------------------------------------ | | session.start | Agent session started | | session.complete | Agent session completed successfully | | session.error | Agent session failed | | agent.message | Text output from the agent | | agent.reasoning | Reasoning/thinking from the agent | | tool.call | Agent invoked a tool | | tool.result | Tool execution result |

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"

| Agent | Credential Env Var | | -------- | ----------------------- | | claude | AX_CLAUDE_CREDENTIALS | | codex | AX_CODEX_CREDENTIALS | | gemini | AX_GEMINI_CREDENTIALS | | opencode | AX_OPENCODE_CREDENTIALS | | copilot | AX_COPILOT_CREDENTIALS |

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, set AX_OPENCODE_CREDENTIALS with your credentials. The provider field must match your --provider flag:

# Anthropic
AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"anthropic","data":{"apiKey":"sk-ant-..."}}' \
  axexec -a opencode --provider anthropic -m claude-sonnet-4 "Hello"

# OpenAI (provider must be specified in credentials)
AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"openai","data":{"apiKey":"sk-..."}}' \
  axexec -a opencode --provider openai -m gpt-4.1 "Hello"

# OpenCode hosted models (provider must be "opencode")
AX_OPENCODE_CREDENTIALS='{"agent":"opencode","type":"api-key","provider":"opencode","data":{"apiKey":"..."}}' \
  axexec -a opencode --provider opencode -m glm-4.7-free "Hello"

Isolation

axexec provides credential/config 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

axexec is intentionally permissive and should not be treated as a sandbox:

• It does not enforce filesystem or network restrictions
• --allow / --deny is best-effort and may be ignored or weakened by adapter "YOLO" switches
• Agent-internal sandbox env vars (GEMINI_SANDBOX, SEATBELT_PROFILE) are excluded from subprocess environments
• For enforcement, run axexec inside an external sandbox (container/VM)

Agents are configured to avoid using your local agent config/credential locations:

• 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 with credential/config isolation and consume a normalized event stream. It translates credentials and permissions to agent-specific formats so your automation stays consistent across providers.

License

MIT