Voice Session Sentinel

A helper for Claude Code in Cursor and VS Code. Version 0.7.2.

Disclaimer: This extension works with Claude Code. It is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic.

Türkçe: README.tr.md (included in the package)

Features

• Reminders. When Claude has been waiting for your answer or approval for a set time, a reminder appears in the bottom-right corner.
• Chat name suggestions. When a chat finishes its work, Claude Haiku suggests a name. Click Yes and the name is applied automatically (the clipboard is not used). No and Update are also available.
• Side panel. Shows this project's Claude chats, their status, and each chat's name-suggestion switch. The panel opens automatically when the editor starts.
• Sounds. Plays a spoken or chime alert in the selected language when Claude asks a question, waits for approval, or finishes. You can upload your own sound for question alerts (mp3, wav, ogg; up to 5 MB). The ▶ buttons in settings preview the selected question sound and the full sound-mode sequence.
• Usage estimate. Shows the remaining time estimated from today's rate, the previous three full days' rate, and the period average. You can choose the weekly overall, five-hour, or weekly Fable limit. A usage report opens in the editor when usage reaches 80% and 90%.
• 50 languages. The panel, notifications, error messages and the usage section appear entirely in the language you choose. Arabic, Persian, Urdu and Western Punjabi are shown right to left. Suggested chat names keep your language and alphabet.

Usage calculations and notification texts are fully local; no Haiku or other model is called for them. Only chat name suggestions use Haiku.

Opening the panel

• Click the Voice Session Sentinel icon in the Activity Bar.
• Command Palette: Voice Session Sentinel: Paneli aç (open panel)
• Command Palette: Voice Session Sentinel: Ayarları aç (open settings)

Command titles are currently in Turkish.

How it works

Watching Claude.

• Claude Code keeps a ~/.claude/sessions/<pid>.json file for each running chat. It contains the chat's ID, name, and status (idle, busy, waiting).
• The extension only reads this folder, every 2 seconds.
• Only chats started in the open workspace folders are watched.
• Chat files (~/.claude/projects/.../<session>.jsonl) are read too. The single exception: if a name cannot be applied through Claude's UI, a custom-title line (the same line Claude writes itself) is appended to the chat file (see Applying the name).
• The usage cache is read-only.
• The Terminal takibini kur (set up terminal tracking) button installs a statusLine hook in Claude's user settings and the /estimated_remaining skill. See the setup section below.

Reminders.

• A chat counts as "waiting for you" when Claude is waiting for permission or approval (waiting), or when it finished and its last message ends with a question mark.
• When reminderMinutes passes, one reminder appears, showing the chat name and how long it has been waiting.
• Buttons:
  • Go to chat: brings the Claude tab or terminal to the front.
  • Snooze: restarts the timer.
  • Close: dismisses the reminder.
• These buttons never send anything to Claude.

Chat name.

• The name is read in this order:
  1. Current name in Claude
  2. custom-title
  3. ai-title
  4. Start of the first message
  5. Untitled chat (project, time)
• If the name cannot be verified, "(name not verified)" is shown.

Name suggestion.

• A suggestion is prepared when Claude finishes a turn.
• The extension runs the local claude program once, hidden.
  • No chat record is created.
  • Tools, MCP, and user settings are disabled.
  • Your existing Claude subscription is used.
• The model is the lowest Haiku version that works on your account, found by trying from oldest to newest.
• Only Claude's own title, the first message, and the project name are sent to the model.
• Name format: <day emoji>_<tag>_<project>_<task>, for example 🕐_code_extension_panel-settings.
• At most two suggestions per chat; the second comes only if the topic changes.
• Chats you named yourself get no suggestions.
• If the model fails, a plain error message is shown. If Claude has a title, it is converted to our format and suggested.

Applying the name.

• Claude in a terminal: when Claude is idle, /rename <name> is typed into that terminal and the result is verified.
• Claude Code for VS Code / Cursor (editor tab): the chat's tab is brought forward, Claude's "Rename Session Tab" box opens, and the name is typed and confirmed (Windows only). The clipboard is not used. Keys are sent only if this VS Code window is in front and the tab really belongs to this chat; another chat's tab is never renamed.
• Chats in Claude's sidebar, or when the paths above are unavailable (VS Code not in front, terminal not found, non-Windows system): the name is added to the chat file as a custom-title line, the same line Claude's own rename writes. The running Claude adopts it; the sidebar title updates on the next refresh.
• If no method works, the name is copied to the clipboard and you are notified.

