diff --git a/README.md b/README.md index 164c6e977d..75b47f2b72 100644 --- 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 new file mode 100644 index 0000000000..6ef568f121 --- /dev/null +++ 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