@ammduncan/easel 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.2.8 — 2026-05-22
+
+### Docs
+- README now documents Codex as a supported client (added in 0.2.5 but missed in the doc pass). "Works with" list, install commands, config-path table, CLI help text, and file map all updated.
+
+## 0.2.7 — 2026-05-22
+
+### Fixed
+- **Agents in non-Claude-Code clients (Claude Desktop, Cursor, etc.) weren't calling the `label` tool**, so their sessions stayed named after the cwd basename of wherever the client spawned the MCP child (often `home` or the user's username — unfindable in the switcher). Claude Code agents do call it because the `SessionStart` hook injects a strong "label NO LATER than your first push" directive; non-CC clients only see tool descriptions, and the old descriptions didn't carry the same urgency.
+- The `label` tool description is now imperative: "as soon as the user's intent is clear, NO LATER than your first push", with format rules (1–8 words, sentence case, name the artefact not the verb) and good/bad examples.
+- The `push` tool description now has a dedicated "BEFORE YOUR FIRST PUSH — LABEL THE SESSION" section that cross-references `label`, so agents see the cue at the moment they're about to push.
+
 ## 0.2.6 — 2026-05-22
 
 ### Fixed

package/README.md

@@ -15,7 +15,7 @@ A live browser tab for every AI coding session. Agents push HTML — explanation
 └────────────────────────────────────────────┘    └────────────────────────────────────┘
 ```
 
-Works with **Claude Code**, **Cursor**, **Claude Desktop**, **Windsurf**, and any other MCP-speaking client.
+Works with **Claude Code**, **Cursor**, **Claude Desktop**, **Windsurf**, **Codex**, and any other MCP-speaking client.
 
 ## Why
 
@@ -33,7 +33,7 @@ npx -y @ammduncan/easel setup
 
 That registers the MCP at user scope, installs the `using-easel` skill so the agent knows when to push, and adds the `SessionStart` hooks that resolve session IDs and auto-open the tab. Restart Claude Code and you're done.
 
-### Cursor / Claude Desktop / Windsurf
+### Cursor / Claude Desktop / Windsurf / Codex
 
 One command per client:
 
@@ -41,9 +41,19 @@ One command per client:
 npx -y @ammduncan/easel setup --client cursor
 npx -y @ammduncan/easel setup --client claude-desktop
 npx -y @ammduncan/easel setup --client windsurf
+npx -y @ammduncan/easel setup --client codex
 ```
 
-Each writes the MCP entry to the client's config file (`~/.cursor/mcp.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, or `~/.codeium/windsurf/mcp_config.json`). Restart the client to load it.
+Each writes the MCP entry to the client's config file:
+
+| Client | Config file |
+|---|---|
+| Cursor | `~/.cursor/mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Codex | `~/.codex/config.toml` — plus copies the `using-easel` skill into `~/.codex/skills/` |
+
+Restart the client to load the MCP server.
 
 ### Any other MCP client
 
@@ -122,7 +132,7 @@ easel open                     ensure server is running, open this session's tab
 easel url                      print this session's URL
 easel config                   print / set { preset, theme, density }
 easel setup                    Claude Code: hooks + MCP + skill
-easel setup --client <name>    register the MCP in another client (cursor, claude-desktop, windsurf)
+easel setup --client <name>    register the MCP in another client (cursor, claude-desktop, windsurf, codex)
 easel restart                  kill + respawn the HTTP server (handy after a build)
 easel update                   git pull + build + setup (clone installs only)
 easel server                   run the HTTP server in the foreground (debug)
@@ -140,7 +150,7 @@ src/
   session-store.ts    disk persistence + retention sweep
   session-id.ts       5-tier resolver (env / hook file / transcript scan / synthetic PPID)
   config-store.ts     preset / theme / density persistence
-  client-setup.ts     per-client config writers (cursor, claude-desktop, windsurf)
+  client-setup.ts     per-client config writers (cursor, claude-desktop, windsurf, codex)
   paths.ts            shared constants + legacy-dir migration
   cli.ts              `easel open|url|setup|config|server|restart|update|version`
   client/

package/dist/mcp.js

@@ -122,6 +122,8 @@ export async function main() {
                     "• One accent color, 3–4 instances max per card. Status colors (red/amber/green) only when state genuinely maps to status.\n\n" +
                     "═══ WHEN TO PUSH ═══\n" +
                     "A response that would otherwise contain: >2 paragraphs of explanation, any UI mockup, a diagram, a code diff, a ≥3-option comparison, or a multi-step progress view. Do NOT ask permission — push proactively. After pushing, reply in chat with ONE LINE: 'pushed to easel ↗ — #<index>'. Don't restate the card's content.\n\n" +
+                    "═══ BEFORE YOUR FIRST PUSH — LABEL THE SESSION ═══\n" +
+                    "Sessions without a label show up in the session switcher as the cwd basename (often something useless like 'ammielyawson' or 'home'), which is unfindable when the user has multiple tabs open. If you haven't called the `label` tool yet in this session, CALL IT NOW before pushing — pass a 1–8 word sentence-case name that describes what the session is about (good: 'SSE explainer', 'Onboarding flow comparison'; bad: 'Helping the user', 'Pushing some cards'). Re-call `label` when the work's theme shifts meaningfully.\n\n" +
                     "═══ OTHER ═══\n" +
                     "• Pass full HTML only — no Markdown. The iframe injects baseline typography so plain `<h1>/<p>` works without extra CSS, but for anything multi-section define your own `<style>` block.\n" +
                     "• `<script>` tags trying to mutate the parent window are sandbox-blocked; in-iframe `<script>` (for animations, charts, interactivity) is fine.",
@@ -138,7 +140,15 @@ export async function main() {
             },
             {
                 name: TOOL_LABEL,
-                description: "Set or update this Claude session's display label — a short, human phrase that names what the session is about (e.g. 'Roadworthy 401 fix', 'Bulk-add cost items redesign', 'Investigating slow query'). The label appears in the topbar, switcher dropdown, and session index, replacing the cwd basename. Call this proactively whenever the work's theme shifts so the user can navigate sessions by what they ARE, not where they live. Pass an empty string to clear back to cwd basename.",
+                description: "Set this session's display label — a short, human phrase that names what the chat is about (e.g. 'Roadworthy 401 fix', 'SSE explainer', 'Onboarding flow comparison'). The label replaces the cwd basename in the topbar, switcher dropdown, and session index, making the user's tabs findable.\n\n" +
+                    "CALL THIS PROACTIVELY:\n" +
+                    "• As soon as the user's intent is clear in this chat — and NO LATER than your first `push`.\n" +
+                    "• Without a label, the session shows up as the cwd basename (often something useless like 'home' or 'ammielyawson' for desktop clients), which is unfindable when the user has multiple chat tabs open.\n" +
+                    "• Re-call whenever the work's theme shifts meaningfully (e.g. user pivots from 'auth flow design' to 'session cleanup').\n\n" +
+                    "FORMAT:\n" +
+                    "• 1–8 words, sentence case, no trailing punctuation.\n" +
+                    "• Name the ARTEFACT, not the verb. Good: 'RegistrationNumberInput extraction', 'SSE explainer', 'Onboarding A/B'. Bad: 'Extracting RegistrationNumberInput', 'Helping with onboarding', 'Pushing some cards'.\n\n" +
+                    "Pass an empty string to clear back to the cwd basename.",
                 inputSchema: {
                     type: "object",
                     properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",