hmmhmmhm/ax-grep/ax-grep-cli

ax-grep CLI

Use ax-grep before browser automation when a subagent needs to inspect a search result, URL, HTML file, or captured page.

First Command

ax-grep "https://example.com" --agent

If ax-grep is not on PATH, use the npm executable:

npx --yes ax-grep@latest "https://example.com" --agent

For smaller context:

ax-grep "https://example.com" --agent-brief

Search

ax-grep --search "official docs pricing" --agent

Use the returned agent.*CommandArgs fields when continuing. They are JSON argv arrays in execution order. Use agent.*Command when you need a shell string.

Agent Policy

• Prefer --agent or --agent-brief over raw text output for subagents.
• Read agent.executor, agent.handoff, agent.next, agent.readTargets,

and any returned agent.sourceChoices or agent.resultChoices before deciding.

• If agent.executor.decision is return, answer from the referenced

readFrom payload instead of opening a browser.

• If a URL follow-up is needed, run the provided commandArgs one command at a

time.

• Escalate to browser automation only when needsBrowserHtml,

needsBrowserInteraction, or the executor/handoff fields say it is needed.

• Do not run multiple browser-backed checks in parallel.

Useful Patterns

Inspect a result and open the best match in one step:

ax-grep --search "site:example.com api reference" --open-result best --agent

If an engine rejects best, open the top ranked result directly:

ax-grep --search "site:example.com api reference" --open-result 1 --agent

Check a page for specific terms:

ax-grep "https://example.com/docs" --find "rate limit" --find "authentication" --agent

Read static HTML from another tool:

curl -fsSL "https://example.com" | ax-grep --stdin --agent

What ax-grep Sees

ax-grep --agent can expose:

• semantic headings, landmarks, links, buttons, forms, tables, and lists
• source-like links and ranked search choices
• JSON-LD schema facts, metadata, policies, topics, provenance, and citations
• hydration URLs, API endpoints, runtime hints, app config, and mobile hints
• recommended next commands and browser handoff reasons

Treat the full JSON payload as source of truth; top-level shortcuts are for fast routing.