The askbox server for RepoSwarm. Answers architecture questions across your repos using AI.

Looking for the CLI? → ask — the standalone command-line client for querying askbox.

The askbox is a persistent HTTP server that answers architecture questions across your repos. It clones your arch-hub (the repository containing all .arch.md files generated by RepoSwarm), runs an AI agent with specialized tools, and returns a markdown report.

Adapters: Claude Agent SDK (default) or Strands SDK. Switch via --adapter strands or ASKBOX_ADAPTER=strands.

┌──────────────────────────────────────────────────┐
│  reposwarm/askbox container                      │
│                                                  │
│  1. Clone arch-hub repo → /tmp/arch-hub          │
│  2. Select adapter (Claude Agent SDK or Strands) │
│  3. Run agent with question                      │
│     Claude Agent SDK: built-in Read/Glob/Grep    │
│     Strands: custom list_repos/read_arch/search  │
│  4. Agent reads relevant arch files              │
│  5. Agent reasons across repos                   │
│  6. Output: markdown answer                      │
│                                                  │
└──────────────────────────────────────────────────┘

The container is designed to run anywhere:

• Local: docker run — for reposwarm new --local users
• AWS: ECS Fargate RunTask
• GCP: Cloud Run Jobs
• Azure: Container Instances
• Kubernetes: Job

Same image everywhere. No vendor lock-in.

Note: The image sets IS_SANDBOX=1 so the Claude Agent SDK's bypassPermissions mode works as root inside Docker. This is baked in — you don't need to set it yourself.

Run a question directly against the sample arch-hub:

# Build the image locally
docker build -t reposwarm/askbox .

# Or pull the pre-built image
docker pull ghcr.io/reposwarm/askbox:latest

# Ask a question
docker run --rm \
  -e ARCH_HUB_URL=https://github.com/royosherove/repo-swarm-sample-results-hub.git \
  -e QUESTION="What testing frameworks are used across all repos and how do they compare?" \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v $(pwd)/output:/output \
  ghcr.io/reposwarm/askbox:latest

# Read the answer
cat output/answer.md

With Amazon Bedrock:

# Option 1: Bedrock API key (simplest — no IAM setup needed)
docker run --rm \
  -e ARCH_HUB_URL=https://github.com/royosherove/repo-swarm-sample-results-hub.git \
  -e QUESTION="How do the state management approaches differ between React and Vue repos?" \
  -e CLAUDE_CODE_USE_BEDROCK=1 \
  -e AWS_REGION=us-east-1 \
  -e AWS_BEARER_TOKEN_BEDROCK=br-... \
  -v $(pwd)/output:/output \
  ghcr.io/reposwarm/askbox:latest

# Option 2: IAM access keys
docker run --rm \
  -e ARCH_HUB_URL=https://github.com/royosherove/repo-swarm-sample-results-hub.git \
  -e QUESTION="How do the state management approaches differ between React and Vue repos?" \
  -e CLAUDE_CODE_USE_BEDROCK=1 \
  -e AWS_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=AKIA... \
  -e AWS_SECRET_ACCESS_KEY=... \
  -v $(pwd)/output:/output \
  ghcr.io/reposwarm/askbox:latest

# Option 3: IAM role (on EC2/ECS — credentials from instance metadata)
docker run --rm \
  -e ARCH_HUB_URL=https://github.com/royosherove/repo-swarm-sample-results-hub.git \
  -e QUESTION="How do the state management approaches differ between React and Vue repos?" \
  -e CLAUDE_CODE_USE_BEDROCK=1 \
  -e AWS_REGION=us-east-1 \
  -v $(pwd)/output:/output \
  ghcr.io/reposwarm/askbox:latest

* At least one LLM provider must be configured. For Bedrock, the simplest option is AWS_BEARER_TOKEN_BEDROCK (get one from the Bedrock console → API keys). For EC2/ECS with an IAM role, just set CLAUDE_CODE_USE_BEDROCK=1 and AWS_REGION.

Uses built-in tools: Read, Glob, Grep — the agent explores the arch-hub directory autonomously.

Custom tools:

The agent writes its answer to /output/answer.md (or $OUTPUT_DIR/answer.md). Progress updates go to $STATUS_FILE if set, otherwise stdout.

When used through the RepoSwarm CLI (reposwarm ask "question"):

1. CLI calls the RepoSwarm API (POST /ask)
2. API starts the askbox container (via runtime adapter)
3. Container runs, writes status updates to the API's database
4. API returns ask-id; CLI polls for completion
5. CLI downloads the markdown answer

The askbox doesn't know or care about the RepoSwarm API — it's just a container that takes a question and produces an answer. The API adapter handles orchestration.

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run locally without Docker
python -m src.agent --question "What patterns do the repos share?" \
  --arch-hub-url https://github.com/royosherove/repo-swarm-sample-results-hub.git

All images are multi-arch (linux/amd64 + linux/arm64), published on every push to main.

Apache License 2.0