Skip to content

For AI Agents

Jump to bottom
Kumak edited this page Nov 22, 2025 · 2 revisions

For AI Agents

bdg is designed for autonomous AI agents. This page covers discovery patterns, exit codes, and best practices.

Self-Documenting Discovery

Agents don't need external docs - bdg teaches itself:

# What domains exist?
bdg cdp --list                              # 53 domains

# What can Network do?
bdg cdp Network --list                      # 39 methods

# How do I use this method?
bdg cdp Network.getCookies --describe       # Full schema + examples

# Find methods by keyword
bdg cdp --search screenshot                 # Find screenshot methods
bdg cdp --search cookie                     # 14 results

Discovery → Learn → Execute Pattern

# 1. Discover
bdg cdp --search storage
# Returns: Storage.getCookies, Storage.clearDataForOrigin, ...

# 2. Learn
bdg cdp Storage.getCookies --describe
# Returns: Parameters, types, examples

# 3. Execute
bdg cdp Storage.getCookies

Machine-Readable Help

bdg --help --json

Returns complete CLI schema with all commands, flags, defaults, and exit codes.

Exit Codes

Code Category Meaning
0 Success Operation completed
1 Generic Unspecified failure
80-89 User Input Fix input before retry
80 Invalid URL Malformed URL
81 Invalid Arguments Bad command arguments
82 Permission Denied Insufficient permissions
83 Resource Not Found Target doesn't exist
84 Resource Already Exists Duplicate resource
85 Resource Busy Resource is locked or busy
86 Daemon Already Running Session already active
100-119 Software May retry with backoff
100 Chrome Launch Chrome failed to start
101 CDP Connection WebSocket failed
102 CDP Timeout Operation timed out
103 Session File Error File read/write failed
104 Unhandled Exception Internal error
105 Signal Handler Error Signal handling failed
110 Software Error Generic software error

Agent Decision Logic

exit_code=$?
case $exit_code in
  0)       # Success - proceed
  80-89)   # User error - don't retry, fix input
  100-102) # External failure - retry with backoff
esac

Token Efficiency

Semantic DOM (70-99% Reduction)

# Default: semantic output
bdg dom get "button"
# [Button] "Submit" (focusable)

# Raw HTML (verbose)
bdg dom get "button" --raw
# <button class="btn btn-primary submit-btn" type="submit">Submit</button>

Real-world example (Wikipedia):

bdg https://en.wikipedia.org/wiki/Main_Page
bdg dom query "a"
bdg dom get 0
# [Link] "Main page" (inferred from DOM)

Graceful Degradation

When Chrome's accessibility tree returns no data, bdg infers roles from HTML:

HTML Tag Inferred Role
<a> link
<button> button
<h1>-<h6> heading (with level)
<nav> navigation
<input> textbox

Output shows (inferred from DOM) when fallback is used.

Best Practices

1. Use Discovery First

bdg cdp --search <keyword>
bdg cdp <Domain> --list
bdg cdp <Method> --describe

2. Handle Exit Codes

if bdg dom query "button"; then
  # Success
else
  case $? in
    83) echo "Element not found" ;;
    101) echo "Connection failed" ;;
  esac
fi

3. Use Cached Indices

bdg dom query "input"    # Cache results
bdg dom get 0            # Use index
bdg dom fill 0 "value"   # Interact by index

4. Compose with Unix Tools

bdg cdp Network.getCookies | jq '.cookies[] | select(.httpOnly)'
bdg dom query "button" --json | jq '.count'

Claude Skill

A Claude skill is included at .claude/skills/bdg/ with workflows and troubleshooting guides.

Clone this wiki locally