Dexthemes

DexThemes

> The theme gallery for Codex. Browse, preview, and hand off beautiful themes to Codex in a couple of clicks.

dexthemes.com · Theme collections · Guides · @DexThemes

---

What it does

• Browse 100+ themes across anime, video games, movies, comics, zodiacs, and more
• Live preview — see how each theme looks with real code, dark and light variants side by side
• Theme details — switch the center workspace from the faux chat to a complete palette, source, and import view
• Indexable public pages — every valid theme variant has a canonical details page with a rendered preview and related themes
• Codex handoff — copies the import string and opens Codex Settings for you
• Create your own — the built-in theme builder lets you design and share custom themes
• Color Me Lucky — random theme generator with 6 color harmonies and ~5000+ name combos
• Community themes — sign in with GitHub and submit your creations
• Leaderboard — daily, weekly, monthly, and all-time creator rankings
• Codex plugin — discover, create, preview, apply, publish, and collect themes without leaving the conversation
• Voice-friendly creation — turn a spoken idea, fandom, event, or personality prompt into a named dark/light theme
• GitHub feedback — prepare a best-effort redacted GitHub Issue for exact review without silently posting it

Quick start

Static site frontend with a generated, hashed app shell.

git clone https://github.com/daeshawnballard/dexthemes.git
cd dexthemes
npm install
npm run build
python3 -m http.server 4173

Open http://127.0.0.1:4173/ and you're in.

dist/ is generated by npm run build and is intentionally not committed to the repository. Root-served static files like manifest.json, robots.txt, sitemap.xml, llms*.txt, and the app icons are sourced from public/ and emitted to the deploy root during the build.

Read this first

• [Architecture guide](docs/ARCHITECTURE.md)
• [Contributing guide](CONTRIBUTING.md)
• [Open source readiness plan](docs/OPENSOURCEREADINESS.md)
• [API guide](docs/API.md)
• [Codex plugin guide](docs/PLUGIN.md)
• [Content authoring guide](docs/CONTENT.md)
• [Indexable pages design concept](docs/INDEXABLE-PAGES-DESIGN-CONCEPT.md)
• [Reusable design prompts](docs/INDEXABLE-PAGES-DESIGN-PROMPTS.md)
• [Implementation prompt](docs/INDEXABLE-PAGES-IMPLEMENTATION-PROMPT.md)
• [OpenAI Build Week 2026 notes](docs/BUILD-WEEK-2026.md)

Project structure

index.html                 → App shell
templates/                 → Source templates for the generated shell and service worker
  index.template.html      → Source template for the generated shell
  sw.template.js           → Source template for the generated service worker
styles/                    → CSS split by domain (tokens, layout, sidebar, preview, builder, mobile, overlays)
  index.css                → Manifest entry for domain-scoped stylesheets
public/                    → Source-of-truth static files emitted to the deploy root during build
  manifest.json            → PWA manifest source
  robots.txt               → Search crawler directives
  sitemap.xml              → Generated static sitemap fallback; /sitemap.xml is live at runtime
  public-pages.css         → Server-rendered theme, guide, and collection page styles
  llms.txt                 → Agent-facing summary docs source
  llms-full.txt            → Full agent-facing docs source
  favicon.svg              → Root favicon source
  apple-touch-icon.png     → iOS home-screen icon source
  icon-192.png             → PWA icon source
content/                   → Markdown source for public guides, features, articles, and reference
  guides/                  → Task and troubleshooting guides
  features/                → Shipped product capability pages
  articles/                → Comparisons and editorial methodology
  reference/               → Stable technical contracts
src/                       → Frontend source modules
  main.js                  → App entry point
  preview-shell.js         → Preview rendering, shell, and window controls
  preview-actions.js       → Preview-side effects, unlock actions, and external handoffs
  preview-chat.js          → Preview delighters, handoff cards, system prompts
  preview-attribution.js   → Theme attribution and reporting UI
  theme-details.js         → In-app Chat preview / Theme details workspace switch
  theme-contracts.js       → Pure theme-shape helpers and import-string builder
  theme-attribution-model.js → Pure author attribution rules
  api.js                   → Frontend API client compatibility barrel
dist/assets/               → Generated hashed frontend build output served in production (not committed)
scripts/build.mjs          → Build pipeline for hashed assets + shell generation
scripts/generate-content.mjs → Validates Markdown and builds the shared content catalog
theme-data/dexthemes/      → Theme packs organized by category
  helpers.js               → createDexTheme() and registerDexThemesPack()
  anime.js                 → Anime-inspired themes (Bleach, Naruto, JJK, etc.)
  games.js                 → Video game themes
  movies.js                → Movie-inspired themes
  comics.js                → Comic book themes
  zodiacs.js               → Zodiac sign themes
  lunar.js                 → Lunar animal themes
  originals.js             → Original DexThemes designs
  liger-zero.js            → Liger Zero pack (Zoids)
  supporter.js             → Unlockable themes
