{"id":50559858,"url":"https://github.com/rs/appclipcode","last_synced_at":"2026-06-04T11:01:40.266Z","repository":{"id":350753523,"uuid":"1208127435","full_name":"rs/appclipcode","owner":"rs","description":"App Clip Code Reverse Engineered","archived":false,"fork":false,"pushed_at":"2026-04-11T22:41:52.000Z","size":1292,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T23:26:25.505Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T21:20:55.000Z","updated_at":"2026-04-11T23:25:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rs/appclipcode","commit_stats":null,"previous_names":["rs/appclipcode"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rs/appclipcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fappclipcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fappclipcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fappclipcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fappclipcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rs","download_url":"https://codeload.github.com/rs/appclipcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rs%2Fappclipcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33901305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T11:01:39.357Z","updated_at":"2026-06-04T11:01:40.255Z","avatar_url":"https://github.com/rs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# App Clip Codes, Reverse Engineered\n\n\u003cimg src=\"doc/demo.svg\" width=\"200\" align=\"right\"\u003e\n\n`appclipcode` provides Go and JavaScript/TypeScript implementations of Apple's\nApp Clip Code format.\n\nApple ships those circular App Clip Codes, but does not document the format.\nThis repo reverse engineered the full pipeline and rebuilt it in JavaScript and\nGo.\n\nThe JS lib can generate App Clip Codes directly in the browser. The Go version\ncan generate, decode, and scan them from images. Both match Apple's generator\non accepted URLs.\n\nIt can:\n\n- generate App Clip Code SVGs from accepted `https://` URLs\n- reproduce Apple's URL compression bit-for-bit for generator-accepted URLs\n- render the circular code, including palette templates\n- decode URLs back from SVGs\n- decode from raster images through the CLI and `ReadImage`\n\nThe reverse-engineering write-up lives in [doc/SPEC.md](./doc/SPEC.md).\n\n## Why I Built This\n\nI got interested in this while working on App Clip invocation flows.\n\nEver played a Netflix game on a TV and paired your phone as the controller? That seamless pairing flow used an App Clip on iPhone, but the code on screen had to be a normal QR code because the controller device might be Android and App Clip Codes are Apple-only. Each pairing session needed its own invocation URL, so the QR code had to be generated dynamically.\n\nLater I was prototyping an iPhone-only install-and-configure flow for NextDNS. Same general problem, but without the cross-platform constraint. A QR code would still have been perfectly sufficient. That made App Clip Codes completely unnecessary and therefore irresistible.\n\nThat turned into a reverse-engineering project.\n\n## Implementations\n\nThis repository currently includes two implementations:\n\n- Go: the main library and CLI in the repository root, with generation,\n  SVG decoding, and raster-image scanning support\n- JavaScript / TypeScript: the package in [`js/`](./js), focused on the\n  encoder path and SVG generation, usable directly in the browser, with a\n  local `appclipcode` CLI\n\n## What Was Hard\n\nRendering the rings was the easy part. The hard part was matching Apple's actual encoding and validation rules:\n\n- host format selection\n- template-word paths\n- combined vs segmented non-template encoding\n- segmented path/query subtype selection\n- generator-compatible URL validation\n- the 128-bit payload limit\n\nIn the end, the format turned out to be a mix of fairly standard building\nblocks, especially multi-context Huffman coding driven by Apple-trained\nfrequency tables, combined with very Apple-specific host tables, path\nwordbooks, and URL acceptance rules.\n\nThose constraints are also why App Clip Codes are not a very good generic QR\ncode replacement: they are iOS-only, accept only a narrow subset of URLs, and\ndepend on a compression scheme with a tight payload budget plus App Clip-specific\nfrequency tables, host tables, and wordbooks.\n\n## LLMs and Reverse Engineering\n\nThe LLMs did most of the brute-force exploration. My job was to decide what to test next, supply hypotheses, reject fake progress, and turn the result into a sound implementation. The loop was fairly mechanical: use Apple's generator as the oracle, generate lots of examples, diff outputs, propose a rule, then try to break it with tests.\n\nClaude with Opus 4.6 1M got about halfway there and then failed in a very instructive way. Instead of recovering the missing behavior, it introduced a large hardcoded table of precomputed encodings and then tried to validate the result with tests derived from those same hardcoded answers. It looked like progress until it had to explain what it was actually doing.\n\nCodex with GPT-5.4 at high reasoning was much better at closing the gap. My takeaway is that LLMs can be genuinely useful for reverse engineering if they are doing hypothesis generation under a test harness. Left alone, they are also perfectly capable of building an impressive-looking lie.\n\n## Status\n\nThe generator path is reverse engineered and matches Apple's `AppClipCodeGenerator` for accepted URLs.\n\nThat includes:\n\n- host format selection\n- template-word paths\n- combined vs segmented non-template encoding\n- segmented path/query subtype selection\n- generator-compatible URL validation and the 128-bit payload limit\n\n## Getting Started\n\n### Go\n\nInstall:\n\n```bash\ngo get github.com/rs/appclipcode\ngo install github.com/rs/appclipcode/cmd/appclipcodegen@latest\n```\n\nCLI example:\n\n```bash\nappclipcodegen gen https://example.com -o code.svg\n```\n\nMore details: [doc/GODOC.md](./doc/GODOC.md)\n\n### JavaScript / TypeScript\n\nInstall:\n\n```bash\nnpm install appclipcode\n```\n\nCLI example:\n\n```bash\nnpx appclipcode https://example.com --index 0 -o code.svg\n```\n\nThe JS library can also run directly in the browser; only the CLI is Node-specific.\n\nMore details: [js/README.md](./js/README.md)\n\n## Reverse-Engineering Notes\n\nThe full write-up is in [doc/SPEC.md](./doc/SPEC.md).\n\nSome of the more useful findings:\n\n- SPQ and CPQ are standard trie-context Huffman coders\n- the non-template selector is `0 = combined`, `1 = segmented`\n- segmented mode is a real grammar with typed path and query components\n- host format `1` uses a much larger fixed-TLD table than early partial extraction suggested\n- the generator validates URL text differently from raw `URLCompression.framework`\n- `AppClipCodeGenerator` rejects URLs whose compressed payload exceeds 128 bits, even though the lower-level framework can emit longer raw bitstreams\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](./LICENSE).\n\n## Disclaimer\n\nThis project is an independent, unofficial implementation of the App Clip Code format. It is not affiliated with, authorized by, endorsed by, sponsored by, or otherwise approved by Apple Inc.\n\nApple, App Clips, and App Clip Code are trademarks of Apple Inc., registered in the U.S. and other countries and regions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frs%2Fappclipcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frs%2Fappclipcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frs%2Fappclipcode/lists"}