Organized-AI · jhillbht · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
diff --git a/README.md b/README.md
@@ -22,6 +22,42 @@ Tiny macOS 14+ menu bar app that keeps **AI coding-provider limits visible** and
 - **Live status.** Provider status polling surfaces incident badges in the menu and an indicator overlay on the bar icon.
 - **Privacy-first.** Reuses existing provider sessions — OAuth, device flow, API keys, browser cookies, local files — so no passwords are stored.
 
+## Sesher + CodexBar essential guide
+
+Sesher and CodexBar work best together when you separate the **human session** from the **AI coding quota**.
+Sesher is the session companion: it helps clarify Session DNA, meeting goals, conversation moves, agendas, repair prompts,
+and follow-through. CodexBar is the menu bar meter: it tells you whether Codex, Claude Code, Cursor, Gemini, Copilot,
+OpenRouter, LiteLLM, and other AI coding providers have enough available quota for the work Sesher helps you plan.
+
+Use CodexBar instead of Sesher only for the quota/status part. Keep Sesher or a Sesher-style workflow for coaching,
+meeting preparation, archetypes, reports, and debriefs.
+
+### Recommended workflow
+
+1. **Plan the session in Sesher.** Define the goal, desired output, constraints, and next move for the conversation or work block.
+2. **Check CodexBar before launching AI work.** Confirm the relevant provider has enough session/weekly/monthly quota and note the reset countdown.
+3. **Pick the provider intentionally.** If Codex is near its limit but Claude or another provider is healthy, switch before starting a long task.
+4. **Run the AI-assisted build/research pass.** Use the provider whose quota window best fits the job.
+5. **Return to Sesher for follow-through.** Capture decisions, debrief the session, and turn outputs into the next agenda or playbook.
+
+### Setup checklist
+
+```bash
+brew install --cask codexbar
+open -a CodexBar
+```
+
+Then in **CodexBar → Settings → Providers**:
+
+- Enable only the providers you actually use with Sesher-backed work sessions.
+- Prefer local CLI, OAuth, or API-key sources when available.
+- Use browser-cookie sources only when you need dashboard extras and are comfortable with the macOS Keychain/browser prompts.
+- Turn on notifications if reset windows matter to your session planning.
+- Optional: install the bundled CLI from **Settings → Advanced → Install CLI** for scripts and dashboards.
+- Claude note: if you see `Claude OAuth token missing 'user:profile' scope`, either run `claude setup-token` to regenerate Claude Code credentials with the usage scope, or switch **Settings → Providers → Claude → Usage source** to **CLI** or **Web**.
+
+More detail: [Sesher comparison](docs/sesher.md).
+
 ## Install
 
 ### Requirements
@@ -180,6 +216,7 @@ Wondering if CodexBar scans your disk? It doesn’t crawl your filesystem; it re
 - UI & icon notes: [docs/ui.md](docs/ui.md)
 - CLI reference: [docs/cli.md](docs/cli.md)
 - Configuration: [docs/configuration.md](docs/configuration.md)
+- Sesher comparison: [docs/sesher.md](docs/sesher.md)
 - Keychain prompts: [docs/keychain-prompts.md](docs/keychain-prompts.md)
 - CLI configuration: [docs/cli-configuration.md](docs/cli-configuration.md)
 - Widgets: [docs/widgets.md](docs/widgets.md)

