# Project: Codex Launcher — Any AI Provider

## Overview

OpenAI Codex CLI & Desktop launcher that proxies to **any** AI provider.
Python-only (stdlib), zero pip dependencies. Supports Responses API, Chat Completions,
Anthropic Messages API, Command Code, and more via a translation proxy.

Maintained by:
- **roman-ryzenadvanced** — original Linux/GTK development
- **cobra91** — Windows port (tkinter GUI, MSIX support)

## Architecture

```
codex-launcher-gui.py  (tkinter on Windows / GTK on Linux)
  → codex_launcher_lib.py  (shared library: endpoints, config, process mgmt)
    → translate-proxy.py   (HTTP proxy: Responses API → backend API)
      → upstream provider (OpenAI, Anthropic, DeepSeek, Antigravity, etc.)
```

### Key Files

| File | Purpose |
|------|---------|
| `src/codex-launcher-gui.py` | Windows tkinter GUI |
| `src/codex_launcher_lib.py` | Shared library (endpoints, config, process management) |
| `src/translate-proxy.py` | Translation proxy (core routing, adapters, streaming) |
| `src/antigravity_grpc/` | gRPC client for Antigravity provider |

### Backend Types

| Type | Wire Protocol | Example |
|------|--------------|---------|
| `openai-compat` | Chat Completions | DeepSeek, OpenRouter, Crof.ai |
| `anthropic` | Anthropic Messages | Anthropic direct, OpenCode Zen |
| `command-code` | Command Code /alpha/generate | CommandCode API |
| `gemini-oauth-*` | Google OAuth | Google Antigravity |

## Platform Compatibility

**MUST work on both Linux and Windows.** No exceptions.

### Platform-Specific Patterns

- **Process management**: `os.setsid()` + `os.killpg()` on Linux, `CREATE_NEW_PROCESS_GROUP` on Windows
- **Process listing**: `pgrep` on Linux, `tasklist` / `wmic` on Windows
- **Desktop launch**: exe path on Linux, `shell:AppsFolder\{AUMID}` for MSIX on Windows
- **Signals**: `signal.SIGTERM` on Linux, `taskkill /F` on Windows
- **Paths**: `~/.local/bin/` on Linux, `%LOCALAPPDATA%\Programs\Codex-Launcher\` on Windows
- **Config**: `~/.codex/config.toml` (same format on both)
- **POSIX-only APIs**: `os.getpgid()`, `/proc/{pid}/stat`, `os.setsid()` — always guard with `sys.platform` checks

### Testing Cross-Platform

- Never assume Unix-only APIs exist (`pgrep`, `getpgid`, `SIGTERM`)
- Use `sys.platform == "win32"` for Windows branches
- Test proxy startup on both platforms before committing
- Provider presets (PROVIDER_PRESETS) work identically on both

## Coding Conventions

- Python 3.8+ stdlib only, zero pip dependencies
- `snake_case` for functions/variables, `UPPER_CASE` for globals
- Immutable patterns: create new dicts/objects, don't mutate in-place
- Error handling: catch at boundaries, never silently swallow errors
- Thread-safe: use `threading.Lock` for shared state, `threading.Semaphore` for concurrency

## Common Pitfalls

- **MSIX exe paths**: `C:\Program Files\WindowsApps\` exes cannot be launched via `subprocess.Popen` — use `shell:AppsFolder` protocol
- **File locking on Windows**: Python can't overwrite files open in another process
- **Path separators**: always use `os.path.join()` or `Path` objects, never hardcoded `/`
- **Signal handling**: Windows doesn't support `SIGUSR1`/`SIGUSR2` — use events or named pipes

## Testing

- **Run before every commit**: `python -m pytest tests/ -v`
- **All tests must pass** before pushing a PR
- Test files live in `tests/` directory
- Tests use `pytest` (not unittest runner)
- Platform-specific tests must skip gracefully on other OS: `pytest.mark.skipif(sys.platform != "linux", reason="Linux-only")`
- Never mock filesystem paths with hardcoded separators — use `os.path.join` or `tmp_path`