Introduction to Arxo

Introduction

Arxo is a comprehensive architecture analysis tool that helps you understand, measure, and enforce architectural patterns in your codebase. It supports TypeScript/JavaScript and Python from a single binary.

What Is Arxo?

Arxo parses your source code, builds dependency and call graphs, and runs published metrics — today that means Agent Architecture and OpenClaw Architecture — to give you scores, findings, and policy guardrails for agent systems and OpenClaw-based skill platforms.

Agent Architecture

Reliability, governance, safety, and coordination for multi-agent and tool-calling systems.

OpenClaw Architecture

Config security, skill governance, observability, and supply chain for OpenClaw skill ecosystems.

Key Features

Language Support

Arxo supports two language ecosystems:

• TypeScript / JavaScript — React, Next.js, Node.js, Bun
• Python — Django, Flask, FastAPI

Published Metrics

Only the following metrics are included in the public build:

Metric	What it covers
agent_architecture	Agent and orchestration: reliability, governance, safety, coordination (scores and findings).
openclaw_architecture	OpenClaw platforms: config security, skill governance, observability, supply chain (scores and findings).

Policy Enforcement

Define architectural rules in YAML and enforce them in CI/CD to prevent regressions:

policy:
  invariants:
    - metric: agent_architecture.overall_agent_health
      op: ">="
      value: 70
      message: "Agent architecture health at least 70"
    - metric: openclaw_architecture.overall_openclaw_health
      op: ">="
      value: 60
      message: "OpenClaw architecture health at least 60"

Multiple Output Formats

Format	Use case
Console	Human-readable terminal output with pass/fail indicators
JSON	Machine-readable for CI/CD pipelines and custom tooling
HTML	Interactive web reports with dependency graph visualization

Fast and Incremental

• Parallel computation — Metrics run concurrently across available cores.
• Cached results — Repeated analysis returns instantly until the cache TTL expires.
• Config-based — Use a config file or defaults to run agent_architecture and openclaw_architecture.

Quick Start

Installation

Install the pre-built binary from GitHub Releases, or use npm:

npm install -g arxo

See Installation for other options (Docker, direct download).

First Analysis

# Agent and OpenClaw architecture (published metrics)
arxo analyze

Sample Output

Analyzing project...
  Parsed 247 files
  Built dependency and call graph

Results:
  agent_architecture.overall_agent_health: 72    ✓
  agent_architecture.governance_readiness: 85   ✓
  openclaw_architecture.overall_openclaw_health: 68   ✓

No policy violations

How It Works

1. Compute Metrics

   Run the published metrics: agent_architecture (reliability, governance, safety, coordination) and openclaw_architecture (config, skill governance, observability, supply chain).

2. Evaluate Policies

   Check each policy invariant against computed metric values. Report violations with expected vs. actual values.

3. Report

   Output results in your chosen format — Console, JSON, or HTML — and exit with a non-zero code if any invariant fails.

Core Concepts

Metrics (published)

The public build includes two metrics:

• agent_architecture — Scores and findings for agent and orchestration code: reliability (loop guards, retries, observability), governance (tool policy, validation), safety (sandbox, MCP, A2A), and coordination (routing, fanout, state).
• openclaw_architecture — Scores and findings for OpenClaw-based skill platforms: config security, skill governance, observability, and supply chain (e.g. ClawHub provenance, metadata validation).

Deep links:

• OpenClaw Architecture
• OpenClaw Scoring and Keys
• OpenClaw Keys and possible values
• OpenClaw Remediation Playbook

Each metric emits numeric scores (e.g. 0–100) and optional findings (warnings with evidence).

Policies

Declarative invariants that must hold. Each invariant references a metric value, a comparison operator, and a threshold:

invariants:
  - metric: agent_architecture.overall_agent_health
    op: ">="
    value: 70
  - metric: openclaw_architecture.overall_openclaw_health
    op: ">="
    value: 60

When an invariant fails, the CLI exits with a non-zero code and reports the violation — making it easy to use as a CI gate.

Running analysis

Run arxo analyze to execute the published metrics (agent_architecture and openclaw_architecture). Use an arxo.yaml config file to customize which metrics run and policy thresholds; see Configuration.

Use Cases

Development

• Pre-commit hooks — Run arxo analyze to gate on agent and OpenClaw architecture health.
• IDE integration — The VS Code extension shows violations inline and provides a metrics dashboard.
• MCP for AI assistants — The MCP server lets Cursor, Claude, and other AI tools call architecture analysis directly.

CI/CD

• Pull request gates — Enforce policies automatically with --fail-fast.
• Reports — Export JSON or HTML reports for CI artifacts and review.

Architecture Review

• Agent systems — Score reliability, governance, safety, and coordination; use findings to fix gaps.
• OpenClaw platforms — Score config security, skill governance, observability, and supply chain; improve over time with policy gates.

Example Scenarios

Gate agent architecture health

arxo.yaml

policy:
  invariants:
    - metric: agent_architecture.overall_agent_health
      op: ">="
      value: 70
      message: "Agent architecture health at least 70"

arxo analyze --fail-fast

Gate OpenClaw architecture health

policy:
  invariants:
    - metric: openclaw_architecture.overall_openclaw_health
      op: ">="
      value: 60
      message: "OpenClaw architecture health at least 60"

arxo analyze --fail-fast

Next Steps

Installation

Install Arxo with pre-built binaries.

Quick Start

Run your first analysis in under a minute.

Configuration

Set up metrics, policies, and output formats.

Metrics Reference

Browse available metrics and interpretation guides.

Integration

• CI/CD Integration — Automate checks in GitHub Actions, GitLab CI, and Jenkins.
• VS Code Extension — Real-time analysis, inline violations, and metrics dashboard.
• MCP Server — Architecture analysis for AI assistants (Cursor, Claude Desktop).

Guides

• Policy Examples — Real-world policy configurations.
• Output Formats — Console, JSON, and HTML.
• Troubleshooting — Common issues and solutions.

Community and Support

• GitHub: github.com/arxohq/arxo
• Issues: github.com/arxohq/arxo/issues
• Discussions: github.com/arxohq/arxo/discussions