codex-devtools 0.1.1 → 0.1.2

package/README.md

@@ -1,117 +1,124 @@
-# codex-devtools
+<p align="center">
+  <img src="resources/logo.png" width="120" alt="codex-devtools logo" />
+</p>
 
-Desktop app for inspecting Codex session data.
+<h1 align="center">codex-devtools</h1>
 
-## Prerequisites
+<p align="center">
+  Desktop inspector for <a href="https://github.com/openai/codex">Codex</a> session data.
+  <br />
+  Browse conversations, search messages, and analyze agent activity across sessions.
+</p>
 
-- Node.js 20+ (Node 24 works)
-- `pnpm` 10 (via Corepack recommended)
+<p align="center">
+  <a href="https://www.npmjs.com/package/codex-devtools"><img src="https://img.shields.io/npm/v/codex-devtools" alt="npm version" /></a>
+  <a href="https://github.com/gulivan/codex-devtools/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/codex-devtools" alt="license" /></a>
+</p>
 
-## Build and run
+---
 
-```bash
-cd /Users/ivan/git/codex-devtools
-corepack enable
-pnpm install
-pnpm approve-builds
-```
+## Quick start
 
-In `pnpm approve-builds`, approve:
-
-- `electron`
-- `esbuild`
-
-Then start the desktop app in development mode:
+> Requires **Node.js 20+** and **pnpm 10** (Corepack recommended).
 
 ```bash
-pnpm dev
+git clone https://github.com/gulivan/codex-devtools.git
+cd codex-devtools
+corepack enable
+pnpm install
+pnpm approve-builds   # approve electron and esbuild
+pnpm dev              # launch Electron app in dev mode
 ```
 
-## Production build
+Or run instantly via npm without cloning:
 
 ```bash
-pnpm build
+npx codex-devtools
+# or
+bunx codex-devtools
 ```
 
-Build artifacts are generated in:
+This starts a standalone HTTP server at `http://localhost:3456`.
 
-- `dist-electron`
-- `out/renderer`
+## Standalone mode
 
-Create desktop installers/packages locally:
+Run as an HTTP server without Electron:
 
 ```bash
-pnpm dist
+pnpm standalone
 ```
 
-Platform-specific package commands:
-
-- `pnpm dist:mac` (macOS: `.dmg`, `.zip`)
-- `pnpm dist:win` (Windows: NSIS installer)
-- `pnpm dist:linux` (Linux: AppImage, `.deb`, `.rpm`)
-
-## Standalone mode
+Opens at `http://localhost:3456` by default.
 
-Run as an HTTP server (without launching Electron):
+## Production build
 
 ```bash
-pnpm standalone
+pnpm build            # compile renderer + main/preload
+pnpm dist             # create installers for all platforms
 ```
 
-Default URL:
+Platform-specific:
+
+| Command | Output |
+|---------|--------|
+| `pnpm dist:mac` | `.dmg`, `.zip` |
+| `pnpm dist:win` | NSIS installer |
+| `pnpm dist:linux` | AppImage, `.deb`, `.rpm` |
 
-- `http://localhost:3456`
+Build artifacts land in `release/`.
 
 ## Environment variables
 
