Bloxy CLI

Bloxy - AI-Powered Coding Automation CLI. Autonomous AI coding loop. Runs AI agents on tasks until done. Supports Claude Code, OpenCode, Codex, Cursor, Qwen-Code, Factory Droid, GitHub Copilot and Gemini CLI.

Install

Option A: npm (recommended)

npm install -g @bloxystudios/cli

# Then use anywhere
bloxy "add login button"
bloxy --prd PRD.md

Option B: Clone

git clone https://github.com/bloxy-studios/bloxy.git
cd bloxy-cli
bun install
bun run build

# Link binary
npm link

Two Modes

Single task - just tell it what to do:

bloxy "add dark mode"
bloxy "fix the auth bug"

Task list - work through a PRD:

bloxy              # uses PRD.md
bloxy --prd tasks.md

Project Config

Optional. Stores rules the AI must follow.

bloxy --init              # auto-detects project settings
bloxy --config            # view config
bloxy --add-rule "use TypeScript strict mode"

Creates .bloxy/config.yaml:

project:
  name: "my-app"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm test"
  lint: "npm run lint"
  build: "npm run build"

rules:
  - "use server actions not API routes"
  - "follow error pattern in src/utils/errors.ts"

boundaries:
  never_touch:
    - "src/legacy/**"
    - "*.lock"

notifications:
  discord_webhook: "https://discord.com/api/webhooks/..."
  slack_webhook: "https://hooks.slack.com/services/..."
  custom_webhook: "https://your-api.com/webhook"

Rules apply to all tasks (single or PRD).

AI Engines

bloxy              # Claude Code (default)
bloxy --opencode   # OpenCode
bloxy --cursor     # Cursor
bloxy --codex      # Codex
bloxy --qwen       # Qwen-Code
bloxy --droid      # Factory Droid
bloxy --copilot    # GitHub Copilot
bloxy --gemini     # Gemini CLI

Model Override

Override the default model for any engine:

bloxy --model sonnet "add feature"                    # use sonnet with Claude
bloxy --sonnet "add feature"                          # shortcut for above
bloxy --opencode --model opencode/glm-4.7-free "task" # custom OpenCode model
bloxy --qwen --model qwen-max "build api"             # custom Qwen model

Engine-Specific Arguments

Pass additional arguments to the underlying engine CLI using -- separator:

# Pass copilot-specific arguments
bloxy --copilot --model "claude-opus-4.5" --prd PRD.md -- --allow-all-tools --allow-all-urls --stream on

# Pass claude-specific arguments  
bloxy --claude "add feature" -- --no-permissions-prompt

# Works with any engine
bloxy --cursor "fix bug" -- --custom-arg value

Everything after -- is passed directly to the engine CLI without interpretation.

Task Sources

Markdown file (default):

bloxy --prd PRD.md

## Tasks

- [ ] create auth
- [ ] add dashboard
- [x] done task (skipped)

Markdown folder (for large projects):

bloxy --prd ./prd/

When pointing to a folder, Bloxy reads all .md files and aggregates tasks:

prd/
  backend.md      # - [ ] create user API
  frontend.md     # - [ ] add login page
  infra.md        # - [ ] setup CI/CD

Tasks are tracked per-file so completion updates the correct file.

YAML:

bloxy --yaml tasks.yaml

tasks:
  - title: create auth
    completed: false
  - title: add dashboard
    completed: false

JSON:

bloxy --json PRD.json

{
  "tasks": [
    {
      "title": "create auth",
      "completed": false,
      "parallel_group": 1,
      "description": "Optional details"
    }
  ]
}

Titles must be unique.

GitHub Issues:

bloxy --github owner/repo
bloxy --github owner/repo --github-label "ready"

Parallel Execution

bloxy --parallel                  # 3 agents default
bloxy --parallel --max-parallel 5 # 5 agents

Each agent gets isolated worktree + branch:

Agent 1 → /tmp/xxx/agent-1 → bloxy/agent-1-create-auth
Agent 2 → /tmp/xxx/agent-2 → bloxy/agent-2-add-dashboard
Agent 3 → /tmp/xxx/agent-3 → bloxy/agent-3-build-api

Without --create-pr: auto-merges back to base branch, AI resolves conflicts. With --create-pr: keeps branches, creates PRs. With --no-merge: keeps branches without merging or creating PRs.

YAML parallel groups - control execution order:

tasks:
  - title: Create User model
    parallel_group: 1
  - title: Create Post model
    parallel_group: 1 # same group = runs together
  - title: Add relationships
    parallel_group: 2 # runs after group 1

Branch Workflow

bloxy --branch-per-task                # branch per task
bloxy --branch-per-task --create-pr    # + create PRs
bloxy --branch-per-task --draft-pr     # + draft PRs
bloxy --base-branch main               # branch from main

Branch naming: bloxy/<task-slug>

Browser Automation

Bloxy can use agent-browser to automate browser interactions during tasks.

bloxy "test the login flow" --browser    # force enable
bloxy "add checkout" --no-browser        # force disable
bloxy "build feature"                    # auto-detect (default)

When enabled, the AI gets browser commands:

• agent-browser open <url> - navigate to URL
• agent-browser snapshot - get element refs (@e1, @e2)
• agent-browser click @e1 - click element
• agent-browser type @e1 "text" - type into input
• agent-browser screenshot <file> - capture screenshot