Usage tracking and remaining time

Open the Estimated usage section at the bottom of the panel.

• Current usage and remaining percentage appear with the first fresh measurement. Daily and three-day estimates appear once there is enough history.
• You never enter percentages, periods, or reset times yourself.
• If the source offers several limits (weekly overall, five-hour, weekly Fable), choose one from the drop-down. The default is the weekly overall limit.

Estimates:

• Today's rate: usage since local midnight divided by real hours passed. If you installed mid-day, there is no midnight reading, so the first day's estimate may be missing.
• Three-day rate: the previous three full calendar days, excluding today. Three days after installation is not enough by itself; readings must cover the day boundaries.
• Durations are calendar time, breaks included. Example: 60% left at 2 percentage points per hour ≈ 30 hours.
• Period average: every period starts at 0%, so one reading is enough. Used percentage is divided by the time from period start (reset time − 7 days; − 5 hours for the five-hour limit) to the last reading. Example: 44% used in 88 hours = 0.5 points per hour. Because it is based on the reading time, it is shown even when data is old. It is not calculated in the first hour of a period or for money budgets.
• If the limit resets earlier, the result is At this rate the limit resets before it runs out.
• If the last reading is older than 15 minutes, today's and three-day estimates are hidden and a hint to refresh with /usage appears.
• A monthly billing date is not a monthly quota. If the source reports a real spending budget, the daily/weekly/monthly money budget is labeled separately.

The extension checks at startup, when the relevant local files change, and every 60 seconds. Refresh re-reads the same local sources; it does not force Claude to fetch new data from the server. The same reading is never stored twice, and subscription percentages are never derived from chat tokens.

80% and 90% notifications

• When current, valid usage reaches 80% or 90%, a report webview opens next to the editor. Your typing focus is kept; no extra sound or repeating timer is added.
• The report shows the measured percentage, estimates, reset time, and charts.
• Each threshold is shown at most once per account, limit, and quota period.
  • A jump like 79% → 91% shows only the 90% alert.
  • If the first reading is 92%, only the 90% alert is shown.
  • If the 80% report is open, the 90% alert updates the same report.
• Closing the report or restarting the extension does not repeat the alert. Thresholds reset once the source confirms a new quota period.
• These alerts are independent of the reply/approval reminder (default 10 minutes).
• No report is shown while the editor is closed. At startup, only the current reading of the current period is checked.

Installing and removing the terminal helper

1. In the panel's usage section, click Terminal takibini kur (set up terminal tracking).
2. Setup:
   • Connects your existing Claude statusLine command to the usage log, keeping that command.
   • Creates the user-level /estimated_remaining skill. It does not overwrite a user command or skill with the same name.
   • Keeps all other Claude settings.
3. Readings collect automatically when Claude sends new status-line data. If needed, open /usage in Claude, then click Refresh in the panel.
4. After updating the extension, reinstall the helper once: run Voice Session Sentinel: Terminal kullanım yardımcısını kur (install terminal usage helper) from the Command Palette. The installed helper is not updated with the extension. An old helper may remove limits added by newer versions (such as Fable) from the log, and /estimated_remaining keeps showing the old report.

The helper needs no separate Node.js installation or background service. It uses the runtime of your installed VS Code/Cursor and can run from the terminal even when the editor is closed. If the editor is removed or its install path changes, reinstall the helper.

/estimated_remaining shows the same local report in terminal Claude and in VS Code Claude.

• It runs only when you call it and makes no separate Haiku request, though Claude still has to generate a reply.
• When your Claude quota is completely used up, the slash command's reply is not guaranteed. The Companion panel and the direct helper report may still work.

Run the helper directly:

& "$env:USERPROFILE\.claude-companion\usage\run.ps1" report

~/.claude-companion/usage/run.sh report

The Terminal takibini kaldır (remove terminal tracking) button removes the hooks Companion installed, if you have not changed them since. Files you changed are left untouched. Removing terminal tracking does not stop the panel's read-only watching of the local usage cache.

