# DexThemes

> Discover, preview, create, and import themes for Codex.

## Direct answers

- **What is DexThemes?** A free, open source catalog, preview, and theme-creation tool for Codex.
- **Is DexThemes official?** No. DexThemes is community-built and is not affiliated with OpenAI.
- **How does import work?** DexThemes copies a complete `codex-theme-v1` import string. The user opens Codex Settings, chooses Appearance, selects Import theme, pastes the string, and approves the change.
- **Does DexThemes modify Codex files?** No. DexThemes prepares the import payload; Codex owns the final import.
- **What are the catalog sources?** Codex catalog themes are built-in palettes, DexThemes themes are curated by this project, and Community themes are original palettes published by creators.
- **Can a user inspect a theme before importing it?** Yes. Every public theme variant has a server-rendered details page and the app provides both a faux chat preview and an in-app Theme details view.
- **Who writes the DexThemes guides and articles?** Daeshawn Ballard. The visible byline links to https://x.com/daeshawn and matches the page's structured author data.
- **Are the guides agent-readable?** Yes. Every guide, feature, article, and reference page is server-rendered HTML with a canonical `.md` representation.

## Domains

- **Website**: https://www.dexthemes.com (frontend, public pages, docs)
- **Public theme catalog**: https://www.dexthemes.com/api/themes
- **Published agent docs**: https://www.dexthemes.com/llms.txt and https://www.dexthemes.com/.well-known/openapi.json
- **Direct API base**: https://acrobatic-corgi-867.convex.site (authenticated + generator endpoints)

Use `https://www.dexthemes.com/api/themes` for public browsing examples. Use the published LLM/OpenAPI docs for discovery. Use the direct Convex base URL when you need authenticated or generator HTTP access.

## Public discovery pages

- Install guide: https://www.dexthemes.com/guides/how-to-install-a-codex-theme
- Custom theme guide: https://www.dexthemes.com/guides/create-a-custom-codex-theme
- Import troubleshooting: https://www.dexthemes.com/guides/codex-theme-import-troubleshooting
- All guides: https://www.dexthemes.com/guides
- Feature documentation: https://www.dexthemes.com/features
- Articles: https://www.dexthemes.com/articles
- Theme format reference: https://www.dexthemes.com/reference
- Collections: https://www.dexthemes.com/collections
- Community themes: https://www.dexthemes.com/collections/community
- Exact theme variant: `https://www.dexthemes.com/{id}/dark|light`
- Markdown representation: append `.md` to an individual guide, feature, article, or reference URL

## Authentication

DexThemes has three auth modes:

1. **Browser session cookie** — used automatically on `www.dexthemes.com` after GitHub OAuth sign-in.
2. **API keys** — prefixed with `dxt_`. A GitHub-authenticated user can create one for an agent or CLI and send it in `Authorization: Bearer <token>`.
3. **Plugin OAuth** — the Codex/ChatGPT MCP app uses a signed OAuth 2.1 access token with GitHub as the upstream identity and `themes:read` or `themes:write` scopes.

### Create an agent key after GitHub sign-in

```
POST /auth/agent
Cookie: __Host-dexthemes_session=...
```

Response:
```json
{
  "apiKey": "dxt_...",
  "agentId": "github:...",
  "message": "API key created. Use it in the Authorization header: Bearer dxt_..."
}
```

The API key is shown only once and stored by DexThemes only as a SHA-256 digest. Anonymous key minting is not supported.

### Use the token

```
Authorization: Bearer dxt_your_api_key_here
```

---

## API Quick Reference

### Public endpoints (no auth required)

#### GET /themes
List all themes across the Codex, DexThemes, and Community categories.
Returns JSON array.

#### GET /themes/community
List all published community themes with colors, accents, and metadata.
Returns JSON array.

#### GET /themes/codex
List all built-in Codex themes.

#### GET /themes/dexthemes
List all DexThemes-curated themes.

#### GET /themes/dexthemes/:subgroup
List DexThemes-curated themes for a subgroup such as `anime`, `video-games`, or `unlockables`.

#### GET /themes/likes/counts
Get like counts for all themes.
Returns JSON object mapping theme IDs to counts.

#### GET /api/color-me-lucky
Generate a random harmonious theme.
Parameters:
- `variant` (optional): "dark" (default) or "light"
- `name` (optional): custom name for the theme

Returns: name, variant, harmony type, colors object, and a ready-to-paste `importString` for Codex.

#### Deep link to a theme
```
https://www.dexthemes.com/{id}/dark|light
```

---

### Authenticated endpoints

