Skip to main content
The axon compile command transforms AXON source code into AXON IR (Intermediate Representation), a JSON-serializable format optimized for execution by different LLM backends.

​
Synopsis

axon compile <file.axon> [options]

​
Description

Runs the complete compilation pipeline:
  1. Lexer — Tokenize source code
  2. Parser — Build Abstract Syntax Tree
  3. Type Checker — Semantic validation
  4. IR Generator — Generate intermediate representation
  5. Serialization — Output as JSON
The resulting IR JSON can be:
  • Saved for later execution
  • Inspected for debugging
  • Distributed independently of source code
  • Executed on any supported backend

​
Arguments

​
file
string
required
Path to the .axon source file to compile

​
Options

​
--backend
string
default:"anthropic"
Target backend for compilation. Affects prompt structure and optimization.Choices: anthropic, openai, gemini, ollamaShort form: -b
​
--output
string
Custom output path for the IR JSON file.Default: <filename>.ir.jsonShort form: -o
​
--stdout
flag
Print IR JSON to stdout instead of writing to a file. Useful for piping to other tools.

​
Exit Codes

CodeMeaning
0Success — IR generated and saved
1Compilation error (lexer, parser, type checker, or IR generation)
2I/O error (file not found or write failure)

​
Output Format

​
File Output (Default)

$ axon compile contract_analyzer.axon
✓ Compiled → contract_analyzer.ir.json
The IR file is saved alongside the source file with .ir.json extension.

​
Stdout Output

$ axon compile program.axon --stdout
{
  "_meta": {
    "source": "program.axon",
    "backend": "anthropic",
    "axon_version": "0.4.0a0"
  },
  "declarations": [
    {
      "type": "persona",
      "name": "LegalExpert",
      "attributes": { ... }
    }
  ]
}

​
Error Output

$ axon compile broken.axon
✗ broken.axon: Unexpected token 'END' at line 15

​
IR JSON Structure

The compiled IR includes:
  • Metadata: Source file, backend, AXON version
  • Declarations: All top-level constructs (personas, flows, anchors, etc.)
  • Type Information: Resolved types and epistemic annotations
  • Execution Graph: Flow dependencies and data flow

​
Examples

​
Basic Compilation

axon compile program.axon
Compile using default settings (Anthropic backend, auto-named output).

​
Target Specific Backend

axon compile program.axon --backend openai
axon compile program.axon -b gemini
Optimize IR for specific LLM providers.

​
Custom Output Path

axon compile program.axon --output dist/program.json
axon compile program.axon -o build/compiled.ir.json
Save IR to a specific location.

​
Pipe to Other Tools

# Pretty-print IR
axon compile program.axon --stdout | jq .

# Save to custom location
axon compile program.axon --stdout > dist/$(date +%Y%m%d).ir.json

# Count declarations
axon compile program.axon --stdout | jq '.declarations | length'

​
Multiple Backends

# Compile for all backends
for backend in anthropic openai gemini ollama; do
  axon compile program.axon -b $backend -o dist/program.$backend.ir.json
done

​
CI/CD Integration

#!/bin/bash
# Build script

set -e  # Exit on error

# Compile all source files
for file in src/*.axon; do
  echo "Compiling $file..."
  axon compile "$file" -b anthropic -o "dist/$(basename $file .axon).ir.json"
done

echo "Build complete: $(ls dist/*.ir.json | wc -l) files"

​
Backend Differences

​
Anthropic (Claude)

Optimized for:
  • Extended context windows
  • System prompts with persona fusion
  • Chain-of-thought reasoning
axon compile program.axon --backend anthropic

​
OpenAI (GPT)

Optimized for:
  • Structured outputs
  • Function calling
  • JSON mode
axon compile program.axon --backend openai

​
Gemini

Optimized for:
  • Multimodal inputs
  • Safety settings
  • Grounding with Google Search
axon compile program.axon --backend gemini

​
Ollama

Optimized for:
  • Local execution
  • Privacy-focused deployments
  • Custom model configurations
axon compile program.axon --backend ollama

​
IR Inspection

Use jq to inspect compiled IR: 
# List all declarations
axon compile program.axon --stdout | jq '.declarations[].name'

# Extract metadata
axon compile program.axon --stdout | jq '._meta'

# Count personas
axon compile program.axon --stdout | \
  jq '[.declarations[] | select(.type == "persona")] | length'

# Find all flows
axon compile program.axon --stdout | \
  jq '.declarations[] | select(.type == "flow") | .name'

​
Troubleshooting

​
IR Generation Failed

✗ IR generation failed: Invalid flow structure
Cause: AST is valid but cannot be converted to executable IR. Solution: Check for unsupported language features or report a compiler bug.

​
Write Permission Error

Solution: Ensure write access to the output directory: 
mkdir -p dist
chmod u+w dist
axon compile program.axon -o dist/output.ir.json

​
Backend Not Found

✗ Backend error: Unknown backend 'invalid'
Solution: Use a supported backend name: 
axon compile program.axon --backend anthropic  # ✓ Valid

check

Validate before compiling

run

Compile and execute in one step

​
Performance Notes

  • Compilation is CPU-bound (no API calls)
  • Typical compile times: 50-500ms depending on program size
  • IR files are typically 2-5x larger than source files
  • Use --stdout to avoid disk I/O overhead

Build docs developers (and LLMs) love

Get started for freeTalk to us