analyze_architecture

analyze_architecture

Run architecture analysis on your project. Returns agent architecture metrics (reliability, governance, safety, coordination for agent and LLM-powered code) and OpenClaw architecture metrics (config security, skill governance, observability, supply chain). The response includes composite scores, per-detector findings with evidence (file, line, reason), and recommendations.

Note

This tool supports caching. Results are cached for 5 minutes (configurable via --cache-ttl) when called with the same project path and config.

Parameters

Parameter	Type	Required	Description
project_path	string	Yes	Absolute or relative path to the project root directory
config_path	string	No	Path to a custom arxo.yaml configuration file
output_format	string	No	json (default) or openarch

What it runs

The tool runs the published metrics:

• agent_architecture — Composite scores (overall agent health, reliability, governance readiness, safety protocol score, coordination maturity), per-detector findings (loop guards, schema validation, observability, MCP governance) with file, line, and recommendation
• openclaw_architecture — Config security, skill governance, observability, and supply chain scores and findings

Response

Returns a JSON summary with computed metrics, findings, and any policy violations.

Response schema (summary)

{
  "results": [
    {
      "id": "agent_architecture",
      "version": "string",
      "data": [ { "key": "string", "value": { "kind": "number", "v": 0.0 } } ],
      "findings": [ ]
    },
    {
      "id": "openclaw_architecture",
      "version": "string",
      "data": [ ],
      "findings": [ ]
    }
  ],
  "violations": [ ],
  "violations_count": 0,
  "ui_schemas": { }
}

results[].data includes entries such as agent_architecture.overall_agent_health, openclaw_architecture.overall_openclaw_health, and per-detector gap scores. findings list evidence with file, line, and recommendation.

OpenClaw Reference

• OpenClaw Architecture
• OpenClaw Scoring and Keys
• OpenClaw Policy and CI Gates
• OpenClaw Keys and possible values

Example

Request:

{
  "project_path": "."
}

Response (summary):

{
  "results": [
    {
      "id": "agent_architecture",
      "version": "1.0.0",
      "data": [
        { "key": "agent_architecture.overall_agent_health", "value": { "kind": "number", "v": 0.72 } },
        { "key": "agent_architecture.agent_reliability_score", "value": { "kind": "number", "v": 75.0 } }
      ],
      "findings": [
        {
          "rule_id": "arxo/agent-loop-guard-absence",
          "severity": "warning",
          "evidence": [ { "file": "src/agent.py", "line": 42, "reason": "No max_steps or timeout" } ],
          "recommendation": "Add step or time limit to prevent runaway loops."
        }
      ]
    }
  ],
  "violations": [],
  "violations_count": 0
}

Error cases

Error	Cause	Solution
missing required parameter: project_path	project_path not provided	Include project_path in request
No such file or directory	Invalid project path	Verify path exists and is accessible
Failed to load config	Invalid YAML in config file	Check YAML syntax in config_path

Performance

• Caching: Results are cached by (project_path, config). Repeated calls with the same parameters return cached results until the TTL expires.
• Cache TTL: Default 300 seconds (5 minutes). Configure via --cache-ttl in the MCP server args.

Related tools

• arxo_config_help — Config schema and examples
• arxo_config_validate — Validate arxo.yaml before analysis
• arxo_config_suggest — Generate a suggested config for the project

CLI equivalent

arxo analyze