dsh-chatgpt-codex

Readme

# dsh-chatgpt-codex

[![CI](https://github.com/sudipnext/dsh-chatgpt-codex/actions/workflows/ci.yml/badge.svg)](https://github.com/sudipnext/dsh-chatgpt-codex/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![DeepSeek Harness plugin](https://img.shields.io/badge/DeepSeek_Harness-dsh--plugin-5b5bd6)](https://github.com/deepseek-ai/deepseek-harness)

Use your **ChatGPT account and Codex models inside DeepSeek Harness**. This standalone DSH plugin supports both a localhost browser callback and headless device-code authentication, refreshes OAuth tokens automatically, and streams Codex Responses into the native DSH message/tool protocol.

No OpenAI API key. No `pi-ai` runtime dependency.

> [!IMPORTANT]
> DeepSeek Harness does not currently ship ChatGPT/Codex OAuth for its main model route. It has a Codex subagent launcher that reuses the official Codex app's login, but that is a separate one-shot delegation path. This plugin fills the main-model gap and targets the current DSH `next` API (`0.1.0-rc.6` or newer).

## Features

- ChatGPT browser OAuth with PKCE, a strict state check, and a localhost callback
- ChatGPT device-code OAuth for SSH, containers, and headless machines
- Automatic access-token refresh with in-process and cross-process rotation locks
- Owner-only atomic credential storage under `$DSH_HOME`
- Native `openai-codex` DSH model provider—no `pi-ai` adapter
- Official OpenAI JavaScript SDK for the Codex Responses transport
- Streaming text, reasoning summaries, function calls, images, usage, and finish reasons
- Encrypted reasoning-item replay for correct multi-turn Codex sessions
- Current GPT-5.6 Luna, Terra, and Sol discovery entries, plus GPT-5.5/5.4 models

## Install in two minutes

The repository commits its built artifacts, so GitHub installation does **not** run a dependency `prepare` script.

### 1. Sign in with ChatGPT

Browser callback (recommended on a desktop):

```sh
pnpm dlx github:sudipnext/dsh-chatgpt-codex#v0.1.0 login
```

Device code (recommended over SSH or in a container):

```sh
pnpm dlx github:sudipnext/dsh-chatgpt-codex#v0.1.0 login --device
```

The default credential file is `$DSH_HOME/chatgpt-codex/auth.json`, or `~/.dsh/chatgpt-codex/auth.json` when `DSH_HOME` is unset.

### 2. Add the DSH bundle

```sh
dsh plugin --profile codex add github:sudipnext/dsh-chatgpt-codex#v0.1.0
```

### 3. Run DeepSeek Harness

```sh
dsh --profile codex
```

The bundle registers `openai-codex` and selects `gpt-5.6-luna` as the profile's default model. A later profile patch can choose another model.

## Authentication commands

```sh
# Browser callback without automatically opening a browser
dsh-chatgpt-codex login --no-open

# Device authorization; the code expires after 15 minutes
dsh-chatgpt-codex login --device

# Safe status output never prints tokens
dsh-chatgpt-codex status
dsh-chatgpt-codex status --json

# Rotate the access token immediately
dsh-chatgpt-codex refresh

# Remove local credentials
dsh-chatgpt-codex logout
```

For a GitHub-only installation, prefix these commands with `pnpm dlx github:sudipnext/dsh-chatgpt-codex#v0.1.0`.

## Configuration

Override the plugin row in the profile's `$DSH_HOME/profiles/<name>/cordis.patch.yml`:

```yaml
- id: llm-chatgpt-codex
  config:
    defaultReasoningEffort: high
    textVerbosity: low
    requestTimeoutMs: 300000

- id: agent-default-model
  config:
    provider: openai-codex
    model: gpt-5.6-terra
```

Available plugin settings:

| Setting | Default | Purpose |
| --- | --- | --- |
| `authFile` | `$DSH_HOME/chatgpt-codex/auth.json` | OAuth credential document |
| `issuer` | `https://auth.openai.com` | OAuth issuer, primarily for compatible deployments/tests |
| `baseURL` | `https://chatgpt.com/backend-api/codex` | Codex Responses base URL |
| `originator` | `dsh-chatgpt-codex` | Honest product identity sent upstream |
| `models` | Current bundled catalog | Advisory DSH model picker entries |
| `defaultReasoningEffort` | `high` | `low`, `medium`, `high`, `xhigh`, or `max` |
| `textVerbosity` | `low` | `low`, `medium`, or `high` |
| `requestTimeoutMs` | `300000` | Provider request timeout |

The model catalog is advisory. Actual model availability depends on the signed-in ChatGPT plan, workspace policy, region, and current OpenAI rollout.

## Why this does not use pi-ai

DeepSeek Harness's general `llm-pi-ai` adapter intentionally does not expose OAuth-only providers because it has no credential store or login lifecycle. This project owns the missing lifecycle directly:

1. The CLI performs ChatGPT PKCE or device-code authentication.
2. `AuthManager` stores and rotates the OAuth token set.
3. `CodexAdapter` converts native DSH history/tools to stateless Responses input.
4. The official `openai` SDK carries the HTTPS/SSE transport.
5. The stream translator emits DSH blocks and stores the encrypted replay items needed on the next turn.

See [Architecture](docs/architecture.md) for the exact components and trust boundaries.

## Security

- OAuth state is cryptographically random and compared in constant time.
- PKCE uses S256 and a fresh verifier for every login.
- The callback server listens only on `127.0.0.1` and closes after one result.
- Credentials are written atomically with mode `0600` on POSIX; parent storage uses `0700`.
- Tokens are never printed by status, errors, tests, or logs.
- This plugin uses its own credential file rather than copying `~/.codex/auth.json`, avoiding refresh-token rotation races with the official Codex client.

Read [SECURITY.md](SECURITY.md) before reporting a vulnerability. `logout` removes local credentials but does not revoke the OpenAI session remotely.

## Compatibility and status

This is an independent community plugin, not an official OpenAI or DeepSeek project. Both Codex's private ChatGPT backend and pre-release DSH APIs can change. The repository pins behavior with keyless OAuth, wire, replay, and storage tests; releases describe any required migration.

Using ChatGPT/Codex remains subject to your OpenAI account terms and workspace policy. A ChatGPT subscription does not guarantee every catalog model.

## Development

```sh
pnpm install
pnpm run check
```

The test suite uses local HTTP servers and synthetic JWTs; it does not require or read real ChatGPT credentials.

## License

MIT © 2026 sudipnext