convex/                    → Backend (Convex) — auth, likes, community themes, IndexNow
  schema.ts                → Database schema
  users.ts                 → User management and sessions
  likes.ts                 → Like/unlike system
  themes.ts                → Community theme submissions and publication scheduling
  indexNow.ts              → IndexNow publication notification action
  http.ts                  → HTTP route composition entrypoint
api/                       → Vercel edge/serverless endpoints (catalog, public pages, OG, sitemap)
  share.js                 → Server-rendered canonical theme pages with real 404 handling
  content-page.js          → Answer-first editorial, reference, and collection pages
  sitemap.js               → Live static + community catalog sitemap
  mcp.js                   → Stateless MCP endpoint for the DexThemes plugin
server/                    → MCP tools, theme creation/validation, generated app resource
mcp-app/                   → Interactive Apps SDK theme cards and previews
plugins/dexthemes/         → Installable Codex plugin manifest, MCP config, assets, and skill
docs/themes.schema.json    → JSON schema for theme submissions
docs/theme-submission-example.json → Example contribution payload

Theme format

Codex themes use this import string format:

codex-theme-v1:{"codeThemeId":"codex","theme":{"accent":"#0169cc","contrast":60,"fonts":{"code":null,"ui":null},"ink":"#fcfcfc","opaqueWindows":true,"semanticColors":{"diffAdded":"#00a240","diffRemoved":"#e02e2a","skill":"#b06dff"},"surface":"#111111"},"variant":"dark"}

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to submit themes, report bugs, and set up the backend locally.

If you want a small place to start, prefer issues labeled good first issue or help wanted. The intended early-contributor surface is theme packs, docs, pure helpers, and focused UI polish rather than auth or deployment plumbing.

Backend

The backend runs on Convex and handles:

• GitHub OAuth with one-time browser-bound state and PKCE S256
• GitHub-authenticated agent/API key issuance with SHA-256 hash-at-rest
• OAuth 2.1 resource-server support for the plugin, with GitHub as the upstream login
• Browser session management (HttpOnly same-site cookies in production, token handoff only for localhost/dev)
• Community theme submissions and moderation
• IndexNow notification after a community theme is published
• Like/unlike with canonical theme resolution and optimistic UI
• Apply tracking
• Color Me Lucky API endpoints
• Plugin-bound stats, unlocks, and confirmed community submissions

Copy [.env.example](.env.example) to .env.local to get started. All secrets live in Convex environment variables — nothing is committed to the repo.

Dependency Note

DexThemes is built on top of Codex theme import and settings behavior that this repo does not control. That is an intentional tradeoff for the project: the codebase is maintainable on its own terms, but Codex compatibility can still shift independently of DexThemes.

Security

• OAuth state values are cryptographically random, single-use, time-limited, bound to the initiating browser, and bound to PKCE S256 verifiers
• Session tokens are 256-bit cryptographically random hex strings
• New agent/API keys are stored only as SHA-256 digests and shown once
• MCP identity is derived from a verified JWT; tools never accept a user or owner ID
• MCP JWTs require a valid signature, issuer, audience, scope, and expiry; identity and network quotas are enforced independently
• Theme IDs and palettes are checked against the canonical static catalog, and every color is validated before storage, preview, or apply
• Monthly ranking achievements require unique signed-in non-author adoptions; raw copy analytics alone cannot unlock them
• Daily and weekly #1 results are finalized on closed UTC periods. Repeat winners keep every win in their stats, while the Golden Hour and Headliner reward themes unlock only once per account.
• Supporter-wall listing is explicit opt-in and independent from Patron access
• Public achievement claims are limited to client-observable actions; account, theme, leaderboard, plugin, and employee unlocks are derived server-side
• Credentialed account CORS is origin-gated; public and explicit Bearer-token routes are separated from cookie-backed writes
• User-controlled strings in HTML templates are escaped, while the MCP app renders tool data through DOM textContent
• No secrets in the codebase — environment variables only

Validation

Use the contributor-safe validation path before opening a PR:

npm run validate

That runs the lightweight contract tests, documentation checks, and production build.

Plugin-specific preflight:

python3 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py plugins/dexthemes
npm audit

The MCP contract tests verify every exposed tool has an outputSchema and explicit readOnlyHint, openWorldHint, and destructiveHint values.

For visible-flow browser coverage, run:

npm run smoke:browser

The app records theme-page referrals, Theme details views, canonical shares, and import handoffs as separate analytics events so discovery can be measured independently from conversion.

Support

DexThemes is free and open source. If it's useful to you:

• Buy me a coffee — supporters get exclusive themes and a badge
• Sponsor on GitHub
• Star the repo — it helps others find it
• Share a theme on X — every share helps grow the community

License

[MIT](LICENSE) — built with love by @Daeshawn.

Community-built. Not affiliated with OpenAI.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: daeshawnballard
• Source: daeshawnballard/dexthemes
• License: MIT
• Homepage: https://dexthemes.com

Install and usage instructions live in the source repository linked above.