diff --git a/docs/sesher.md b/docs/sesher.md
@@ -0,0 +1,122 @@
+---
+summary: "Comparison notes for Sesher users evaluating CodexBar."
+read_when:
+  - Migrating from Sesher
+  - Comparing session tools with CodexBar
+  - Explaining what CodexBar does and does not replace
+---
+
+# Sesher comparison
+
+Sesher and CodexBar answer different questions.
+
+- **Sesher** is a session companion / coaching-style product concept: it helps people understand their "Session DNA," prepare for conversations, ask follow-up questions, and turn meeting insight into practical scripts, agendas, repair prompts, and next moves.
+- **CodexBar** is a macOS menu bar utility for AI coding-provider limits: it shows usage, quota windows, reset countdowns, credits, spend, provider status, and local cost scans for tools such as OpenAI Codex, Claude Code, Cursor, Gemini, Copilot, OpenRouter, LiteLLM, and related providers.
+
+## Quick decision
+
+Use **CodexBar instead of Sesher** only if the job you need done is quota visibility for AI coding tools.
+
+Keep **Sesher alongside CodexBar** if you need coaching/session workflows, meeting prep, archetypes, reports, or a conversational companion for human sessions.
+
+## Capability map
+
+| Need | Sesher | CodexBar |
+| --- | --- | --- |
+| Discover a personal/session style | Yes | No |
+| Generate a lightweight session playbook | Yes | No |
+| Ask coaching-style follow-up questions | Yes | No |
+| Prepare meeting scripts, agendas, or repair prompts | Yes | No |
+| Show Codex / Claude / Cursor / Gemini quota remaining | No | Yes |
+| Show reset countdowns for AI coding-provider windows | No | Yes |
+| Track credits, spend, and provider billing summaries | No | Yes |
+| Poll provider status and incident badges | No | Yes |
+| Provide a native macOS menu bar meter | No | Yes |
+| Provide a scriptable CLI for quota/status checks | No | Yes |
+| Manage provider auth sources, cookies, OAuth, API keys, or local usage logs | No | Yes |
+
+## Product differences
+
+### Scope
+
+Sesher is about **human operating context**: how someone shows up in sessions, where conversations drift, and what lightweight tactics help a person lead or participate better.
+
+CodexBar is about **machine/account operating context**: whether a provider account has enough available quota to start another AI coding task, when the quota resets, and whether the provider is healthy.
+
+### User interface
+
+Sesher is currently best represented as a web-style experience: landing page, five-question quiz, sample report, archetypes, and coaching result cards.
+
+CodexBar is native macOS infrastructure: status item, menu popover, settings panes, provider toggles, widgets, notifications, and a bundled `codexbar` CLI.
+
+### Data sources
+
+Sesher's prototype data is user-entered assessment answers and generated coaching/report content.
+
+CodexBar reads known provider-specific sources, depending on the provider and enabled features:
+
+- local CLI/app configuration and usage logs
+- OAuth/device-flow credentials
+- API keys
+- browser cookies or local storage
+- Keychain items needed to decrypt cookies or bootstrap some sessions
+- provider billing/status APIs
+
+CodexBar does **not** crawl the filesystem broadly; it reads a small set of known locations for enabled providers and features.
+
+### Privacy and permissions
+
+Sesher's core prototype can run as a simple web app and does not need privileged macOS access for its basic assessment flow.
+
+CodexBar may need macOS permissions or prompts for specific provider integrations, especially browser-cookie-based providers:
+
+- optional Full Disk Access for Safari cookies/local storage
+- Keychain prompts for Chromium cookie decryption or provider OAuth/session items
+- provider API keys or OAuth/device-flow authorization
+
+For privacy-sensitive use, enable only the providers you actually need and prefer CLI/OAuth/API-key sources over broad browser-cookie imports where possible.
+
+## Migration notes
+
+CodexBar is not a drop-in product replacement for Sesher. A practical migration looks like this:
+
+1. Install CodexBar for AI provider limit visibility.
+2. Enable only the coding providers you use.
+3. Use CodexBar's menu bar and reset countdowns to decide when to launch long-running AI coding tasks.
+4. Keep Sesher or a Sesher-like workflow for human session preparation, coaching reports, and meeting guidance.
+
+### Claude setup note
+
+If CodexBar reports `Claude OAuth token missing 'user:profile' scope`, the Claude Code token it found can run inference but cannot call the Claude usage endpoint. Choose one path:
+
+- run `claude setup-token` to regenerate credentials with the required usage/profile scope, then keep Claude usage source on Auto/OAuth; or
+- switch **CodexBar → Settings → Providers → Claude → Usage source** to **CLI** or **Web**.
+
+CLI mode is usually the least invasive workaround for a Sesher + CodexBar setup because it relies on the already-installed Claude Code CLI instead of browser-cookie import.
+
+## When to use both
+
+A common combined workflow:
+
+1. Use Sesher to clarify the human goal for a conversation or working session.
+2. Use CodexBar to confirm Codex/Claude/etc. quota before starting the AI-assisted build or research pass.
+3. Run the coding/research work when quotas are healthy.
+4. Return to Sesher-style prompts for debrief, follow-through, and next-session planning.
+
+## Non-goals
+
+CodexBar does not aim to provide:
+
+- personality assessments
+- coaching archetypes
+- meeting facilitation flows
+- session reports for human leadership style
+- conversational coaching UX
+
+Sesher does not aim to provide:
+
+- AI coding-provider quota monitoring
+- native macOS menu bar meters
+- provider billing/spend dashboards
+- provider status incident polling
+- account auth/cookie/API-key probes