reposwarm-askbox

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.

What it does

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.

Architecture

┌──────────────────────────────────────────────────┐
│  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.

Quick Start (standalone)

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

Environment Variables

Variable	Required	Description
QUESTION	Yes	The architecture question to answer
ARCH_HUB_URL	Yes	Git URL of the arch-hub repository
ARCH_HUB_BRANCH	No	Branch to clone (default: main)
Anthropic API
ANTHROPIC_API_KEY	*	Anthropic API key (from platform.claude.com)
Amazon Bedrock
CLAUDE_CODE_USE_BEDROCK	*	Set to 1 to enable Bedrock
AWS_REGION	*	AWS region (e.g. us-east-1)
AWS_BEARER_TOKEN_BEDROCK	*	Bedrock API key — simplest auth, no IAM needed
AWS_ACCESS_KEY_ID	*	IAM access key (alternative to API key)
AWS_SECRET_ACCESS_KEY	*	IAM secret key
AWS_SESSION_TOKEN	*	Session token (for temporary credentials)
AWS_PROFILE	*	AWS SSO profile name
LiteLLM Proxy
ANTHROPIC_BASE_URL	*	LiteLLM proxy URL
LITELLM_API_KEY	*	LiteLLM API key
Options
ASKBOX_ADAPTER	No	Agent adapter: claude-agent-sdk (default) or strands
MODEL_ID	No	Override model (default: claude-sonnet-4-20250514)
MAX_TOOL_CALLS	No	Max agent tool invocations (default: 50)
OUTPUT_DIR	No	Where to write answer (default: /output)
STATUS_FILE	No	Write progress updates to this file
REPOS_FILTER	No	Comma-separated list of repos to scope the question to
IS_SANDBOX	No	Set to 1 for root/Docker — already set in image

* 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.

Agent Tools

Claude Agent SDK (default)

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

Strands SDK (--adapter strands)

Custom tools:

Tool	Description
list_repos()	Returns manifest — all repo names, types, one-line summaries
read_arch(repo, section?)	Read a repo's full .arch.md or a specific section
search_arch(query)	Text search across all arch files, returns matching lines with context

Output

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

Integration with RepoSwarm

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.

Development

# 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

Ecosystem

Project	Docker Image
reposwarm-cli	— (binary install)
reposwarm-api	ghcr.io/reposwarm/api:latest
reposwarm-ui	ghcr.io/reposwarm/ui:latest
reposwarm (worker)	ghcr.io/reposwarm/worker:latest
reposwarm-askbox (this repo)	ghcr.io/reposwarm/askbox:latest

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

License

Apache License 2.0