-- `CODEX_SESSIONS_PATH`: path to Codex sessions directory (default: `~/.codex/sessions`)
-- `HOST`: standalone server host (default: `0.0.0.0`)
-- `PORT`: standalone server port (default: `3456`)
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_SESSIONS_PATH` | `~/.codex/sessions` | Path to Codex sessions directory |
+| `HOST` | `0.0.0.0` | Standalone server host |
+| `PORT` | `3456` | Standalone server port |
 
 ## Scripts
 
-- `pnpm dev`: start Electron app in dev mode
-- `pnpm build`: build renderer + Electron main/preload
-- `pnpm dist`: build macOS + Windows + Linux packages
-- `pnpm dist:mac`: build macOS packages
-- `pnpm dist:win`: build Windows installer
-- `pnpm dist:linux`: build Linux packages
-- `pnpm standalone`: build and run standalone HTTP server
-- `pnpm test`: run tests with Vitest
-- `pnpm lint`: run ESLint
-- `pnpm typecheck`: run TypeScript type checks
+| Script | Description |
+|--------|-------------|
+| `pnpm dev` | Electron app in dev mode |
+| `pnpm build` | Build renderer + Electron main/preload |
+| `pnpm standalone` | Build and run standalone HTTP server |
+| `pnpm dist` | Package for macOS + Windows + Linux |
+| `pnpm dist:mac` | Package for macOS |
+| `pnpm dist:win` | Package for Windows |
+| `pnpm dist:linux` | Package for Linux |
+| `pnpm test` | Run tests (Vitest) |
+| `pnpm lint` | Run ESLint |
+| `pnpm typecheck` | TypeScript type checks |
 
 ## CI/CD
 
-- `.github/workflows/ci.yml`: typecheck/lint/build/test on `main` and PRs.
-- `.github/workflows/release.yml`: cross-platform packaging on semver tags (`v*`) and manual dispatch.
-- `.github/workflows/npm-publish.yml`: npm publish on semver tags (`v*`) and manual dispatch.
-
-Required GitHub repository secret for npm publishing:
-
-- `NPM_TOKEN`: npm automation token (or granular token with publish + 2FA bypass).
-
-## Versioning (SemVer)
+| Workflow | Trigger | Action |
+|----------|---------|--------|
+| `ci.yml` | Push to `main`, PRs | Typecheck, lint, build, test |
+| `release.yml` | Semver tags (`v*`), manual | Cross-platform packaging |
+| `npm-publish.yml` | Semver tags (`v*`), manual | Publish to npm |
 
-Releases use semantic version tags:
+Required secret: `NPM_TOKEN` (npm automation token with publish + 2FA bypass).
 
-- `vMAJOR.MINOR.PATCH` (example: `v0.1.1`)
-- optional pre-release/build metadata (`v1.2.3-beta.1`, `v1.2.3+build.4`)
-
-Tag and publish flow:
+## Releasing
 
 ```bash
-npm version patch
+npm version patch     # bumps version and creates git tag
 git push origin main --follow-tags
 ```
 
-`release.yml` and `npm-publish.yml` validate tag format and fail if the tag is not valid SemVer.
+Tags must be valid semver (`vMAJOR.MINOR.PATCH`). Pre-release metadata supported (`v1.2.3-beta.1`).
 
 ## Troubleshooting
 
-If `pnpm dev` fails with `Electron failed to install correctly` or `Electron uninstall`:
+**`Electron failed to install correctly`**
+
+```bash
+pnpm approve-builds   # approve electron and esbuild
+pnpm install
+pnpm dev
+```
+
+## License
 
-1. Run `pnpm approve-builds`
-2. Approve `electron` and `esbuild`
-3. Run `pnpm install` again
-4. Retry `pnpm dev`
+[MIT](LICENSE)

package/bin/codex-devtools.cjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+'use strict';
+
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+
+const standaloneEntrypoint = join(__dirname, '..', 'dist-electron', 'main', 'standalone.cjs');
+
+if (!existsSync(standaloneEntrypoint)) {
+  console.error(
+    '[codex-devtools] Missing standalone bundle. Reinstall package or run a version that includes dist-electron output.',
+  );
+  process.exit(1);
+}
+
+const standaloneModule = require(standaloneEntrypoint);
+
+if (typeof standaloneModule.startStandaloneCli !== 'function') {
+  console.error('[codex-devtools] Invalid standalone entrypoint: startStandaloneCli export not found.');
+  process.exit(1);
+}
+
+standaloneModule.startStandaloneCli();

package/out/renderer/index.html

@@ -3,6 +3,9 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/png" sizes="256x256" href="./assets/256x256-DdIsGiwi.png" />
+    <link rel="icon" type="image/png" sizes="32x32" href="./assets/32x32-DQgygEFU.png" />
+    <link rel="icon" type="image/png" sizes="16x16" href="./assets/16x16-B2_QkmoB.png" />
     <title>codex-devtools</title>
     <script type="module" crossorigin src="./assets/index-CR8-JZrV.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-r_pK0Xle.css">

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-devtools",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Desktop app for inspecting Codex session data",
   "license": "MIT",
   "author": {
@@ -17,7 +17,11 @@
     "url": "https://github.com/gulivan/codex-devtools/issues"
   },
   "main": "dist-electron/main/index.cjs",
+  "bin": {
+    "codex-devtools": "bin/codex-devtools.cjs"
+  },
   "files": [
+    "bin/**",
     "dist-electron/**",
     "out/renderer/**",
     "README.md"
@@ -85,7 +89,9 @@
     "extraMetadata": {
       "main": "dist-electron/main/index.cjs"
     },
+    "icon": "resources/icon.png",
     "mac": {
+      "icon": "resources/icon.icns",
       "category": "public.app-category.developer-tools",
       "target": [
         "dmg",