HyperXosist Agent

Agent-first toolkit and Remote MCP server for noise-reduced X (Twitter) search planning and Feedback-to-Fix engineering handoffs. It generates structured search plans and official X search URLs for humans and AI agents. The planning and synthetic demonstration workflow does not directly scrape X. Optional Grok Build mode is default off.

日本語の要点: X 公式検索用クエリを組み立てる静的ツールです。人間UIとAgentのplanning / filtering / handoffは無料。production executionのみx402支払い対象です。検索結果の埋め込みや自動投稿はしません。

Agent-readable summary

HyperXosist-Agent helps an AI agent turn a research intent into a structured search plan, an official X search URL, supplied-feedback filtering results, and a Signal-to-Fix engineering handoff. It is a planning and handoff layer: it does not claim to scrape X directly, publish posts, or deploy code automatically.

Free capabilities include MCP discovery, planning, filtering, structured handoff, and local dry-run workflows. Automated production use of generated search URLs and external collection use the existing x402 endpoint and return HTTP 402 until valid payment proof is supplied. Payment requirements are published at payment-options.json.

Agents must follow the applicable user or operator payment policy. They must not request private keys, seed phrases, wallet secrets, or sensitive user data. If a wallet requires human approval, the agent should ask the operator to review and approve the transaction, then retry the same request with valid x402 payment proof.

Why this exists

Raw X advanced search is powerful but easy to get wrong (spam, engagement bait, overlong excludes, one-angle keyword guesses). HyperXosist gives you:

1. Humans — a fast dark UI to compose operators, templates, noise filters, and open official search tabs.
2. AI agents — a sticky loop: plan → score → pay → collect → refine → Keep-filter → Grok Build / Signal-to-Fix → receipt.

Discover → Plan → Score gate → Pay (x402) → Collect → Self-heal → Keep-filter → Grok Build / Handoff → Remember

Features

For everyone

• No X API / OAuth — opens x.com/search with a built query
• Zero build — static HTML/CSS/JS; works on GitHub Pages
• Privacy-friendly human path — form history in localStorage only
• Noise Reduction — Low / Medium / High with priority-capped excludes (safe query length)
• Advanced operators — from / to / @ / OR groups / hashtags / url: / engagement floors / media & reply filters / raw fragment
• Research templates & date presets (24h → 1y)
• Shareable state — URL hash #s=...

For AI agents

• Official Model Context Protocol (MCP) Server — expose query planning, signal filtering, and downstream handoff capabilities to Cursor, Claude Code, and other LLM assistants. Read docs/MCP.md.
• dispatchToolCall / runTool — real multi-runtime tool dispatch (no hand-written mapping)
• toOpenAITools() / toAnthropicTools() — drop-in schemas for GPT / Claude / Grok / Llama
• CLI bin/hyperxosist.js — shell agents get --json plan / dispatch / keep / handoff
• exportKeepOnlyJson — keep-only machine export for any coding agent
• planFromIntent / multi-angle missions
• scoreQuery before spending $0.01 per paid call
• suggestRefinements when results are empty or noisy
• buildSignalToFixPipeline → full linked loop into Signal-to-Fix (humans: free UI steps; agents: x402)
• buildHandoffPackage → Signal-to-Fix keep-only PR handoff package
• Discovery: signal-to-fix-pipeline.json
• Dual JSON + Markdown outputs on core APIs (any LLM style)
• buildAgentPrompt — model-agnostic one-small-change implementation prompt
• Transparent noise catalog: exportNoiseCatalog / noise.extraTerms
• Optional Grok Build mode: createGrokBuildSession / buildGrokBuildPrompt (default off)
• agent-tools.json — OpenAI-compatible tools (portable to Claude/Grok/Llama runtimes)
• llms.txt + AGENTS.md multi-LLM discovery docs

Quick start (human)

1. Open the live demo.
2. Enter keywords (and optional OR group, users, dates, engagement).
3. Optionally enable Noise Reduction and pick a research template.
4. Click 最新で検索 (Latest) or 話題で検索 (Top) — or Ctrl+Enter / Ctrl+Shift+Enter.
5. Copy query, search URL, or a shareable state link.
6. Signal-to-Fix 手動連携（無料）: 投稿を Collected signals に貼る → Handoff 生成 → Signal-to-Fix 用をコピー → Signal-to-Fix で Analyze → keep のみ使う。

