ask

The read side of RepoSwarm. Query your codebase architecture with AI.

ask is a CLI for querying architecture knowledge generated by RepoSwarm. It connects to an askbox server that holds your .arch.md files and uses LLMs to reason across repos.

RepoSwarm writes architecture docs. ask reads them.

Install

curl -fsSL https://raw.githubusercontent.com/reposwarm/ask-cli/main/install.sh | sh

Or with Go:

go install github.com/reposwarm/ask-cli/cmd/ask@latest

Quick Start

# Set up a local askbox (interactive — configures provider, starts Docker)
ask setup

# Or non-interactive
ask setup --provider bedrock --region us-east-1 --model sonnet \
  --arch-hub https://github.com/org/arch-hub.git

# Check server status
ask status

# Ask a question
ask "how does authentication work across services?"

If you already have RepoSwarm installed, ask setup auto-detects its provider configuration and offers to reuse it.

Usage

Ask a question

# Default: submits and waits for answer
ask "what patterns are shared across repos?"

# Get job ID immediately (don't wait)
ask --no-wait "summarize the architecture"

# JSON output
ask --json "what databases are used?"

# Scope to repos
ask --repos api,billing,auth "how do these talk to each other?"

# Override model
ask --model us.anthropic.claude-opus-4-20250514-v1:0 "deep analysis of security patterns"

Check status

ask status

🏥 Askbox Server Status

  Server:    http://localhost:8082
  Status:    healthy
  Arch-hub:  ✅ ready (12 repos)
  Jobs:      5 total, 0 running
  Uptime:    4992s

List previous questions

ask list
ask list --status completed
ask list --limit 10

📋 Questions (5)

  ✅ completed  47a8df6c  What databases are used?                  (1258 chars)
  ✅ completed  4f329717  How does auth work across services?       (1577 chars)
  ⏳ running    7feed4a0  Summarize the architecture                

Get a previous answer

ask get 47a8df6c
ask get 47a8df6c --json

Refresh arch-hub

# Pull latest from configured arch-hub
ask refresh

# Set a new arch-hub URL
ask refresh --url https://github.com/org/arch-hub.git

Browse Results

Read architecture docs directly from the arch-hub files:

# List repos with architecture docs
ask results list

# Read a repo's architecture
ask results read my-api
ask results read my-api Authentication

# Search across all repos
ask results search "DynamoDB"
ask results search "auth" --repo my-api --max 20

# Compare two repos
ask results diff my-api my-frontend

# Export to markdown files
ask results export my-api -o my-api.arch.md
ask results export --all -d ./docs

By default, results are read from the local arch-hub directory (auto-detected from askbox or common paths). Override with --path:

ask results list --path /path/to/arch-hub

Configuration

# Show config
ask config show

# Set server URL
ask config set serverUrl http://askbox.internal:8082

# Set default adapter
ask config set adapter strands

# Set default model
ask config set model us.anthropic.claude-sonnet-4-20250514-v1:0

Docker Management

ask setup              # Interactive setup (provider + Docker)
ask up                 # Start askbox container
ask down               # Stop askbox container
ask logs               # View logs
ask logs -f            # Follow logs

ask setup writes:

• ~/.config/ask/config.json — CLI settings (no secrets)
• ~/.ask/askbox.env — Provider credentials (mode 0600)
• ~/.ask/docker-compose.yml — Docker Compose for askbox

Config is stored at ~/.config/ask/config.json.

Resolution order (highest wins):

1. --server flag
2. ASK_SERVER_URL environment variable
3. Config file serverUrl
4. Default: http://localhost:8082

Global Flags

Flag	Description
--json	JSON output
--for-agent	Plain text (no colors/spinners)
-s, --server	Override askbox server URL

How It Works

┌──────────┐     HTTP      ┌──────────┐    LLM    ┌─────────────┐
│  ask CLI │ ──────────▶  │  askbox  │ ────────▶ │ Claude/etc  │
│          │ ◀──────────  │  server  │ ◀──────── │             │
└──────────┘              └──────────┘            └─────────────┘
                               │
                               ▼
                         ┌───────────┐
                         │ arch-hub  │
                         │ .arch.md  │
                         │ files     │
                         └───────────┘

1. ask submits a question to the askbox HTTP server
2. Askbox uses an LLM (Claude Agent SDK or Strands) to read .arch.md files
3. The LLM reasons across repos and returns a detailed answer
4. ask polls for the result and displays it

Askbox Server

The askbox server is a separate component. See reposwarm-askbox for details.

Standalone (via ask setup):

ask setup    # Interactive: picks provider, writes env, starts Docker

Manual Docker:

docker run -d --name askbox \
  -p 8082:8082 \
  -e ARCH_HUB_URL=https://github.com/org/arch-hub.git \
  ghcr.io/reposwarm/ask-clibox:latest

With RepoSwarm: Askbox runs automatically as part of the RepoSwarm Docker Compose stack.

RepoSwarm Integration

If you use RepoSwarm, the askbox server runs as part of your Docker Compose stack. Just install ask and it connects to localhost:8082 automatically.

# RepoSwarm writes architecture docs
reposwarm investigate my-api

# ask reads them
ask "how does my-api handle authentication?"

License

MIT