Show HN: Sosumi.ai – Convert Apple Developer docs to AI-readable Markdown
Sosumi.ai converts Apple Developer documentation into AI-readable Markdown, addressing the common pain point of large language models hallucinating when trying to process Swift/SwiftUI APIs. This "Show HN" offers a practical solution to a specific LLM limitation, sparking discussions on "AI-readable" terminology and the perennial woes of proprietary documentation. It's a clever hack that makes Apple's notoriously JavaScript-heavy docs digestible for modern AI tools.
The Lowdown
Sosumi.ai is a novel service designed to bridge the gap between Apple Developer documentation and large language models (LLMs). The creator, _mattt, built it out of frustration with LLMs like Claude struggling to accurately process Swift and SwiftUI APIs, primarily because Apple's documentation is rendered via JavaScript, making it opaque to many AI tools that simply see blank pages when fed direct URLs.
- The service allows users to convert any Apple Developer documentation page to clean Markdown by simply swapping
developer.apple.comwithsosumi.aiin the URL. - Under the hood, Sosumi.ai is a lightweight Hono app running on Cloudflare Workers, which fetches the original structured JSON data from Apple's docs and renders it into a machine-readable Markdown format.
- It operates on an accessibility-first, on-demand basis, converting pages only when requested, and adheres to strict disclaimers, including rate limiting, no bulk downloading, and no permanent archives, to ensure compliance and avoid imposing undue load on Apple's servers.
- The project also offers an MCP (Multi-purpose Client Protocol) interface with a search tool for the Apple developer website.
- The author plans to open-source the project, allowing for self-hosting, and has already implemented a feature to render the Markdown as simple HTML for human readability based on user feedback.
Sosumi.ai offers a pragmatic solution for developers looking to leverage AI tools more effectively with Apple's ecosystem, sidestepping the current limitations of LLMs and the challenges posed by JavaScript-rendered documentation. It highlights the ongoing struggle with documentation accessibility in the AI era.
The Gossip
Lexical Lingering: "AI-Readable" or Just "Readable"?
A significant point of contention was the term "AI-readable Markdown." Some commentators argued that Markdown is inherently machine-readable, and appending "AI-readable" unnecessarily "taints" the term, implying a distinction that shouldn't exist for well-formatted data. Others defended the term, noting that the author's explicit goal was to make the content accessible to AI, which might struggle with JS-rendered pages even if "human-readable," thus the "AI" prefix clarifies the *why*.
Cognitive Conundrums: LLMs and Niche Languages
Many users resonated with the author's frustration regarding LLMs' performance with Swift and SwiftUI. While some noted that more advanced models like GPT-4 (or newer versions) handle Swift/Objective-C better, the general consensus was that LLMs often struggle with less popular languages or frameworks, especially when source material is obscured by complex web rendering. The discussion touched upon the difficulties coding agents face when documentation isn't readily parsable.
Documentation Despair: Apple's Archival Ails
Commenters widely praised the utility of Sosumi.ai, particularly those actively developing iOS apps, highlighting how it alleviates a common pain point. This led to a broader discussion on Apple's documentation practices, lamenting the lack of easily downloadable or machine-readable documentation sets, a feature that existed in the past. The service was also appreciated for improving general accessibility for screen reader users and aligning with "Small Web" principles.
Repository Reluctance: Public Code's Perils
When asked about a public repository, the author stated plans to open-source it after some tidying. This sparked a tangential debate on why developers often delay making repos public. Reasons cited included fear of criticism, "magic numbers" in hobby projects, not wanting to deal with "entitlement" or future obligations from open-source users, and the general discomfort of sharing work-in-progress. Others countered that code shouldn't be a secret and that immediate public sharing is beneficial.