headsdown
Availability awareness and task gating for Gemini CLI.
Open source Open in the app JSON README (API)
About
Availability awareness and task gating for Gemini CLI.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- headsdownapp
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.4.0
- Open pull requests
- 16
- Last push
- 2026-09-05T16:14:04Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
headsdownapp/headsdown-gemini
README
# @headsdown/gemini 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. ## Features - **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_user` UI to negotiate scope (Override, Wrap-Up, or Defer) when focus conflicts arise. - **Real-time Gating**: - `BeforeAgent` Hook: Warns the agent if you are busy or a "Wrap-Up" deadline is near before it even starts planning. - `BeforeTool` Hook: Prevents destructive actions (file writes, shell commands) unless a proposal has been approved. - **Secure Storage**: Leverages Gemini CLI's `settings` to securely store your `HEADSDOWN_TOKEN` in the system keychain. ## Installation ### Standard Install (Recommended) Install directly from npm: ```bash gemini extension install @headsdown/gemini ``` ### Local Development If you want to contribute or run from source: ```bash git clone https://github.com/headsdownapp/headsdown-gemini.git cd headsdown-gemini npm install npm run build gemini extension install . ``` ## Configuration After installation, the CLI will prompt you for your HeadsDown token. You can also set it manually: ```bash gemini settings set HEADSDOWN_TOKEN <your-token> ``` *Tip: Use the `headsdown_auth` tool within Gemini to get your token via device flow.* ## Requirements - **Node.js**: `>=22.14.0` - **Gemini CLI**: `v0.39.1` or higher ## Development ```bash npm run build # Bundle runtime entrypoints to dist/ npm test # Run Vitest suite npm run dev # Watch mode ``` Published 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. ## Publishing 1. Update version in `package.json`. 2. Push a tag (e.g., `git tag v0.4.0 && git push origin --tags`). 3. GitHub Actions will automatically update `CHANGELOG.md`, publish to npm, and create a GitHub Release. ## Dependency update automation 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. ## License MIT