Browser use on `www.dexthemes.com` relies on the session cookie. Scripted use relies on a Bearer `dxt_...` API key issued to a GitHub-authenticated account.

#### GET /auth/me
Get the current authenticated user profile.
Returns: `{ user: { ... } }`

#### POST /auth/logout
End the current browser session. API keys are not affected.
Returns: `{ success: true }`

#### GET /me/stats
Get the authenticated user's submission statistics (theme count, total copies, total likes).
Returns: JSON stats object.

#### GET /me/likes
Get the list of theme IDs the authenticated user has liked.
Returns: `{ likes: ["theme-id-1", "theme-id-2", ...] }`

#### POST /themes
Submit a new community theme.
Body:
```json
{
  "themeId": "my-theme-slug",
  "name": "My Theme",
  "summary": "A cool dark theme",
  "dark": { "surface": "#...", "ink": "#...", "accent": "#...", ... },
  "light": { "surface": "#...", "ink": "#...", "accent": "#...", ... },
  "accents": ["#accent1", "#accent2"],
  "codeThemeId": { "dark": "codex", "light": "codex" }
}
```
At least one of `dark` or `light` is required. Returns 201 on success.

#### POST /themes/like
Toggle a like on a theme (like if not liked, unlike if already liked).
Body: `{ "themeId": "theme-id" }`
Returns: `{ liked: true|false, count: <number> }`

#### POST /themes/flag
Flag a theme for moderation.
Body: `{ "themeId": "theme-id", "reason": "optional reason (max 500 chars)" }`
Returns 409 if already flagged by this user.

#### POST /themes/copy
Increment the copy counter for a theme. Requires auth to prevent abuse.
Body: `{ "themeId": "theme-id" }`
Returns: updated theme object or 404.

#### POST /api/color-me-lucky/submit
Submit a randomly generated theme to the DexThemes gallery.
Body:
```json
{
  "name": "Theme Name",
  "variant": "dark",
  "colors": { "surface": "#...", "ink": "#...", ... },
  "summary": "optional description"
}
```
If `colors` is omitted, fresh random colors are generated. Returns 201 on success.

#### POST /me/api-demo
Perform an authenticated API read and unlock The Builder. The server grants the achievement only through this endpoint; clients cannot claim `use_api` by naming the action.

---

### OAuth endpoints (browser redirect flow only)

These initiate OAuth sign-in and redirect back to the frontend. On production origins they establish the secure browser session cookie automatically. Localhost/dev flows may still use a temporary hash-token bootstrap.

#### GET /auth/github
Start GitHub OAuth flow. Optional query param: `origin` (frontend URL to redirect back to).

#### GET /auth/github/callback
GitHub OAuth callback. Exchanges code for token, creates/updates user, redirects to frontend.

---

## Codex/ChatGPT plugin

- MCP endpoint: `https://www.dexthemes.com/api/mcp`
- Protected-resource metadata: `https://www.dexthemes.com/.well-known/oauth-protected-resource`
- Public tools cover discovery, personalized named theme drafting, validation, previews, Codex apply preparation, public leaderboards, and sanitized GitHub Issue preparation.
- `themes:read` returns the signed-in creator's stats, personal monthly/all-time ranks, and achievements.
- `themes:write` first renders an exact review; the app-only write accepts only a short-lived token bound to that payload and OAuth session after the user presses Publish.

Plugin identity is derived only from the verified OAuth token. Tools never accept user IDs, owner IDs, author identity, tokens, API keys, or email addresses as arguments. A verified exact `@openai.com` identity may receive the optional “OpenAI is nothing without its people” achievement and Human Spark reward; DexThemes stores only an eligibility boolean, and the original unlock theme does not imply OpenAI endorsement.

---

## Theme format

Each theme has dark and/or light variants with these color properties:
- `surface` — main background
- `ink` — primary text color
- `accent` — brand/link color
- `sidebar` — sidebar background (auto-derived if omitted)
- `codeBg` — code block background (auto-derived if omitted)
- `diffAdded` — green for added code
- `diffRemoved` — red for removed code
- `skill` — secondary accent color
- `contrast` — contrast level (0-100)

### Applying a theme to Codex

Copy the `importString` from any API response, open Codex, go to Settings, then Appearance, and paste it.

## Links

- Website: https://www.dexthemes.com
- OpenAPI: https://www.dexthemes.com/.well-known/openapi.json
- GitHub: https://github.com/daeshawnballard/dexthemes
- Full theme data for LLMs: https://www.dexthemes.com/llms-full.txt