# DexThemes

> Discover, preview, create, and apply themes through supported Codex and DeepSeek Harness paths.

## 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.
- **How does DeepSeek Harness apply work?** Install the published, runtime-reviewed `@dexthemes/deepseek-harness-plugin@0.6.4` from npm, then open Settings → Plugins → DexThemes. Search the DeepSeek, DexThemes, or Community collections, preview a paired theme, and click Apply; the package calls Harness's guarded `theme.overrideTokens` service. Applying another theme switches the owned layer and Revert restores Harness default. The package also connects a restricted public MCP profile for search, paired drafting, Color Me Lucky, validation, preview data, apply preparation, and leaderboards. The DeepSeek collection includes a palette matched to Harness's published defaults plus twelve company-named, unofficial color tributes with evidence links. This is not a clipboard/import flow, and the standalone website cannot control an unrelated Harness tab.
- **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)
- **DeepSeek Harness payload**: https://www.dexthemes.com/api/deepseek-theme?theme={public-theme-id}
- **DeepSeek Harness MCP tools**: https://www.dexthemes.com/api/deepseek-mcp
- **DeepSeek Harness npm package**: https://www.npmjs.com/package/@dexthemes/deepseek-harness-plugin
- **DeepSeek Harness install/compatibility source**: https://github.com/daeshawnballard/dexthemes/tree/main/packages/deepseek-harness-plugin
- **Plugin releases**: https://github.com/daeshawnballard/dexthemes/releases
- **Support**: https://www.dexthemes.com/support.html

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.

#### GET /api/deepseek-theme?theme={public-theme-id}
Return validated light/dark semantic token pairs and the exact client-only Cordis definition for an eligible paired theme. This is a distribution artifact, not an external Harness installer. Fonts are omitted and `cordis_stop` is the reversal path.

#### 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, separate Codex and DeepSeek Harness 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` authorizes public submission. The first-party app renders an exact review and calls the write after its Publish button is pressed. Its short-lived token binds the exact payload and OAuth session and expires, but app visibility and the token do not independently prove a human click.

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.

## DeepSeek Harness agent tools

- Restricted MCP endpoint: `https://www.dexthemes.com/api/deepseek-mcp`
- Tools: `search`, `fetch`, `draft_theme`, `color_me_lucky`, `validate_theme`, `render_theme_preview`, `prepare_deepseek_apply`, and `get_leaderboard`
- The profile is anonymous and read-only. It excludes Codex apply, account, submission, publishing, and feedback tools because Harness's generic bridge does not enforce their OAuth or app-only metadata.
- Calls transmit only explicit tool arguments. DexThemes does not automatically receive prompts, workspace contents or paths, credentials, account identity, or transcript history.
- The installed Harness settings plugin can connect a DexThemes account through OAuth device authorization. A successful connected apply can grant `Harnessed` and its `Deep Current` reward; anonymous MCP and theme applies never grant it.
- Current published, runtime-reviewed install: `pnpm dsh plugin --profile web add @dexthemes/deepseek-harness-plugin@0.6.4`. See the versioned DeepSeek Harness documentation for the exact evidence scope; do not infer newer reconnect, token, revocation, or activity assurances from an older artifact.

---

## 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