Skip to content
Back to search

x-md

Turn public X posts, profiles, and search into compact Markdown or JSON for agents. Hosted at x.pcstyle.dev.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/pc-style/x-md with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/pc-style/x-md'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pc-style--x-md/badge.svg)](/listings/pc-style--x-md)

HTML

<a href="/listings/pc-style--x-md"><img src="/api/listings/pc-style--x-md/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 273 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # x.md
  2. Turn public X posts, conversations, profiles, search results, and social graphs into compact Markdown for agents. The hosted API is available at [mdfromx.com](https://mdfromx.com); no X API key is required for the default provider path.
  3. > [!IMPORTANT]
  4. > **Status: beta.** Routes and output fields can change as upstream X providers change. The compatibility target for self-hosting is Bun 1.4 (see `.bun-version`) and the locked dependencies in this repository.
  5. **Not affiliated with X Corp. Public lists are not available.**
  6. ## What it returns
  7. - Compact, agent-friendly Markdown by default; add `?full=true` for dates, metrics, and richer profile details.
  8. - A source URL for every post and reply, including quoted posts.
  9. - Direct video URLs, thumbnails, duration/dimensions/bitrate when supplied, and all available video variants.
  10. - Conversation context by default: parents, the author's thread, and top replies. Use `context` and `replies` to narrow it.
  11. - Structured JSON with the rendered Markdown and raw post/profile data via `?format=json` or `Accept: application/json`.
  12. - Profiles with profile data and up to 20 latest original posts by default.
  13. - Search, followers, and following, with cursor or bounded page pagination.
  14. ## Use the hosted API
  15. Replace `x.com` with `mdfromx.com` on a public status URL:
  16. ```text
  17. https://x.com/handle/status/1234567890
  18. https://mdfromx.com/handle/status/1234567890
  19. ```
  20. ```bash
  21. curl -sS -H 'Accept: text/markdown' \
  22. 'https://mdfromx.com/handle/status/1234567890'
  23. curl -sS -G 'https://mdfromx.com/api/v1/posts' \
  24. --data-urlencode 'url=https://x.com/handle/status/1234567890'
  25. ```
  26. Browsers that request HTML get a readable page containing the Markdown. Agents can explicitly request `text/markdown`. Discord, Telegram, Slack, and other preview bots receive Open Graph embed HTML for the same status URL, including multiple images on Discord, video streams where supported, video thumbnails on Slack, quote/poll text, and an oEmbed engagement line.
  27. ## For agents
  28. Everything here is public, needs no key, and is meant to be read by a program:
  29. | Surface | Where | What it is |
  30. | --- | --- | --- |
  31. | Markdown negotiation | any read route, or `/`, `/docs`, `/about` | `Accept: text/markdown` returns Markdown; docs pages also answer to a `.md` suffix or `?mode=agent`. Responses carry `Vary: Accept` and a `Link: …; rel="alternate"` to the Markdown twin |
  32. | `/llms.txt` | [mdfromx.com/llms.txt](https://mdfromx.com/llms.txt) | What x.md is for, when *not* to use it, and every route, in one text file |
  33. | `/openapi.json` | [mdfromx.com/openapi.json](https://mdfromx.com/openapi.json) | OpenAPI 3.1: parameters, response schemas, error bodies, quotas, lifecycle |
  34. | `/api` | [mdfromx.com/api](https://mdfromx.com/api) | A small JSON index for an agent that has only the domain |
  35. | `/mcp` | [mdfromx.com/mcp](https://mdfromx.com/mcp) | MCP server over Streamable HTTP, exposing the same reads as tools |
  36. | Agent skill | `bunx skills add pc-style/x-md -g -y --skill browse-x` | The `browse-x` skill for coding agents |
  37. | `/.well-known/ard.json` | [mdfromx.com/.well-known/ard.json](https://mdfromx.com/.well-known/ard.json) | Agentic Resource Discovery catalog of every machine surface above |
  38. Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents (`application/problem+json`) with a stable machine `code`, a human `detail`, and a `resolution` hint — see the [error catalogue](https://mdfromx.com/docs/errors). Rate limits are advertised on every response with the IETF `RateLimit-Policy` and `RateLimit` structured fields plus the `RateLimit-Limit`/`-Remaining`/`-Reset` compatibility triple, and `Retry-After` on a `429`.
  39. ### Versioning
  40. `/api/v1/*` is the stable machine surface: `/api/v1/posts`, `/api/v1/profiles/{handle}` (`/followers`, `/following`), `/api/v1/search`, `/api/v1/oembed`. Additive changes ship inside `v1`; breaking ones ship as a new path prefix, and `v1` keeps working for at least 12 months after a successor appears. The permalink routes (`/{handle}`, `/{handle}/status/{id}`, `/search`, `/oembed`) are the unversioned product surface and are not deprecated.
  41. `GET /api/convert` and `GET /api/browse` are aliases scheduled for deprecation on **2026-09-15**, with a **2027-09-15** sunset. They still work unchanged and already announce the schedule on every response:
  42. ```http
  43. Deprecation: @1789430400
  44. Sunset: Wed, 15 Sep 2027 00:00:00 GMT
  45. Link: <https://mdfromx.com/api/v1/posts>; rel="successor-version"
  46. ```
  47. Full policy: [mdfromx.com/docs/versioning](https://mdfromx.com/docs/versioning).
  48. ## Post conversion
  49. Both `GET /:handle/status/:id` and `GET /api/v1/posts?url=…` support:
  50. | Parameter | Default | Supported values |
  51. | --- | --- | --- |
  52. | `format` | `markdown` | `markdown`, `obsidian`, `json` |
  53. | `full` | false | `true`, `1`, or `yes` enables expanded Markdown; Obsidian is always expanded |
  54. | `thread` | `full` | `off`, `full`, `conversation`, or a limit from `2` to `100` |
  55. | `context` | `full` | `full` includes parents, author thread, and selected replies; `thread` excludes unrelated replies |
  56. | `replies` | `top` | `top`, `recent`, `off` |
  57. | `userinfo` | `off` | `off`, `author`, `all` |
  58. | `nocache` | false | `true`, `1`, or `yes` bypasses the application cache |
  59. `thread=off` returns only the requested post. The default conversation result is ordered and labels posts as parent, post, thread, or reply when that data is available. Provider fallbacks can return less context, article content, or quote data.
  60. ```bash
  61. # Expanded conversation without replies
  62. curl -sS 'https://mdfromx.com/handle/status/1234567890?full=true&replies=off'
  63. # Author thread only, capped at 20 posts
  64. curl -sS 'https://mdfromx.com/handle/status/1234567890?context=thread&thread=20'
  65. # Structured output
  66. curl -sS -H 'Accept: application/json' \
  67. 'https://mdfromx.com/handle/status/1234567890'
  68. curl -sS 'https://mdfromx.com/handle/status/1234567890?format=json'
  69. ```
  70. JSON conversion responses contain `url`, `markdown`, raw `posts`, `compact`, `warnings`, `postCount`, `source`, `cache`, and `format`. Media in both Markdown and `posts` includes direct video data when the upstream provider exposes it; availability and lifetime of X CDN URLs are controlled by X.
  71. Preview bots hitting `GET /:handle/status/:id` receive embed HTML instead of Markdown. `GET /oembed` is the Discord oEmbed document advertised from that HTML. Explicit `?format=` or `Accept: application/json` / `text/markdown` still wins over user-agent detection.
  72. ## Browse profiles and X
  73. Browse routes return compact Markdown by default and structured data with `?format=json` or `Accept: application/json`.
  74. | Route | Behavior |
  75. | --- | --- |
  76. | `GET /:handle` | Profile data and latest original posts (replies and reposts filtered out) |
  77. | `GET /search?q=…` | Search posts or users; `feed=latest`, `top`, `photos`, `videos`, or `users` (`media` aliases `photos`) (invalid values fall back to `latest`) |
  78. | `GET /:handle/followers` | Followers |
  79. | `GET /:handle/following` | Accounts followed |
  80. The default `limit` is 20 and the maximum is 100; every page is cut exactly at `limit` (search feeds served by own accounts answer 20). Pass the opaque `cursor` returned as `nextCursor` — there is no ceiling on a cursor chain — or use `page=1` through `page=10`; values above 10 are clamped. Profile reads return original posts unless `with_replies=true` / `with_reposts=true` is set, and `until=<date>` jumps straight to a date. Search takes `since` and `until`.
  81. ```bash
  82. curl -sS 'https://mdfromx.com/elonmusk'
  83. curl -sS 'https://mdfromx.com/search?q=typescript&feed=latest&limit=20'
  84. curl -sS 'https://mdfromx.com/elonmusk/followers?full=true'
  85. curl -sS -H 'Accept: application/json' \
  86. 'https://mdfromx.com/elonmusk/following?limit=20'
  87. ```
  88. ### Versioned browse routes
  89. ```bash
  90. curl -sS 'https://mdfromx.com/api/v1/profiles/elonmusk'
  91. curl -sS -G 'https://mdfromx.com/api/v1/search' \
  92. --data-urlencode 'q=typescript' \
  93. --data-urlencode 'feed=top' \
  94. --data-urlencode 'format=json'
  95. ```
  96. The older `GET /api/browse?resource=profile|search|followers|following` alias takes the same options and still works, but it is deprecated and sunsets on 2027-09-15.
  97. Search feeds are case-insensitive. `users` returns account profiles in `users`; other feeds return `posts`. Latest and Top try FxTwitter first, then a custom-built live search provider, and can fall back to web-indexed snippets. Photos, Videos, and Users use the live provider directly.
  98. ### Search limits
  99. - Live search allows **5 uncached requests per minute per IP**. Cache hits are free.
  100. - Requests served by the live provider have an additional allowance of **10 per IP per 15-minute window**, drawn from a shared public pool. All feeds share it, and each page of a page walk counts as one request.
  101. - A rejected request returns `429` with `Retry-After` in seconds until the window resets. An upstream outage returns `503` with `Retry-After: 30`.
  102. Every response advertises what is left, so a client can pace itself instead of discovering the limit by hitting it:
  103. ```http
  104. RateLimit-Policy: "api-ip";q=600;w=60, "search-ip";q=5;w=60, "account-ip";q=10;w=900
  105. RateLimit: "api-ip";r=599;t=60, "search-ip";r=5;t=60, "account-ip";r=10;t=900
  106. RateLimit-Limit: 5
  107. RateLimit-Remaining: 5
  108. RateLimit-Reset: 60
  109. ```
  110. `q` is the quota, `w` the window in seconds, `r` what is left, `t` the seconds until that window resets. The unprefixed `RateLimit-Limit`/`-Remaining`/`-Reset` triple describes the tightest policy. Ignore these values on a response with a positive `Age`: a CDN hit replays the state of whoever filled the cache.
  111. Counters are per instance unless a shared KV store is configured.
  112. Browse JSON includes the resource-specific `profile`, `posts`, or `users`, plus `page`, `limit`, optional `nextCursor`, rendered `markdown`, and cache status. The verified upstream profile API does not expose pinned-post markers, and public X lists are explicitly unsupported.
  113. ## Import a post history
  114. `GET /{handle}/posts` returns an account's history in bulk — thousands of posts, replies included, raw JSON, in seconds:
  115. ```bash
  116. curl -sS 'https://mdfromx.com/paulg/posts?since=2025-09-01&max_posts=2000'
  117. curl -sN 'https://mdfromx.com/paulg/posts?since=2026-06-01&format=ndjson' # stream
  118. curl -sS 'https://mdfromx.com/paulg/posts?index=true' # what is archived already
  119. ```
  120. X hands out a timeline one cursor at a time; x.md mints cursors for arbitrary instants and walks many chains at once, then stores what it collected so the next import only fetches the gap. Measured: 1379 posts in 7.8 s at `concurrency=32` against the public upstream, 8× a sequential walk at equal completeness ([bench/RESULTS-scale.md](bench/RESULTS-scale.md)). Parameters: `since`, `until`, `max_posts` (≤5000), `with_replies`, `with_reposts`, `only_replies`, `concurrency` (≤32 per upstream), `format=json|ndjson`, `refresh`, `index`. Full guide: [Import a post history](https://mdfromx.com/docs/bulk-import).
  121. ## Agent skill
  122. Install the hosted skill, `browse-x`, with the [skills CLI](https://skills.sh/):
  123. ```bash
  124. bunx skills add pc-style/x-md -g -y --skill browse-x
  125. ```
  126. The skill uses `https://mdfromx.com`; it does not require a local checkout or local API keys. Its helper is a TypeScript CLI (`bun skills/browse-x/scripts/browse-x.ts …`) that needs Bun, and exits with code 3 on a rate limit after printing `Retry-After`, so agents know exactly how long to wait.
  127. The skills CLI command follows the repository's current default branch. For a reviewable, immutable copy, check out the newest tag on the [releases page](https://github.com/pc-style/x-md/releases) and copy `skills/browse-x` from that checkout.
  128. ## Caching and reliability
  129. FxTwitter is the primary data provider and X's syndication endpoint is the fallback. Self-hosted deployments may additionally configure Context.dev and Firecrawl. `X-Source` reports `fxtwitter`, `syndication`, `contextdev`, or `firecrawl`; `X-Cache` reports cache status. Browse endpoints use FxTwitter directly.
  130. Successful post conversions are cached for about one hour by default (`CACHE_TTL_SECONDS=3600`). Browse results are cached for 30 minutes (profiles), 10 minutes (search and replies), or 6 hours (followers and following). Both send cache headers unless bypassed. `nocache=true` bypasses the application cache, but it cannot bypass upstream caches. Public X data can be missing, delayed, rate-limited, deleted, protected, or shaped differently by upstream providers, so context, counts, media variants, and pagination cursors are best effort. The API does not authenticate to private accounts and does not provide public lists.
  131. ## Trust and privacy boundaries
  132. - The hosted service receives the public X URL, handle, or search query you request and sends it to FxTwitter or X's public syndication service. Successful results are cached for up to about one hour (follower lists up to 6 hours) and can be served to other callers requesting the same public resource.
  133. - Optional Context.dev and Firecrawl fallbacks are disabled unless a self-hosted operator configures their API keys. When enabled, the public X URL is sent to that provider.
  134. - The hosted `browse-x` skill sends its arguments to `mdfromx.com`. Do not put secrets or private-account information in URLs or search terms.
  135. - Optional, disabled-by-default PostHog dataset capture archives allowlisted structured public results, not just metrics. See the [archive/privacy policy](internal/archive.md) for actor pseudonyms, opt-out controls, retention duties, and delivery limits.
  136. - Media links point to upstream X/FxTwitter CDNs. Fetching those links is outside x.md's cache and privacy boundary.
  137. x.md is read-only and does not accept X credentials, post content, or account mutations. It is the canonical implementation, has no successor, and is not affiliated with X Corp.
  138. ## Self-host
  139. ```bash
  140. git clone --depth 1 https://github.com/pc-style/x-md.git
  141. cd x-md
  142. bun install --frozen-lockfile
  143. cp .env.local.example .env.local
  144. bun run dev
  145. ```
  146. That clones `main`, which is the moving target. For a reviewable source snapshot, clone with `--branch` and the newest tag from the [releases page](https://github.com/pc-style/x-md/releases) — the hosted API runs the newest tag — and keep the lockfile. No container image or deployment artifact is published; you deploy the source.
  147. Optional environment variables:
  148. | Variable | Description |
  149. | --- | --- |
  150. | `CONTEXT_DEV_API_KEY` | Context.dev converter fallback |
  151. | `X_SEARCH_SESSIONS_JSON` | Configuration for the live search provider; the expected shape is defined in `lib/xsearch.ts`. Locally, the gitignored `accounts.local.json` is read instead. Without it, Photos, Videos, and Users return `503` |
  152. | `KV_REST_API_URL` / `KV_REST_API_TOKEN` | Optional Upstash/Vercel KV REST endpoint (or `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`) for shared rate-limit counters, the per-account post archive, and durable app state. Falls back to per-instance memory |
  153. | `FXTWITTER_BASE_URL` | Optional upstream override: one FxEmbed base URL or a comma-separated pool. Requests rotate across the pool and a throttled base sits out its `Retry-After`. Default `https://api.fxtwitter.com` |
  154. | `FIRECRAWL_API_KEY` | Firecrawl converter fallback and degraded `/search` fallback (web-indexed x.com snippets, `X-Source: firecrawl`, `X-Search-Degraded: true`) when live X search is down |
  155. | `TRUSTED_PROXY_HOPS` | Off Vercel, the number of your own proxies that append to `X-Forwarded-For`; per-IP quotas key on the entry that many hops from the right. Default `1`. On Vercel the edge-set `X-Vercel-Forwarded-For` (then `X-Real-IP`) is used instead |
  156. | `CACHE_TTL_SECONDS` | Post conversion cache TTL; default `3600` |
  157. | `CACHE_DISABLED` | Set to `1` to disable caching |
  158. | `CACHE_PERSIST` | Set to `0` for memory-only caching |
  159. Deploy with Vercel after `bun run build`; `vercel.json` configures `dist`, the API handlers, and all public route rewrites.
  160. ### Page weight
  161. The landing, content and docs pages share one budget, measured from the built `dist/` under Lighthouse's Slow 4G profile (1.6 Mbps, 150 ms RTT) with a 4x CPU slowdown:
  162. | page | render-blocking (brotli) | requests before first paint | median LCP |
  163. |---|---|---|---|
  164. | `/` | 28.6 kB | 6 | 548 ms |
  165. | `/about` | 26.5 kB | 6 | 432 ms |
  166. | `/docs` | 160.1 kB | 37 | 868 ms |
  167. The docs row is every face the build declares, Satoshi and IBM Plex Mono; a browser only fetches the ones a page renders (45 kB there). Webfonts are the largest single item and are self-hosted subsets; `bun run fonts:build` re-subsets them and `bun run fonts:check` verifies the committed files offline.
  168. Reproduce it with:
  169. ```sh
  170. bun run build
  171. bun bench/frontend-load.ts # static budget from dist/
  172. node bench/frontend-trace.mjs --runs 11 # throttled LCP/TBT, cold cache
  173. node bench/frontend-trace.mjs --compare before,dist --runs 11 # before vs after
  174. node bench/frontend-shots.mjs --out /tmp/shots --label current # for a pixel diff
  175. ```
  176. `--dist <dir>` points any of them at a saved copy of `dist/`, so a before/after comparison runs the same code twice. The two Chromium harnesses resolve Playwright from `PLAYWRIGHT_MODULE` so the repo's dependency tree stays untouched.
  177. ## Project layout
  178. ```text
  179. api/convert.ts Post conversion handler
  180. api/browse.ts Profile, search, followers, and following handler
  181. api/oembed.ts Discord oEmbed JSON for chat previews
  182. lib/ Providers, rendering, pagination, cache, and embeds
  183. src/ Vite landing page and rendered documentation
  184. bench/ Page-weight benchmarks for the public pages
  185. ```
  186. ## License
  187. [MIT](LICENSE)
  188. ## Documentation
  189. Docs are MDX pages in `docs/`, built with Blume and mounted at `/docs`. Run `bun run docs:dev` for the documentation server. `bun run build` builds docs first, then the landing page into the same `dist` directory. Configure navigation and site metadata in `blume.config.ts`; `theme.css` maps the shared `src/tokens.css` palette into Blume.
  190. ## Contributing
  191. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks, and PR expectations, and [SECURITY.md](SECURITY.md) for private vulnerability reports.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.