Interactive Mode

Interactive mode provides a guided, prompt-based workflow for running architecture analysis.

Overview

Instead of memorizing flags and options, interactive mode asks you questions:

arxo analyze --interactive

What it prompts for:

Project path — Directory to analyze
Metrics — Agent and OpenClaw architecture (default)
Output file — Where to save results (optional)

Getting Started

Basic Interactive Analysis

arxo analyze --interactive

Example session:

🔍 Arxo Interactive Analysis

? Select project directory:
  > . (current directory)
    Browse...
    Enter path manually

? Run agent and OpenClaw architecture?
  > Yes (default)

? Save report to file?
  > No, display in terminal
    Yes, save as JSON
    Yes, save as HTML

🚀 Starting analysis...
✓ Agent and OpenClaw architecture analyzed

📊 Results:
...

Features

1. Smart Path Selection

Interactive mode offers multiple ways to select the project:

Option 1: Current Directory

? Select project directory:
  > . (current directory)

Option 2: Browse Filesystem

? Select project directory:
    . (current directory)
  > Browse...

Opens a file browser to select a directory.

Option 3: Manual Entry

? Select project directory:
    . (current directory)
    Browse...
  > Enter path manually

? Enter project path: /path/to/my-app

2. Metrics

The default run includes Agent Architecture (reliability, governance, safety, coordination) and OpenClaw Architecture (config security, skill governance, observability, supply chain).

3. Output Format Selection

Choose how to view results:

? Save report to file?
  > No, display in terminal
    Yes, save as JSON  → report.json
    Yes, save as HTML  → report.html

Custom filename:

? Save report to file?
    No, display in terminal
  > Yes, save as JSON

? Output filename: my-analysis.json

4. Configuration Detection

If .arxo.yaml exists in the project:

✓ Found configuration: .arxo.yaml

? Use existing config or run defaults?
  > Use .arxo.yaml config
    Run defaults (agent + OpenClaw)

Use Cases

1. First-Time User

Scenario: New to Arxo, want to explore

arxo analyze --interactive

Select current directory (.)
Run agent and OpenClaw architecture (default)
Display in terminal
Review results

2. Evaluating a New Project

Scenario: Downloaded a project, want to assess agent architecture

cd ~/Downloads/new-project
arxo analyze --interactive

Current directory is auto-selected
Run default metrics (agent + OpenClaw)
Save as HTML to share with team

3. No Config File

Scenario: Quick analysis without creating config

# Instead of:
arxo analyze --format json --output report.json

# Use interactive mode:
arxo analyze --interactive

Faster for one-off analysis.

4. Teaching/Demos

Scenario: Teaching Arxo to team members

Interactive mode is self-documenting:

Runs agent and OpenClaw architecture by default
Guides through output options

Keyboard Shortcuts

During interactive prompts:

Key	Action
`↑` / `↓`	Navigate options
`Enter`	Select option
`Space`	Toggle checkbox (multi-select)
`Ctrl+C`	Cancel and exit
`Ctrl+D`	Cancel and exit
`/`	Search/filter (in long lists)

Advanced Usage

Skip Prompts with Flags

You can pre-fill some answers:

# Pre-select path, prompt for output
arxo analyze --interactive --path ./my-project

# Pre-select everything (no prompts)
arxo analyze --path ./my-project --output report.json

When does interactive mode activate?

Explicit: --interactive flag
Implicit: Missing required arguments (not in all versions)

Configuration Wizard

Interactive mode can generate config files:

arxo init --interactive

Prompts:

Project type (TypeScript or Python)
Analysis goals (CI, security, coupling, etc.)
Policy strictness (Strict, Moderate, Lenient)
Output preferences

Generates: .arxo.yaml with recommended settings

Comparison with CLI Flags

Task	Interactive Mode	CLI Flags
New users	✅ Beginner-friendly	❌ Must learn flags
Speed	⏱️ Slower (prompts)	⚡ Faster (direct)
Discoverability	✅ Shows all options	❌ Must read docs
Automation	❌ Not scriptable	✅ Fully scriptable
Memory	✅ No flags to remember	❌ Must remember flags
CI/CD	❌ Not suitable	✅ Perfect for CI

Recommendation:

Development/Exploration: Use --interactive
Scripts/CI/CD: Use explicit flags

Troubleshooting

Terminal Not Supported

Error: “Interactive mode not supported in this terminal”

Cause: Running in non-interactive environment (CI, cron, etc.)

Solution: Use explicit flags:

arxo analyze --format json

Prompt Doesn’t Appear

Issue: Hangs after running --interactive

Causes:

Stdin not connected: Redirected input
Terminal emulator: Some terminals don’t support interactive prompts

Solutions:

Check stdin:

# ❌ Won't work
echo "" | arxo analyze --interactive

# ✅ Works
arxo analyze --interactive

Use explicit flags:
Terminal window
```
arxo analyze --path .
```

Slow Browsing

Issue: File browser is slow

Solution: Enter path manually:

? Select project directory:
  > Enter path manually

Can’t Find Project

Issue: Project not listed in browse mode

Solution: Use absolute path:

? Enter project path: /full/path/to/project

Examples

Example 1: Agent Architecture Check

$ arxo analyze --interactive

? Select project directory: . (current directory)
? Run agent and OpenClaw architecture: Yes
? Save report to file? No, display in terminal

✓ Analysis complete!
✓ Agent architecture: overall_agent_health 0.72
✓ No policy violations

Example 2: Generate HTML Report

$ arxo analyze --interactive

? Select project directory: .
? Run agent and OpenClaw architecture: Yes
? Save report to file? Yes, save as HTML
? Output filename: agent-report.html

✓ Report saved to: agent-report.html

$ open agent-report.html

Example 3: Save JSON for CI

$ arxo analyze --interactive

? Select project directory: .
? Run agent and OpenClaw architecture: Yes
? Save report to file? Yes, save as JSON
? Output filename: report.json

✓ Report saved to: report.json

Tips and Best Practices

1. Use the AI Preset

For agent architecture analysis:

arxo analyze --interactive
# Choose default metrics

HTML reports are self-contained and easy to share:

arxo analyze --interactive
# Choose "Yes, save as HTML"
# Email/Slack the HTML file to team

3. Use for Teaching

Interactive mode is self-documenting:

Team onboarding: Walk through options together
Workshops: Demonstrate analysis flow
Documentation: Screenshot the prompts

4. Combine with Config Files

Best of both worlds:

# Create config with interactive wizard
arxo init --interactive

# Run analysis with interactive prompts
arxo analyze --interactive
# Choose "Use .arxo.yaml config"

5. Bookmark Common Workflows

Create shell aliases:

# ~/.bashrc or ~/.zshrc
alias arxoi='arxo analyze --interactive'
alias arxoa='arxo analyze'
alias arxoah='arxo analyze --format html'

Usage:

arxoi           # Interactive mode
arxoa           # Agent architecture (non-interactive)
arxoah          # Agent architecture report (HTML)

Scripting with Interactive Mode

While interactive mode isn’t designed for automation, you can use expect or yes for demos:

Using `yes` (Limited)

# Auto-select first option for all prompts (not recommended)
yes "" | arxo analyze --interactive

Using `expect` (Advanced)

#!/usr/bin/expect -f

spawn arxo analyze --interactive

# Select current directory
expect "Select project directory:"
send "\r"

# Confirm default metrics
expect "Run agent and OpenClaw"
send "\r"

# Don't save to file
expect "Save report to file?"
send "\r"

expect eof

Note: For real automation, use CLI flags instead.