___________  __     _________________________________
___    |_  |/ /     __  ____/_  __ \__  __ \__  ____/
__  /| |_    /_______  /    _  / / /_  / / /_  __/
_  ___ |    |_/_____/ /___  / /_/ /_  /_/ /_  /___
/_/  |_/_/|_|       \____/  \____/ /_____/ /_____/

AI coding runtime for teams that need controlled execution, durable context, and embeddable agent workflows, not just code suggestions.

AX Code is an AI execution runtime for software development. It combines agents, tool execution, provider routing, session state, and configurable isolation into one system that can run in the terminal, inside VS Code, through the SDK, or as a headless service.

• Let agents work in real repositories with explicit tools, sandbox modes, and permission boundaries
• Keep context alive with persistent sessions, replay, export, and project instructions in AGENTS.md
• Move between hosted and local model providers without changing the developer workflow
• Reuse one runtime across TUI, CLI, SDK, VS Code, headless server mode, and internal automation
• Extend the runtime with MCP servers, plugins, and custom SDK tools instead of rebuilding orchestration

Built by DEFAI Digital.

---

Get Started in 60 Seconds

Install

# Homebrew (macOS / Linux)
brew install defai-digital/ax-code/ax-code

# npm (any platform)
npm i -g @defai.digital/ax-code

Verify

ax-code doctor

Look for the Runtime line:

Output	Meaning
Runtime: Bun X.Y.Z (compiled)	Default Homebrew/npm install — compiled binary
Runtime: Bun X.Y.Z (bun-bundled)	ax-code-source compatibility package
Runtime: Bun X.Y.Z (source)	Local checkout via pnpm setup:cli

Run

# Set any provider key (pick one)
export ANTHROPIC_API_KEY="your-key"              # Claude
export GOOGLE_GENERATIVE_AI_API_KEY="your-key"   # Gemini
export XAI_API_KEY="your-key"                    # Grok
export OPENAI_API_KEY="your-key"                 # GPT

# Launch
ax-code

That's it. No project setup or config file is required. Run ax-code, then use /connect inside the TUI to add or switch providers.

Update

ax-code upgrade and package-manager update commands apply to the compiled runtime shipped by the default package.

ax-code upgrade
brew upgrade ax-code
npm update -g @defai.digital/ax-code   # follows your installed dist-tag

Distribution note

The supported user install path now ships the compiled binary under the normal ax-code package/formula. The source+bun launcher remains available as the ax-code-source compatibility channel for diagnosis or fallback.

From Source (contributors)

git clone https://github.com/defai-digital/ax-code.git
cd ax-code && pnpm install && pnpm run setup:cli

Requires pnpm v9.15.9+ and Bun matching the root package.json engine (^1.3.12 today). setup:cli installs a launcher for the same bundled runtime used by npm and Homebrew. ax-code doctor should report Runtime: Bun X.Y.Z (compiled).

Refresh the local bundled runtime after code changes:

pnpm --dir packages/ax-code run build -- --single
pnpm run setup:cli -- --rebuild
ax-code doctor

For contributor-only source debugging, install the checkout-bound launcher explicitly:

pnpm run setup:cli -- --source

---

Why AX Code

Most AI coding tools optimize for a chat loop. AX Code is built as a runtime you can actually operate across repositories, teams, and integration surfaces.

• Control what the agent can do: every action goes through explicit tools, permission rules, and isolation modes such as full-access, workspace-write, or read-only.
• Preserve work over time: sessions can be resumed, forked, compacted, exported, and replayed instead of disappearing with a chat tab.
• Keep provider choice open: switch between cloud and local model backends without changing the surrounding workflow.
• Share project knowledge with the repo: AGENTS.md keeps conventions, guardrails, and collaboration defaults close to the code.
• Build on the same runtime everywhere: use the terminal, VS Code, one-shot CLI, SDK, CI jobs, or internal platforms without inventing separate agent stacks.

AX Code is not just a chat UI. It is the runtime layer behind agent selection, tool orchestration, session persistence, and policy boundaries.

When It Fits

AX Code is a strong fit when you need one or more of these:

• Large or messy repositories where uncontrolled tool use is risky
• Team workflows that need repeatability, reviewability, or policy boundaries
• Provider choice across hosted and local model backends
• Embeddable agent workflows through a TypeScript SDK or headless server
• Repository-specific context that can live with the code in AGENTS.md

Use It Your Way

Surface	Best for	Entry point
TUI	Interactive repo work	ax-code
One-shot CLI	Quick tasks and scripts	ax-code run "review the auth flow"
Server mode	CI, bots, and internal platforms	ax-code serve
TypeScript SDK	Embedding ax-code in applications	packages/sdk/js/README.md
VS Code	Editor-native workflow	packages/integration-vscode/README.md

Core Workflow

1. Connect a provider with environment variables or ax-code providers login.
2. Launch ax-code and use /connect if you want to switch models from the TUI.
3. Run ax-code init so AGENTS.md captures project-specific instructions and conventions.
4. Turn on sandboxing with --sandbox workspace-write or /sandbox when you want bounded execution.
5. Run ax-code index on larger repos for faster semantic and code-intelligence workflows.

Documentation

• Start Here: understand what AX Code is, where the value comes from, and which docs to read next
• Documentation Hub: guides, architecture, specs, and reference docs
• Sandbox Mode: isolation modes, protected paths, and network controls
• Autonomous Mode: unattended execution behavior and safeguards
• Auto-Route: keyword-based specialist routing and optional fast-model complexity routing
• Semantic Layer: provenance and replay boundaries for graph and LSP-backed answers

Common Commands

ax-code
ax-code run "debug why the build is failing"
ax-code providers login
ax-code models
ax-code init
ax-code index
ax-code mcp add
ax-code serve
ax-code doctor

Security and Operations

AX Code includes configurable isolation modes, protected paths for .git and .ax-code in sandboxed runs, encrypted provider and MCP credentials at rest, and localhost-only server defaults. See SECURITY.md for the threat model and docs/sandbox.md for isolation behavior and configuration.

Project Notes

AX Code combines ideas from ax-cli and OpenCode into the developer-facing runtime of the broader AutomatosX ecosystem.

Community

Report bugs, feature requests, and questions through GitHub Issues. See CONTRIBUTING.md for the current contribution policy and Discord for community discussion.

License

MIT — Copyright (c) 2025 DEFAI Private Limited. Portions derived from OpenCode, Copyright (c) 2025 opencode.