Neo — Web App API Discovery & Execution

Neo turns any website into an AI-callable API. It passively captures browser traffic, generates API schemas, and lets you call discovered APIs directly — no scraping, no reverse engineering.

First-Time Setup

# Install CLI
npm i -g @4ier/neo

# One-time setup: detects Chrome, installs extension, configures profile
neo setup

# Start Chrome with Neo extension
neo start

# Verify everything works
neo doctor

All 6 checks should be ✓. If not, run neo setup again.

Prerequisites: Browser with CDP

Neo requires Chrome running with Chrome DevTools Protocol (CDP) enabled.

# Check connection
neo doctor

# If Chrome isn't running with CDP:
neo start

# Or start manually with your own profile:
# google-chrome-stable --remote-debugging-port=9222 &

Environment variables (all optional):

NEO_CDP_URL — CDP endpoint (default: http://localhost:9222)
NEO_EXTENSION_ID — Force specific extension ID (default: auto-discovered)
NEO_SCHEMA_DIR — Schema storage directory (default: ~/.neo/schemas)

Complete Workflow

Step 1: Check what Neo already knows

neo status                    # Overview: domains, capture counts, extension status
neo schema list               # Cached API schemas (knowledge from past browsing)

Step 2: Open target website (if needed)

neo open https://example.com  # Opens in Chrome

Step 3: Read page content

neo read example.com          # Extract readable text from the page (like reader mode)

Step 4: Interact via API (fast path)

# Check if we have API knowledge for this domain
neo schema show x.com

# Smart API call: auto-finds endpoint + auth
neo api x.com HomeTimeline
neo api x.com CreateTweet --body '{"variables":{"tweet_text":"hello"}}'
neo api github.com notifications

Step 5: Execute in page context

neo exec <url> --method POST --body '{}' --tab example.com --auto-headers
neo replay <capture-id> --tab example.com
neo eval "document.title" --tab example.com

Step 6: UI automation (when no API exists)

neo snapshot                  # Get accessibility tree with @ref mapping
neo click @14                 # Click element by reference
neo fill @7 "search query"    # Fill input field
neo type @7 "text"            # Append text
neo press Enter               # Keyboard input
neo scroll down 500           # Scroll
neo screenshot                # Capture screenshot

Step 7: Clean up — ALWAYS close tabs when done

neo tabs                                        # List open tabs
neo eval "window.close()" --tab example.com     # Close tab

⚠️ Resource management: Every neo open creates a new tab. Always close tabs after you're done.

API Discovery Workflow

When you need to discover what APIs a website uses:

# 1. Open the site, browse around to generate captures
neo open https://example.com

# 2. Check accumulated captures
neo capture list example.com --limit 20
neo capture search "api" --limit 10

# 3. Generate API schema
neo schema generate example.com

# 4. Explore the schema
neo schema show example.com

# 5. Call discovered APIs
neo api example.com <endpoint-keyword>

Command Reference

# --- Page Reading & Interaction ---
neo open <url>                          # Open URL in Chrome (creates new tab!)
neo read <tab-pattern>                  # Extract readable text from page
neo eval "<js>" --tab <pattern>         # Run JS in page context
neo tabs [filter]                       # List open Chrome tabs

# --- UI Automation ---
neo snapshot [-i] [-C] [--json]         # A11y tree with @ref mapping
neo click @ref [--new-tab]              # Click element
neo fill @ref "text"                    # Clear + fill input
neo type @ref "text"                    # Append text to input
neo press <key>                         # Keyboard key (Ctrl+a, Enter, etc.)
neo hover @ref                          # Hover
neo scroll <dir> [px] [--selector css]  # Scroll
neo select @ref "value"                 # Select dropdown
neo screenshot [path] [--full]          # Capture screenshot
neo get text @ref | url | title         # Extract info
neo wait @ref | --load | <ms>           # Wait for element/load/time

# --- Capture & Traffic ---
neo status                              # Overview
neo capture list [domain] [--limit N]   # Recent captures
neo capture search <query>              # Search by URL pattern
neo capture domains                     # Domains with counts
neo capture detail <id>                 # Full capture details
neo capture stats <domain>              # Statistics breakdown

# --- Schema (API Knowledge) ---
neo schema generate <domain>            # Generate from captures
neo schema show <domain>                # Human-readable
neo schema list                         # All cached schemas
neo schema search <query>               # Search endpoints
neo schema openapi <domain>             # Export OpenAPI 3.0

# --- API Execution ---
neo api <domain> <keyword> [--body '{}']  # Smart call (schema + auto-auth)
neo exec <url> [--method POST] [--body] [--tab pattern] [--auto-headers]
neo replay <id> [--tab pattern]         # Replay captured call

# --- Analysis ---
neo flows <domain>                      # API call sequence patterns
neo deps <domain>                       # Data flow dependencies
neo suggest <domain>                    # AI capability analysis

# --- Setup & Diagnostics ---
neo setup                               # First-time setup (Chrome + extension)
neo start                               # Launch Chrome with Neo extension
neo doctor                              # Health check
neo version                             # Version

Decision Tree

User wants to interact with a website
  │
  ├─ Just read content? → neo read <domain>
  │
  ├─ Need to call an API?
  │   ├─ neo schema show <domain> → schema exists? → neo api <domain> <keyword>
  │   └─ No schema? → neo open <url> → browse → neo schema generate <domain>
  │
  ├─ Need to fill forms / click buttons?
  │   └─ neo snapshot → neo click/fill/type @ref
  │
  └─ Complex multi-step interaction?
      └─ Combine: neo open → neo snapshot → neo click/fill → neo read → close tab

Key Rules

Always check CDP first: Run neo doctor to verify Chrome is reachable
Close tabs after use: neo eval "window.close()" --tab <pattern>
Check schema before API calls: neo schema show <domain> — use cached knowledge
API > UI automation: If an API exists, use neo api/neo exec instead of snapshot+click
Per-domain capture cap: 500 entries, auto-cleanup. Don't worry about storage.
Auth is automatic: API calls run in browser context, inheriting cookies/session/CSRF