Agent Companion

Know the moment Claude Code needs you — without staring at the terminal.

Agent Companion watches your Claude Code sessions and tells you — with a desktop notification, a sound, a live status bar item, and optionally your voice — the moment Claude needs a permission granted, has a question, finishes, or fails. No more tabbing back every thirty seconds to check.

Contents

• Why
• Install
• Quick start
• Features
• Voice control
• Settings
• Commands
• Privacy & security
• Troubleshooting
• How it works
• Contributing
• Roadmap
• License

Why

You kick off a Claude Code task and switch away — another window, another room. Claude then:

• needs permission to run something,
• has a question for you,
• finishes,
• or fails.

You don't notice until you wander back. Agent Companion closes that gap.

Install

From the Marketplace:

1. Open the Extensions view in VS Code (⇧⌘X / Ctrl+Shift+X).
2. Search Agent Companion and click Install — or install directly:

   code --install-extension HanifAdeyemi.claude-agent-companion
   

Requirements: VS Code 1.85+, and Claude Code installed and used from a terminal (VS Code's integrated terminal or an external one — both work, since notifications come from Claude Code's own hook system, not from watching a specific terminal). macOS, Windows, and Linux are all supported.

Quick start

1. Open the Command Palette (⌘⇧P / Ctrl+Shift+P) and run Agent Companion: Setup Claude Code Integration.
2. Choose Global (every project on this machine) or Project (this workspace only).
3. Review the summary and confirm — your existing Claude settings are backed up first, and only Agent Companion's own entries are added.
4. Run Claude Code as usual. Watch the status bar for live state, and expect a notification the moment Claude needs you.

Run Agent Companion: Remove Claude Code Integration any time to cleanly reverse step 3.

Features

• Instant notifications for the four moments that actually need you: permission requested, input required, task completed, task failed — each with its own sound and message.
• Live status bar — $(robot) Claude: Working, $(bell) Claude: Needs Permission, and so on. Click it for a list of active sessions and any pending permission requests, with one-click Allow/Deny.
• Deterministic risk classification — every permission request is tagged LOW / MEDIUM / HIGH / CRITICAL by a fixed rule set before you ever see it. No model calls, no guessing.
• Cross-platform sound, native on every OS (macOS afplay, Windows SoundPlayer, Linux paplay/aplay/ffplay) — sensible defaults out of the box, fully customizable per event.
• Optional voice commands — say "yes," "no," "repeat," or "open Claude" instead of reaching for the keyboard. Off by default. See below for exactly what this does and doesn't do today.
• Safe, reversible setup — hook installation backs up your settings first and never touches anything it didn't add.

Voice control

Voice control is off by default and, when enabled, only ever listens in a short window right after a real permission request — never continuously, never on a timer.

What works today: the listening window, the visible mic indicator, and full command recognition (Yes/Allow, No/Deny, Repeat, "Open Claude") once a transcript exists. Risk-tier enforcement is real: for LOW/MEDIUM-risk requests a recognized "yes" approves immediately; for HIGH/CRITICAL requests, voice can never approve on its own — it only opens a typed confirmation dialog. That gate is enforced in the core decision logic, not just the UI.

What's not wired up yet: the microphone-to-text step itself. VS Code has no built-in speech-to-text API, so this release ships an honest placeholder — enabling voice control turns on the listening window and mic indicator, but no command will actually be recognized until a real speech engine is added. The command that enables it tells you this explicitly. Swapping in a real engine is fully isolated to one file, so it won't change any other behavior when it lands.

Settings

All settings live under agentCompanion.* (Settings UI → search "Agent Companion"):

Commands

Privacy & security

• No external network calls. Communication is loopback-only, between the extension and its own hook script on your machine. Nothing is ever sent to a remote server.
• The microphone is never active outside a bounded listening window tied to a real pending permission request, and voice control defaults to off.
• Command text isn't persisted. Raw command text lives in memory only for the lifetime of a pending decision — never written to logs or disk. Status bar state stores risk tier, not command content.
• Nothing is ever auto-approved for HIGH or CRITICAL risk. A casual "yes" is never sufficient by itself for those tiers, enforced at the decision layer.
• Setup is safe and reversible. Your Claude settings are backed up before any write, and removal only deletes entries this extension added.

Troubleshooting

How it works

Claude Code supports hooks — commands it invokes on events like permission requests and task completion, with structured JSON in and out. Agent Companion installs a small script as that hook command; the script talks to a local, loopback-only server the extension runs while VS Code is open. No terminal scraping, no polling.

Claude Code hook → local hook script → loopback HTTP → normalized event bus → notifications,
                                                                                status bar, voice

The event bus is agent-agnostic by design — nothing outside the Claude integration layer knows Claude's specific payload shapes, so support for other agents (Codex CLI, Gemini CLI) can be added later without touching notifications, voice, or the UI. See docs/ARCHITECTURE.md for the full design writeup.

Contributing

npm install
npm run compile   # bundle with esbuild
npm run typecheck
npm run lint
npm test          # unit tests, no VS Code host required
npm run test:e2e  # launches a real Extension Development Host and verifies activation

Press F5 in VS Code (with this repo open) to launch an interactive Extension Development Host.

Key source layout: src/agents/claude/ (Claude integration), src/permissions/RiskClassifier.ts (risk rules), src/voice/ (voice pipeline), src/notifications/ (notifications and sound).

Roadmap

• Now: Claude Code support, notifications, sounds, status bar, risk classification, voice command parsing with risk-gated routing.
• Next: Codex CLI and Gemini CLI adapters, multiple simultaneous sessions, a richer dashboard, stuck-agent detection, a real speech-recognition backend.
• Later: mobile notifications, remote approval where it can be done safely, cross-device monitoring.

License

Proprietary — see LICENSE. Free to install and use via the official Marketplace listing; redistribution or modification of the source requires permission.