Guides
Setting up needs-you and connecting the things that should alert you. New here? Start with the quickstart, or the tester guide if you were invited to try it.
Start here
- Quickstart The whole setup, step by step: the Mac app, Claude Code on the Mac, servers.
- Testers Trying needs-you: download, first run, what to try and how to report problems, on one page.
- Words Words: hub, sender, reader, owner, invite link, server hub, tailnet, and the Settings page for each.
- Mac app Installing and using NeedsYou.app: the pill, the cards, Settings.
Agents
- Claude Code Claude Code hooks for "agent is waiting" cards, and the skill: what gets installed and what each hook posts.
- Claude Code everywhere Alerts from Claude Code sessions on the Mac, over SSH, in tmux, VS Code Remote-SSH and Orca.
- Codex CLI OpenAI Codex CLI hooks: a card when a session wants approval or is waiting for your next message.
- Gemini CLI Gemini CLI hooks: a card when a session wants approval or is waiting for your next message.
- Copilot CLI GitHub Copilot CLI hooks: a card when Copilot asks for permission or finishes its turn, cleared when you answer.
- Kimi Code Kimi Code CLI hooks: a card when Kimi asks for approval or a question, or finishes its turn, cleared when you answer.
- Grok Build Grok Build hooks: a card when Grok asks for permission or has waited a minute for you, and how they share the Claude Code hooks.
- Cursor Cursor hooks: a card when a Cursor agent finishes its turn (Cursor has no approval hook).
- Cline Cline hooks, VS Code and CLI: a card when a task finishes (Cline has no approval hook).
- Aider Aider's notifications command: a card when Aider waits for you; it can't tell when you answer.
- opencode An opencode plugin: a card when a session asks for permission, asks a question or goes idle.
- Orca Orca agents and automations on one or many servers: the Terminal button, keys, a hand-off example.
- MCP server A stdlib-Python MCP server so agents without a shell can post, resolve and run doctor through MCP tools.
- Custom connector Connect any agent or tool: the exact item format, and which fields are required or optional.
Servers, CI and tools
- Add a sender Invite links, the installer's options, CI and cron, removing a sender.
- Tailscale Putting the Mac and your servers on one tailnet, and checking they can reach each other.
- GitHub Review requests, deploy approvals, failed CI and your PRs' state, from one poller.
Run it
- Server hubs Optional always-on server hubs: install, two-hub setup, backups, upgrades, resource use.
- Keeping up to date Keeping up to date: the Mac app updating itself, needs-you update on senders, rollouts.
- Troubleshooting When an item doesn't show up: needs-you doctor, reachability, hooks.
Reference
- Agent guide The sender contract: when agents should post, keys, rules, and resolving what they posted.
- API The hub's HTTP API (v1): every endpoint, field, status code and the replication format.
These pages are built from the markdown in docs/ on every push to main.