Configuration Reference

Complete reference for axis.config.json and scenario files.

axis.config.json

AXIS is configured via an axis.config.json file in your project root. 

{
  "scenarios": "./scenarios",
  "agents": [
    "claude-code",
    {
      "adapter": "gemini",
      "model": "gemini-2.5-pro",
      "scenarios": ["cms/*"],
      "flags": { "yolo": true }
    }
  ],
  "defaults": {
    "concurrency": 4,
    "scoring_weights": {
      "goal_achievement": 0.4,
      "environment": 0.2,
      "service": 0.2,
      "agent": 0.2
    }
  },
  "env": ["ANTHROPIC_API_KEY", "GEMINI_API_KEY"],
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  },
  "skills": ["./skills/deploy"],
  "adapters": {
    "my-agent": "./adapters/my-agent.ts"
  }
}

Top-Level Fields

Field Type Description
scenarios string Path to the scenarios directory (required).
agents (string | AgentConfig)[] Adapter names or full agent configurations (required).
defaults object Default concurrency and scoring weights.
env string[] Environment variables to pass through to agent processes.
mcp_servers object MCP servers available to all agents.
skills string[] Skills available to all agents (local paths, GitHub shorthand, or URLs).
adapters object Custom adapter module paths, keyed by adapter name.

Agent Configuration

Agents can be specified as a simple string (adapter name) or a full configuration object.

Field Type Description
adapter string Adapter type (required): claude-code, codex, gemini, etc.
model string Model override passed to the agent CLI.
scenarios string[] Subset of scenarios to run (supports glob patterns like cms/*).
skills string[] Agent-specific skills (merged with top-level skills).
flags object CLI flags passed to the agent (for example, {"full-auto": true}).
command string Custom CLI command (for custom adapters).

Scoring Weights

Override the default dimension weights under defaults.scoring_weights. Values must sum to 1.0. 

{
  "defaults": {
    "scoring_weights": {
      "goal_achievement": 0.4,
      "environment": 0.2,
      "service": 0.2,
      "agent": 0.2
    }
  }
}

MCP Servers

Configure Model Context Protocol servers that are automatically wired into each agent environment. AXIS supports both stdio (local process) and HTTP (remote endpoint) servers. 

{
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": { "LOG_LEVEL": "info" }
    },
    "remote-api": {
      "type": "http",
      "url": "https://mcp.example.com/tools",
      "headers": { "Authorization": "Bearer ${TOKEN}" }
    }
  }
}

Each adapter writes MCP configuration in its native format before spawning the agent.

  • Claude Code: .mcp.json in workspace root.
  • Codex: config.toml in CODEX_HOME.
  • Gemini: settings.json in GEMINI_CLI_HOME.

Skills

Skills extend agent capabilities with reusable instruction sets. Specify them at the top level (shared), per agent, or per scenario. 

{
  "skills": [
    "./skills/deploy",
    "netlify/axis-skill-deploy",
    "https://github.com/owner/repo"
  ]
}
  • Local paths: Relative to the config file.
  • GitHub shorthand: owner/repo format.
  • Full URLs: GitHub repository URLs.

Remote skills are cached in .axis/skills-cache/. Use --refresh-skills to force re-clone.

Environment Variables

The env field lists additional environment variables to pass through to agent processes. The following are always passed through by default:

  • ANTHROPIC_API_KEY, CODEX_API_KEY, GEMINI_API_KEY
  • System essentials: PATH, USER, SHELL, LANG, TERM, TMPDIR

Scenarios

Scenarios are JSON files in the configured scenarios directory. The filename (without .json) becomes the scenario key. Nested directories create namespaced keys.

  • scenarios/hello-world.json maps to key hello-world.
  • scenarios/cms/create-post.json maps to key cms/create-post.

Scenario Schema

{
  "name": "Debug and fix a broken script",
  "prompt": "There is a JavaScript file at /tmp/app/add.js that has a bug. Find it, fix it, and verify.",
  "rubric": [
    { "check": "Agent identified the bug", "weight": 0.3 },
    { "check": "Agent fixed the bug", "weight": 0.4 },
    { "check": "Agent verified the fix", "weight": 0.3 }
  ],
  "setup": [
    { "action": "run_script", "command": "mkdir -p /tmp/app" },
    { "action": "run_script", "command": "echo 'function add(a,b) { return a-b; }' > /tmp/app/add.js" }
  ],
  "teardown": [
    { "action": "run_script", "command": "rm -rf /tmp/app" }
  ],
  "agents": ["claude-code"]
}
Field Type Description
name string Human-readable scenario title (required).
prompt string Task description sent to the agent (required).
rubric string | object[] Success criteria: a string or array of checks with optional weights (required).
setup object[] Lifecycle actions run before the agent.
teardown object[] Lifecycle actions run after scoring.
agents string[] Override which agents run this scenario.
skills string[] Scenario-specific skills.
Setup and Teardown

Lifecycle actions run sequentially with a 30-second timeout per action. Setup failures abort the job. Teardown failures are logged but do not block subsequent jobs.