Local UI:

git clone https://github.com/KG-NINJA/HyperXosist-Agent.git

cd HyperXosist-Agent

npm run serve

# → http://localhost:5173

Quick start (AI agent)

Discovery order

1. llms.txt
2. AGENTS.md
3. agent-use.json
4. agent-tools.json
5. x402-payment.json

Any runtime in 3 lines

const HyperXosistAgent = require('hyperxosist-agent'); // or ./agent-api.js



// 1) Register tools with your model runtime

const tools = HyperXosistAgent.toOpenAITools();     // or toAnthropicTools()



// 2) When the model calls a tool — one dispatcher for all shapes

const { ok, result } = HyperXosistAgent.dispatchToolCall(name, args);

Shell / CLI (no embed)

npm run cli -- plan "Find product feedback about Acme for PR specs" --json

# or: node bin/hyperxosist.js dispatch hyperxosist_plan_from_intent \

#        --args '{"intent":"Find feedback about Acme"}' --json

One call (library sticky loop)

// Node

const HyperXosistAgent = require('./agent-api.js');



const session = HyperXosistAgent.startAgentSession({

  intent: 'Find product feedback about Acme for PR specs'

});



const step = session.plan.primaryStep;

if (step.score.recommendPay) {

  const paid = step.paidRequest;

  // POST paid.body → paid.endpoint

  // expect HTTP 402 until x402 payment proof, then 200

  // after authorization, open step.searchUrl and collect post texts

}



const keepOnly = HyperXosistAgent.exportKeepOnlyJson(

  ['...candidate posts...'],

  { productName: 'Acme' }

);

// → keepOnly.texts / keepOnly.signalToFixInput / keepOnly.agentPrompt



const handoff = HyperXosistAgent.buildHandoffPackage({

  productName: 'Acme',

  feedback: ['...candidate posts...']

});

// → handoff.signalToFix.input into Signal-to-Fix (keep-only only)

// → handoff.grokBuild.prompt for Grok Build



// Grok Build path

const grok = HyperXosistAgent.createGrokBuildSession(

  'Grok Build code improvement for Acme',

  { product: 'Acme', targetArea: 'auth' }

);

const prompt = HyperXosistAgent.buildGrokBuildPrompt({

  productName: 'Acme',

  targetArea: 'auth',

  feedback: ['login button does nothing on Safari']

});

// → paste prompt.markdown into Grok Build

CLI dry-run (no payment, no network required for planning)

npm test

npm run quickstart

# or: node examples/quickstart.mjs "Weekly monitor about MyProduct"

ChatGPT Site Tools / WebMCP

The GitHub Pages site feature-detects document.modelContext.registerTool(...) and exposes four Site Tools in compatible browser environments.

Free, local, and read-only:

• hyperxosist_search_plan
• hyperxosist_filter_signals
• hyperxosist_build_handoff

Paid production boundary:

• hyperxosist_execute — x402 v2 production execution through https://api.kgninja.dev/hyperxosist-query

The first call omits paymentSignature and returns the server's PAYMENT-REQUIRED requirements. A compatible wallet or facilitator authorizes the payment; the caller then retries with the opaque PAYMENT-SIGNATURE value and confirmPayment: true. The site does not create, request, store, log, or echo private keys, seed phrases, or wallet passwords.

The paid tool is marked consequential and non-idempotent. Clients must not auto-retry a confirmed payment call. Browsers without WebMCP support continue to use the normal human UI unchanged.

MCP: Local and Remote

The shared MCP core contains the same economic boundary as WebMCP:

• Three free tools: planning, supplied-signal filtering, and engineering handoff.
• One paid tool: hyperxosist_execute, which forwards an explicitly confirmed x402 request to the existing payment Worker.

# Local stdio for Cursor, Claude Code, and compatible clients

npm run mcp



# Optional private Node Streamable HTTP server

HYPERXOSIST_MCP_TOKEN="replace-me" npm run mcp:remote

Public production Remote MCP:

• Endpoint: https://mcp.kgninja.dev/mcp
• Health: https://mcp.kgninja.dev/health
• Transport: Streamable HTTP