{"id":49115365,"url":"https://github.com/headsdownapp/headsdown-claude","last_synced_at":"2026-04-21T07:01:04.771Z","repository":{"id":349013480,"uuid":"1200114695","full_name":"headsdownapp/headsdown-claude","owner":"headsdownapp","description":"HeadsDown availability plugin for Claude Code. Trust levels, status contracts, and verdicts.","archived":false,"fork":false,"pushed_at":"2026-04-21T05:00:55.000Z","size":213,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T06:41:22.566Z","etag":null,"topics":["claude-code","developer-tools","headsdown","mcp"],"latest_commit_sha":null,"homepage":"https://headsdown.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/headsdownapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T03:48:00.000Z","updated_at":"2026-04-21T05:00:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/headsdownapp/headsdown-claude","commit_stats":null,"previous_names":["headsdownapp/headsdown-claude"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/headsdownapp/headsdown-claude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headsdownapp%2Fheadsdown-claude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headsdownapp%2Fheadsdown-claude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headsdownapp%2Fheadsdown-claude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headsdownapp%2Fheadsdown-claude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/headsdownapp","download_url":"https://codeload.github.com/headsdownapp/headsdown-claude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/headsdownapp%2Fheadsdown-claude/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32081122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T06:27:27.065Z","status":"ssl_error","status_checked_at":"2026-04-21T06:27:21.250Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","developer-tools","headsdown","mcp"],"created_at":"2026-04-21T07:00:43.411Z","updated_at":"2026-04-21T07:01:04.764Z","avatar_url":"https://github.com/headsdownapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# headsdown-claude\n\n[HeadsDown](https://headsdown.app) availability plugin for Claude Code. Gives Claude awareness of your focus mode, availability state, and availability before it starts tasks.\n\nWhen installed, Claude will:\n1. **Know your availability from the start** via a SessionStart hook that injects your current mode into context\n2. **Check before starting work** via a skill that teaches Claude to submit task proposals\n3. **Respect your focus time** by scoping work appropriately or deferring when you're busy\n4. **Show what you missed** via a digest of notifications that arrived during focus mode\n\n## Install\n\n### From a marketplace (when published)\n\n```\n/plugin install headsdown\n```\n\n### From a local directory\n\n```bash\ngit clone https://github.com/headsdownapp/headsdown-claude.git\ncd headsdown-claude\nnpm install\nnpm run build\n```\n\nThen start Claude Code with the plugin:\n\n```bash\nclaude --plugin-dir /path/to/headsdown-claude\n```\n\nOr add it to your settings for permanent use.\n\n## Setup\n\nAuthenticate with HeadsDown after installing:\n\n```\n/headsdown auth\n```\n\nOr ask Claude: \"Run headsdown_auth to connect my HeadsDown account\"\n\nThis starts a Device Flow: you visit a URL, enter a code, and the API key is saved locally at `~/.config/headsdown/credentials.json`.\n\n## What's in the Plugin\n\n### SessionStart Hook\n\nEvery time Claude Code starts a session, the hook calls the HeadsDown API and injects your current availability into Claude's context. Claude knows your mode, status, and availability state before you say anything. If you're not authenticated or the API is unreachable, the hook exits silently (no disruption).\n\n### PreToolUse Hook (Write/Edit)\n\nBefore Claude writes or edits any file, the hook checks your current mode:\n\n| Mode | Behavior |\n|------|----------|\n| **online** | Silent pass. No interruption. |\n| **busy** | Allow, but inject a warning: \"Submit a proposal via headsdown_propose before continuing.\" |\n| **busy + locked** | Ask the user for explicit permission. Status is locked = do not disturb. |\n| **limited** | Allow, but remind Claude to keep changes small and focused. |\n| **offline** | Ask the user for explicit permission. All changes should be deferred. |\n\nThis is the enforcement layer. The skill suggests checking availability; this hook requires it.\n\n### `/headsdown` Command\n\nQuick slash command for direct access:\n- `/headsdown` or `/headsdown status` - See your current availability\n- `/headsdown auth` - Authenticate with HeadsDown\n\n### `headsdown` Skill\n\nA SKILL.md that teaches Claude when and how to check availability. Claude loads this contextually before starting tasks, so it knows to check your status and submit proposals for non-trivial work.\n\n### MCP Tools\n\nSeven tools registered via the plugin's MCP server:\n\n**`headsdown_status`** - Check your current availability. Returns mode, status message, time remaining, and availability state.\n\n**`headsdown_propose`** - Submit a task proposal. Returns a verdict:\n- **Approved**: Claude proceeds\n- **Deferred**: Claude informs you and suggests postponing or reducing scope\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `description` | Yes | What Claude plans to do |\n| `estimated_files` | No | Number of files to modify |\n| `estimated_minutes` | No | Expected duration |\n| `scope_summary` | No | Which modules, what kind of changes |\n| `source_ref` | No | Ticket number, PR URL, etc. |\n\n**`headsdown_digest`** - View notifications and messages that arrived during focus time. Returns grouped summaries by source and actor. Read-only.\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `latest` | No | Limit to N most recent summaries (default: 20) |\n\n**`headsdown_grants`** - List/create/revoke delegation grants for actor-scoped authorization.\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `action` | No | list_active, list, create, revoke, revoke_many (default: list_active) |\n| `id` | No | Grant id for revoke |\n| `scope` | No | session, workspace, agent |\n| `session_id` | No | Session identifier |\n| `workspace_ref` | No | Workspace reference |\n| `agent_id` | No | Agent identifier |\n| `permissions` | No | availability_override_create, availability_override_cancel, preset_apply |\n| `duration_minutes` | No | Relative expiry for create |\n| `expires_at` | No | Absolute expiry for create |\n| `source` | No | Audit source label |\n| `active` | No | Active filter for list/revoke_many |\n\n**`headsdown_override`** - Get/set/clear temporary availability overrides.\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `action` | No | get, set, clear (default: get) |\n| `id` | No | Override id for clear |\n| `mode` | No | online, busy, limited, offline (required for set) |\n| `duration_minutes` | No | Relative expiry for set |\n| `expires_at` | No | Absolute expiry for set |\n| `reason` | No | Optional reason for set/clear |\n\n**`headsdown_report`** - Report the outcome of a task approved via `headsdown_propose`. Helps HeadsDown calibrate future verdicts.\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `outcome` | Yes | completed, failed, partially_completed, cancelled, timed_out |\n| `error_category` | No | Category of error if failed |\n| `tests_passed` | No | Whether changes pass tests |\n\n**`headsdown_auth`** - Authenticate via Device Flow.\n\n## How It Works\n\n```\nYou set your focus mode in HeadsDown (busy for 2 hours)\n         │\n         ▼\nClaude Code starts a session\n         │\n         ▼\nSessionStart hook ──► [HeadsDown] Mode: busy, 🔨 Deep work, 120min remaining\n         │\n         ▼\nClaude already knows your status. User asks for a big refactor.\n         │\n         ▼\nheadsdown_propose ──► { decision: \"deferred\", reason: \"...\" }\n         │\n         ▼\nClaude tells you: \"You're in focus mode. Want me to defer this,\n                   or should I scope it down to a quick fix?\"\n```\n\n## Plugin Structure\n\n```\nheadsdown-claude/\n├── .claude-plugin/\n│   └── plugin.json           # Plugin manifest\n├── skills/\n│   └── headsdown/\n│       └── SKILL.md          # Agent behavioral instructions\n├── commands/\n│   └── headsdown.md          # /headsdown slash command\n├── hooks/\n│   ├── hooks.json            # Hook configuration\n│   ├── session-start.sh      # Injects availability at session start\n│   └── check-availability.sh # Gates file modifications by mode\n├── .mcp.json                 # MCP server config\n├── src/\n│   ├── index.ts              # MCP server entry point\n│   ├── server.ts             # Tool handlers\n│   └── cli.ts                # Lightweight CLI for hooks/commands\n├── test/\n│   └── server.test.ts        # 47 tests\n├── package.json\n└── README.md\n```\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HEADSDOWN_API_URL` | `https://headsdown.app` | API endpoint (for development) |\n| `HEADSDOWN_API_KEY` | (from credentials file) | Override the stored API key |\n\n## Data Transparency\n\nThis plugin is a thin wrapper around the [HeadsDown SDK](https://github.com/headsdownapp/headsdown-sdk). It sends requests only to the HeadsDown API.\n\n**What is sent:** Task descriptions and scope estimates (when you submit proposals), your API key for authentication, and actor context metadata (`source`, `agentId`, `sessionId`, `workspaceRef`) for delegated authorization paths.\n\n**What is received:** Your availability status, availability state, task verdicts, and digest summaries (aggregated notifications).\n\n**What is stored locally:** Your API key at `~/.config/headsdown/credentials.json` (0600 permissions).\n\nNo telemetry. No analytics. No third-party requests.\n\n## Development\n\n```bash\ngit clone https://github.com/headsdownapp/headsdown-claude.git\ncd headsdown-claude\nnpm install\nnpm run build\nnpm test\n\n# Validate plugin structure\nclaude plugins validate .\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadsdownapp%2Fheadsdown-claude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheadsdownapp%2Fheadsdown-claude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheadsdownapp%2Fheadsdown-claude/lists"}