Unified CLI runner for AI coding agents with normalized event streaming
npm install axexecExecution 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.
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).
``bash`
npm install -g axexec
Install the agent CLIs you plan to use:
- Claude Code: npm install -g @anthropic-ai/claude-code (bin: claude)npm install -g @openai/codex
- Codex: (bin: codex)npm install -g @google/gemini-cli
- Gemini: (bin: gemini)npm install -g opencode-ai
- OpenCode: (bin: opencode)npm install -g @github/copilot
- Copilot CLI: (bin: copilot)
If a binary is not on your PATH, set an override:
`bash`
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
`bashRun 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"
Pipeline Examples
$3
`bash
axexec -a claude "Summarize the change" | cut -f2 | sort | uniq -c | sort -rn
`$3
`bash
axexec -a claude -f jsonl "Audit dependencies" | jq 'select(.type == "tool.call")'
`$3
`bash
axexec --list-agents | tail -n +2 | awk -F'\t' '$3 ~ /openai/ {print $1}'
`Options
`
-a, --agent Agent to use (claude, codex, gemini, opencode, copilot)
--cwd Working directory for the agent process
--credentials-file Read credentials JSON from file (or '-' for stdin)
-p, --prompt Prompt text (alternative to positional argument)
-m, --model Model to use (agent-specific)
--provider Provider for OpenCode (e.g., anthropic, openai, google, opencode)
--allow Allow permissions (best-effort, comma-separated)
--deny Deny permissions (best-effort, comma-separated)
-f, --format Output format: jsonl, tsv (default: tsv, truncated on TTY)
--raw-log 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
$3
For CI/CD pipelines, credentials can be passed via environment variables:
`bash
Export credentials locally (one-time setup)
axauth export --agent claude --output creds.json --no-passwordStore 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 |
$3
You can also use standard environment variables directly:
`bash
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:`bash
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 filesAgent Rule
Add to your
CLAUDE.md or AGENTS.md:`markdown
Rule:
axexec UsageRun
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.
``MIT