Use cases:

• Testing UI after implementing features
• Verifying deployments
• Form filling and workflow testing

Config (.bloxy/config.yaml):

capabilities:
  browser: "auto" # "auto", "true", or "false"

Webhook Notifications

Get notified when sessions complete via Discord, Slack, or custom webhooks.

Config (.bloxy/config.yaml):

notifications:
  discord_webhook: "https://discord.com/api/webhooks/..."
  slack_webhook: "https://hooks.slack.com/services/..."
  custom_webhook: "https://your-api.com/webhook"

Notifications include task completion counts and status (completed/failed).

Sandbox Mode

For large repos with big dependency directories, sandbox mode is faster than git worktrees:

bloxy --parallel --sandbox

How it works:

• Symlinks read-only dependencies (node_modules, .git, vendor, .venv, .pnpm-store, .yarn, .cache)
• Copies source files that agents might modify (src/, app/, lib/, config files, etc.)

Why use it:

• Avoids duplicating gigabytes of node_modules across worktrees
• Much faster sandbox creation for large monorepos
• Changes sync back to original directory after each task

When to use worktrees instead (default):

• Need full git history access in each sandbox
• Running git commands that require a real repo
• Smaller repos where worktree overhead is minimal

Parallel execution reliability:

• If worktree operations fail (e.g., nested worktree repos), bloxy falls back to sandbox mode automatically
• Retryable rate-limit or quota errors are detected and deferred for later retry
• Local changes are stashed before the merge phase and restored after

GitHub Issue Sync

Sync your PRD progress to a GitHub issue for tracking:

bloxy --prd PRD.md --sync-issue 42

This updates issue #42's body with the current PRD content after each task completes.

Options

| Flag | What it does | | -------------------- | ----------------------------------------------------- | | --prd PATH | task file or folder (auto-detected, default: PRD.md) | | --yaml FILE | YAML task file | | --json FILE | JSON task file | | --github REPO | use GitHub issues | | --github-label TAG | filter issues by label | | --sync-issue N | sync PRD progress to GitHub issue #N | | --model NAME | override model for any engine | | --sonnet | shortcut for --claude --model sonnet | | --parallel | run parallel | | --max-parallel N | max agents (default: 3) | | --sandbox | use lightweight sandboxes instead of git worktrees | | --no-merge | skip auto-merge in parallel mode | | --branch-per-task | branch per task | | --base-branch NAME | base branch | | --create-pr | create PRs | | --draft-pr | draft PRs | | --no-tests | skip tests | | --no-lint | skip lint | | --fast | skip tests + lint | | --no-commit | don't auto-commit | | --max-iterations N | stop after N tasks | | --max-retries N | retries per task (default: 3) | | --retry-delay N | seconds between retries | | --dry-run | preview only | | --browser | enable browser automation | | --no-browser | disable browser automation | | -v, --verbose | debug output | | --init | setup .bloxy/ config | | --config | show config | | --add-rule "rule" | add rule to config |

Requirements

Required:

• AI CLI: Claude Code, OpenCode, Cursor, Codex, Qwen-Code, Factory Droid, GitHub Copilot, or Gemini CLI

npm version (@bloxystudios/cli):

• Node.js 18+ or Bun

Both versions:

• gh (optional, for GitHub issues / --create-pr)
• agent-browser (optional, for --browser)

Engine Details

| Engine | CLI | Permissions | Output | | -------- | ------------ | -------------------------------- | ------------- | | Claude | claude | --dangerously-skip-permissions | tokens + cost | | OpenCode | opencode | full-auto | tokens + cost | | Codex | codex | N/A | tokens | | Cursor | agent | --force | duration | | Qwen | qwen | --approval-mode yolo | tokens | | Droid | droid exec | --auto medium | duration | | Copilot | copilot | -p flag | duration | | Gemini | gemini | --yolo | tokens + cost |

When an engine exits non-zero, bloxy includes the last lines of CLI output in the error message to make debugging easier.

Changelog

v1.1.0

• Gemini CLI support: new --gemini engine option for Google Gemini CLI
• JSON PRD support: new --json flag to use JSON files as task sources with support for parallel groups and task descriptions
• Sandbox mode: --sandbox flag for lightweight isolation using symlinks for dependencies (faster than worktrees)
• Webhook notifications: Discord, Slack, and custom webhooks for session completion (configure in .bloxy/config.yaml)
• GitHub issue sync: --sync-issue <number> syncs PRD progress to a GitHub issue after each task
• Task caching: Performance improvements with in-memory task caching and debounced writes
• Telemetry system: Opt-in eval dataset collection for building AI benchmarks
• Engine-specific arguments: Pass arguments to underlying CLI via -- separator
• Automated versioning: Version generation scripts for release management
• Deferred task handling: Detect rate-limit/quota errors and defer for later retry
• Improved parallel reliability: Fallback to sandbox mode on worktree errors, stash local changes during merge

v1.0.0

• Initial release
• Support for Claude Code, OpenCode, Codex, Cursor, Qwen-Code, Factory Droid, GitHub Copilot
• Sequential and parallel execution modes
• Markdown, YAML, and GitHub Issues task sources
• Branch-per-task workflow with PR creation
• Browser automation integration
• Project configuration system

License

MIT