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

``bash
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)

$3

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
`

Usage

`bash


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

$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-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 |

$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 files

Agent Rule

Add to your CLAUDE.md or AGENTS.md:

`markdown


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