bz-agent

Set up AI agent integration with Boozang test automation.

Running npx bz-agent init creates a .bz/ directory in your project with connection config and comprehensive LLM-readable documentation, so any AI assistant (Claude, Cursor, ChatGPT, etc.) can interact with Boozang's MCP tools (40+ tools across data management and IDE control).

Quick Start

npx bz-agent init

You'll be prompted for:

• Server URL (default: https://ai.boozang.com)
• MCP token (bzmcp_... — generate in Boozang: Project Settings → MCP API)
• Project ID (optional — auto-resolved from the token)
• Version (default: master)

What It Creates

your-project/
├── .bz/
│   ├── .env               # Auth token (gitignored)
│   ├── .gitignore         # Protects .env
│   ├── config.json        # Connection config
│   ├── AGENT.md           # Main guide for AI assistants
│   ├── mcp-api.md         # Full 25-tool API reference
│   ├── concepts.md        # Data model & terminology
│   ├── workflows.md       # Common automation patterns
│   └── best-practices.md  # Test design recommendations
├── CLAUDE.md              # Pointer to .bz/AGENT.md (optional)
└── ...

Point your AI assistant to .bz/AGENT.md and it has everything it needs.

Commands

bz-agent init

Create .bz/ directory with config and agent documentation.

# Interactive
npx bz-agent init

# Non-interactive
npx bz-agent init --server=https://ai.boozang.com --token=bzmcp_YOUR_TOKEN --project=p123 --version=master

# Skip CLAUDE.md creation
npx bz-agent init --no-claude

bz-agent status

Show current config and test the API connection.

npx bz-agent status

bz-agent update

Re-render .bz/*.md files from the latest bundled templates. Preserves your .env token.

npx bz-agent update

bz-agent snapshot

Cache the project's module/test structure locally so AI agents don't need to re-fetch it every session. Creates two files:

• .bz/modules-cache.json — raw JSON for programmatic use
• .bz/project-map.md — human/AI-readable module map

npx bz-agent snapshot

Run this after init, or whenever modules/tests change significantly. AI agents are instructed to read .bz/project-map.md before making getModules/getTests API calls.

How It Works

The .bz/AGENT.md file is a self-contained guide that tells any AI assistant:

1. How to connect — endpoint, auth, project/version
2. What tools are available — 40+ MCP tools (data CRUD + IDE control)
3. How to onboard users — the 8-step interview flow
4. How Boozang works — data model, concepts, patterns

The MCP API uses JSON-RPC 2.0 over HTTPS. Your AI makes HTTP POST requests to the Boozang server.

Requirements

• Node.js >= 18
• A Boozang account with an MCP token (generate in Project Settings → MCP API)

License

MIT