Local data and language

• The last 35 days of usage readings are stored outside your project in ~/.claude-companion/usage/history.json. The terminal and the panel share this store.
• Accounts are kept apart with a one-way identity hash.
• API keys, login tokens, and chat content are never copied into this history.
• Which thresholds have been shown is also stored there.

All texts (panel, notifications, errors and the usage section) support the 50 languages of the language menu and come from one shared catalog (src/i18n/locales/*.json, with en.json as the template). Arabic, Persian, Urdu, and Western Punjabi are shown right to left; the five Arabic options share Modern Standard Arabic text while their spoken alerts stay dialectal. auto follows VS Code's display language; any other language can be chosen in the panel. In the terminal, the language is chosen in this order: the workspace's panel language, your user language, then the system language.

Settings

Each chat's name-suggestion preference is kept in the extension's own workspace storage. Technical details are written to the Output → Voice Session Sentinel channel.

Known limitations

• Command Palette titles and Settings page descriptions are translated by VS Code itself, so they are only available in the VS Code display languages the extension covers (German, Spanish, French, Italian, Japanese, Korean, Polish, Brazilian Portuguese, Russian, Turkish, Simplified Chinese). In every other language they appear in English.

• With auto, a Traditional Chinese VS Code (zh-tw, zh-hk) shows the Simplified Chinese (Mandarin) texts; Cantonese and Taiwanese Hokkien can be chosen in the panel.

• Translations were made with AI and checked against published software terminology (VS Code language packs, Firefox, Android, MediaWiki) and by back-translation. Languages with few software sources (for example Bhojpuri, Igbo, Javanese, Sundanese, isiZulu, Odia, Western Punjabi, Burmese) would benefit most from native-speaker feedback.

• Usage cache.

  • The usage cache is not a documented API. An unsupported version, an unidentified account, or a missing source is shown openly; no data is made up.
  • Compatibility with your Claude install and its /usage flow should be checked for the version you use.

• Terminal helper.

  • The helper needs Claude's status line to provide usage fields before logging starts.
  • Nothing is recorded while the computer is off. Long gaps can delay estimates.

• VS Code/Cursor Claude panel.

  • The status line works only for Claude running in a terminal; the Claude panel in VS Code/Cursor does not run the statusLine command.
  • In the panel, readings come only from Claude's cache. That cache refreshes when you open /usage, when you open Account & usage in the Claude panel, and the first time the Claude panel opens in each window.
  • So readings are sparse, but the period average still gives an estimate. For frequent readings, run Claude in the terminal with the Claude Code extension's claudeCode.useTerminal setting.

• Weekly Fable limit.

  • It is read only from the undocumented limits list in Claude's cache; the status line does not send it. Fable data therefore often looks stale.
  • If the format changes, only the Fable option disappears; other limits are unaffected.

• 80% and 90% alerts are checked only for the limit currently selected in the panel.

• On Windows, running run.ps1 directly depends on your PowerShell execution policy. The status-line and slash-command hooks do not change that policy.

• Undocumented chat files.

  • The sessions/*.json and .jsonl formats are not documented by Claude. A Claude update may break reading.
  • If that happens, the extension does not crash and names show as "(name not verified)".
  • For chat files larger than 8.5 MB, only the beginning and end are read, so a title change in the middle may be missed.

• Renaming.

  • If you are typing in the terminal while /rename is being sent, the text can get mixed up.
  • Typing into Claude's name box automatically is Windows-only. On other systems the name is applied through the chat file. Sidebar titles update on the next refresh, not instantly.

• Sound. VS Code does not play sound until you click the panel once. In that case, the sound is played through Windows (Windows only).

• Multiple windows.

  • Terminal chats are handled only by the window that owns the terminal.
  • Claude chats inside VS Code/Cursor cannot be matched to a window, so each window opening the same folder may remind you separately.

Development

npm.cmd ci
npm.cmd run typecheck
npm.cmd test
npm.cmd run build
npm.cmd run package -- --allow-missing-repository
cursor.cmd --install-extension .\voice-session-sentinel-0.7.2.vsix

License

Free to use. Copying, modifying, redistributing, or selling is not allowed without written permission. See the LICENSE file.