x-monkey

A lightweight userscript panel for continuously capturing and browsing X (Twitter) GraphQL tweet data in real time.

What it does

• Intercepts supported GraphQL responses from x.com across the userscript app session.
• Parses and normalizes users, tweets, and media into an in-memory database.
• Shows a draggable/resizable Vue panel with three tabs:
  • Feature: URL-driven feature entry points backed by the accumulated in-memory database.
  • Database: full captured tweet list and entity detail views.
  • Settings: panel size, scale, theme mode, and behavior options.
• Keeps captured entities for the current page session by default; optional auto-clear is available for navigation changes.
• Uses Shadow DOM style isolation and runtime theme switching.

Tech stack

• Vue 3 + TypeScript
• Vite + vite-plugin-monkey
• Bun (runtime and package manager)

Development

bun install
bun run dev

Build

bun run build

Build output is generated in dist/ as a userscript bundle.

Remote Database Build Options

The tweet-db integration targets the current tweet-db v2 public API only:

• GET /api/v1/session
• POST /api/v1/tweet/query
• POST /api/v1/tweet/submit

Legacy tweet-db endpoints such as /api/v1/ingest/submissions and /api/v1/posts/status/query are intentionally not supported.

Runtime behavior in the userscript:

• Remote database sync is manual from the tweet detail panel.
• Refresh queries the remote state for the current tweet, author, and media.
• Sync submits the current tweet bundle.
• Sync All submits the current tweet plus visible replies when available.
• Query requires a registered tweet-db session; submit requires an administrator session.

The integration can be configured in two ways:

1. Optionally create remote-db.config.json in the project root
2. Override the same fields with Vite environment variables when needed

A tracked example is available at remote-db.config.example.json. The actual remote-db.config.json file is optional and gitignored, so it can be used for machine-local build settings.

Default repository configuration:

• enabled: true
• configurable: true
• baseUrl: ''

This means the feature is enabled by default, the Settings tab will show the remote database section, and the Base URL can be entered later if it is not fixed in the file.

Settings behavior:

• A per-user Enable remote database switch is available in Settings.
• Check applies the current draft enable state and Base URL in memory immediately.
• Save persists the enable state and Base URL to userscript storage.

Build-time fields:

• enabled
• configurable
• baseUrl

Equivalent environment variables:

• VITE_XD_REMOTE_DB_ENABLED Enables the remote database feature.
• VITE_XD_REMOTE_DB_CONFIGURABLE Allows the Base URL to be edited from the Settings tab.
• VITE_XD_REMOTE_DB_BASE_URL Compile-time default Base URL. Must be a valid absolute http(s) URL when remote mode is enabled and not configurable. May be empty only when remote mode is enabled and configurable.

Precedence:

• Environment variables override remote-db.config.json
• remote-db.config.json overrides the built-in defaults used by normal builds

Userscript @connect generation:

• When remote mode is configurable, the build keeps @connect *.
• When a compile-time remote Base URL is set, its hostname is also added to @connect.
• When remote mode is fixed to a compile-time Base URL, the build emits that hostname instead of a wildcard.

Rules enforced during build:

• VITE_XD_REMOTE_DB_CONFIGURABLE=true requires VITE_XD_REMOTE_DB_ENABLED=true.
• When remote mode is disabled, the other two variables are ignored.
• When remote mode is enabled and not configurable, VITE_XD_REMOTE_DB_BASE_URL is required.
• When remote mode is enabled and configurable, VITE_XD_REMOTE_DB_BASE_URL is optional and acts as the initial default.

Examples:

VITE_XD_REMOTE_DB_ENABLED=true \
VITE_XD_REMOTE_DB_CONFIGURABLE=false \
VITE_XD_REMOTE_DB_BASE_URL=http://127.0.0.1:3001 \
bun run build

VITE_XD_REMOTE_DB_ENABLED=true \
VITE_XD_REMOTE_DB_CONFIGURABLE=true \
VITE_XD_REMOTE_DB_BASE_URL= \
bun run build

Contract verification against the adjacent tweet-db checkout:

bun run scripts/verify-remote-db-contract.ts