HeadsDown availability awareness and task gating for Gemini CLI. This extension makes Gemini "availability-aware," allowing it to respect your focus time, submit task proposals, and negotiate scope when you are busy.
- Specialist Subagent (
@headsdown): A dedicated expert agent for managing your availability, focus time, and task proposals. - Interactive Conflict Resolution: Uses Gemini CLI's native
ask_userUI to negotiate scope (Override, Wrap-Up, or Defer) when focus conflicts arise. - Real-time Gating:
BeforeAgentHook: Warns the agent if you are busy or a "Wrap-Up" deadline is near before it even starts planning.BeforeToolHook: Prevents destructive actions (file writes, shell commands) unless a proposal has been approved.
- Secure Storage: Leverages Gemini CLI's
settingsto securely store yourHEADSDOWN_TOKENin the system keychain.
Install directly from npm:
gemini extension install @headsdown/geminiIf you want to contribute or run from source:
git clone https://github.com/headsdownapp/headsdown-gemini.git
cd headsdown-gemini
npm install
npm run build
gemini extension install .After installation, the CLI will prompt you for your HeadsDown token. You can also set it manually:
gemini settings set HEADSDOWN_TOKEN <your-token>Tip: Use the headsdown_auth tool within Gemini to get your token via device flow.
- Node.js:
>=22.14.0 - Gemini CLI:
v0.39.1or higher
npm run build # Bundle runtime entrypoints to dist/
npm test # Run Vitest suite
npm run dev # Watch modePublished artifacts bundle the HeadsDown SDK into dist/index.js and dist/hooks/*.js while keeping @modelcontextprotocol/sdk as an external runtime dependency. Source TypeScript remains in-repo for development.
- Update version in
package.json. - Push a tag (e.g.,
git tag v0.4.0 && git push origin --tags). - GitHub Actions will automatically update
CHANGELOG.md, publish to npm, and create a GitHub Release.
This repo uses Renovate to keep @headsdown/sdk and other routine dependencies current. New SDK releases open bot PRs automatically, and eligible updates can automerge after required CI checks pass. In normal maintenance flow, do not manually edit @headsdown/sdk versions unless you are intentionally overriding Renovate behavior.
MIT