Guides

Troubleshooting

Work from the sender toward the Mac: can the sender reach a hub, did the hub store the item, can the Mac see it, is the Mac showing the right context.

Reporting a problem: what to include, and how to save the app's log with tokens and invite codes masked, is in Testers → Report a problem.

Start here: needs-you doctor #

On the sender, run:

needs-you doctor          # or ~/.local/bin/needs-you doctor if it isn't on PATH
needs-you doctor --json   # the same, for agents: {ok, version, checks: [{check, status, detail, hint}]}

It checks the env file (and that its mode is 600), whether needs-you and ~/.local/bin are on PATH, each hub URL (reachable, hub version, the token's name and role), the outbox (queued, failed, oldest), each agent's hooks or plugin (Claude Code, Codex, Gemini, opencode, Copilot, Kimi, Grok, Cursor, Cline, Aider), the Claude skill, the MCP server and agent instructions if you installed them, Orca settings, updates, and the 5-minute flush schedule. Each line is OK, WARN, FAIL or INFO. Every WARN and FAIL has one next step under it (after ->): a command to run as is, or exactly what to ask for, such as a new invite link (<invite link> is the only placeholder). It exits 1 if any check is FAIL. It's read-only: it never posts an item, never flushes the outbox and never prints the token (only "set" and its length).

Quick checks by hand #

# on the sender
. ~/.config/needs-you/env
for u in $(echo "$NEEDS_YOU_URLS" | tr ',' ' '); do
  printf '%s  ' "$u"; curl -sS -o /dev/null -w '%{http_code}\n' --max-time 5 "$u/v1/health"
done
ls ~/.local/state/needs-you/outbox/ 2>/dev/null   # queued items that haven't reached a hub
tailscale status | head                          # is this machine on the tailnet?
# macOS with the Tailscale app: /Applications/Tailscale.app/Contents/MacOS/Tailscale status

A sender can't reach the hub #

Setting up Tailscale, or checking it step by step: Tailscale.

The CLI never fails your job because of the hub. It queues to ~/.local/state/needs-you/outbox/ and sends on the next call or needs-you flush (the invite installer schedules one every 5 minutes). Items sitting in the outbox mean no hub has accepted them yet. The outbox keeps at most 500 requests and 7 days; older ones are dropped with a warning.

Invite links #

setup-sender.sh (manual setup) #

• needs-you: command not found after setup: ~/.local/bin isn't on your PATH. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile. Hooks and cron don't read your profile; they find the CLI at ~/.local/bin/needs-you directly (or set NEEDS_YOU_BIN).
• "no terminal available; continuing as --non-interactive": you ran it without a TTY (e.g. over ssh host cmd). Use ssh -t, or pass --url and --token-stdin.
• "does not look like the needs-you CLI": the --install-cli URL returned an HTML page (login wall, 404). Use the raw file URL.
• Health ok, but the test item is refused (401): the token isn't valid on that hub. Tokens replicate between peered hubs; check the hubs are peered and the token exists on each (needs-you-admin token list).

Items post, but nothing shows on the Mac #

1. Context and hours: a work item at 21:00 shows only as the faint second number (0 · 1). Use the toggle in the expanded header, or check the work-hours setting.
2. Kind: done and info items never raise the count. They're in the collapsed Recent section.
3. Snoozed: press Control-Option-Space (⌃⌥Space, or your configured shortcut) to bring the panel back.
4. Mac can't reach a server hub: the Mac needs Tailscale up. Hover the idle pill: the "last check" time should be recent.
5. Wrong hub: the sender's NEEDS_YOU_URLS must include the Mac's hub or a server hub peered with it.
6. Hubs out of sync: if the Mac polls hub-a and the sender wrote to hub-b, replication should copy it within seconds. If it doesn't, check the peer list and the replication outbox on hub-b (Server hubs).

Duplicate or stale cards #

• Duplicates: the sender changes its key between runs (a timestamp, a run id). Keys must be stable.
• Cards that never go away: the sender never calls resolve. Fix the sender, then clear the card with Done on the Mac.
• A sender that went away (a killed agent session, a machine that's gone, an automation that crashed) can't resolve its cards. Safety nets, in the order they kick in:
  • Agent hooks record the agent's process. The 5-minute needs-you flush on that machine resolves the card once the process is gone (Claude Code).
  • Agent cards expire 48 hours after their last post (NEEDS_YOU_AGENT_EXPIRY_HOURS; Aider's after an hour). Each new post pushes it out.
  • Scheduled automations post with --expires-in of about twice their interval, so a blocker they stop reporting drops off by itself (Orca).
  • On the Mac, a card waiting 4 hours or more shows its age, and its … menu has Dismiss All from <host> for a machine that went away (Mac app).
• A card keeps re-animating: the title, body or priority changes on every post (e.g. a counter or time in the title). Put changing details in the body sparingly, or keep them out.

Claude Code hooks #

Setup per environment (SSH, tmux, VS Code Remote-SSH, Orca): Claude Code everywhere. Turn on the debug log and simulate an event:

echo '{"session_id":"t1","cwd":"'"$PWD"'","notification_type":"idle_prompt","message":"test"}' |
  NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/dev/stderr ~/.claude/hooks/needs-you-hook.sh notify

Other checks:

• /hooks inside Claude Code lists the active hooks. If ours are missing, re-run install-hooks.sh and restart the session.
• Project-level hooks use $CLAUDE_PROJECT_DIR/.claude/hooks/needs-you-hook.sh. If the repo was cloned without .claude/hooks/, re-run install-hooks.sh --project.
• A card that doesn't clear: the resolve runs only if this session posted (marker files in ~/.local/state/needs-you/claude-hooks/). Deleting that directory is safe. A session that was killed is cleared by the next needs-you flush once its Claude process is gone (needs-you doctor shows whether the flush is scheduled), or 48 hours after its last post.
• Too noisy? idle_prompt fires after about a minute of waiting. Opt in only on machines where agents run unattended.

Codex hooks #

needs-you doctor has a codex hooks line. Simulate an approval prompt and its resolve with a log to stderr:

echo '{"hook_event_name":"PermissionRequest","session_id":"t1","cwd":"'"$PWD"'","tool_name":"Bash","tool_input":{"command":"make test"}}' |
  NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/dev/stderr ~/.codex/hooks/needs-you-hook.sh notify codex
echo '{"session_id":"t1"}' | NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/dev/stderr ~/.codex/hooks/needs-you-hook.sh resolve codex

The log lines mean the same as for the Claude Code hooks above. Codex-specific causes:

• Not trusted. Codex skips hooks nobody has reviewed and says so at startup. Open /hooks in Codex and trust the needs-you entries. Editing those entries by hand makes them untrusted again.
• Hooks turned off. hooks = false under [features] in ~/.codex/config.toml (or a managed requirements.toml) disables every hook; doctor reports the first.
• Another CODEX_HOME. The installer and doctor follow $CODEX_HOME; run them with the same value Codex uses.
• Every turn makes a card. That's the Stop hook: Codex finished and is waiting for you. Opt in only where Codex runs unattended, set NEEDS_YOU_AGENT_TURN_CARDS=0 to keep only approval cards, or turn it off for a session with NEEDS_YOU_AGENT_ALERTS=0.

Copilot CLI hooks #

needs-you doctor has a copilot hooks line. In copilot mode the hook finishes in the background, so log to a file:

echo '{"sessionId":"t1","cwd":"'"$PWD"'","notification_type":"permission_prompt","message":"Run command: make test"}' |
  NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/tmp/ny-hook.log ~/.copilot/hooks/needs-you-hook.sh notify copilot
sleep 2; cat /tmp/ny-hook.log

Copilot-specific causes:

• Not restarted. Copilot CLI reads ~/.copilot/hooks/*.json when it starts.
• Hooks turned off. "disableAllHooks": true in ~/.copilot/settings.json or config.json; doctor reports it.
• Another COPILOT_HOME. Copilot then reads $COPILOT_HOME/hooks/ instead; run the installer and doctor with the same value.
• A card stays after Esc. Cancelling a permission prompt runs no hook in Copilot; the card goes with your next prompt or the end of the session.

Kimi Code hooks #

needs-you doctor has a kimi hooks line, and kimi doctor checks that Kimi accepts config.toml. In kimi mode the hook finishes in the background, so log to a file:

echo '{"hook_event_name":"PermissionRequest","session_id":"session_t1","cwd":"'"$PWD"'","tool_name":"Bash","display":{"command":"make test"}}' |
  NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/tmp/ny-hook.log ~/.kimi-code/hooks/needs-you-hook.sh notify kimi
sleep 2; cat /tmp/ny-hook.log

Kimi-specific causes:

• Not restarted. Kimi reads config.toml when it starts.
• Kimi refuses the config. Any key Kimi doesn't know, in any [[hooks]] entry, makes it refuse the whole file; kimi doctor names it. The needs-you block uses only event, matcher, command and timeout.
• The installer stopped. Your config.toml defines hooks as a table or an inline list: copy the entries from integrations/kimi/kimi-hooks.toml into it by hand.
• Another KIMI_CODE_HOME. Kimi then reads $KIMI_CODE_HOME/config.toml; run the installer and doctor with the same value.
• No "waiting" card from kimi -p. By design: the run has exited, so nobody is waiting (the log says skipped: kimi has exited).
• A card stays after Ctrl-C. Kimi runs no SessionEnd hook then; the 5-minute needs-you flush clears the card once Kimi has exited. Leave with /exit to clear it at once.

Grok Build hooks #

needs-you doctor has a grok hooks line, and grok inspect lists the hooks Grok loaded. In grok mode the hook finishes in the background, so log to a file:

echo '{"hook_event_name":"Notification","notificationType":"permission_prompt","session_id":"t1","cwd":"'"$PWD"'"}' |
  NEEDS_YOU_AGENT_ALERTS=1 NEEDS_YOU_HOOK_LOG=/tmp/ny-hook.log ~/.grok/hooks/needs-you-hook.sh notify grok
sleep 2; cat /tmp/ny-hook.log

Grok-specific causes:

• The "waiting" card comes a minute late. By design: it comes from Grok's idle_prompt notification, about 60 seconds after the turn, and not at all if you type first.
• Not restarted, or switched off. Grok reads ~/.grok/hooks/*.json when it starts; an entry switched off in /hooks stays off (~/.grok/disabled-hooks), and an organization policy with allow_managed_hooks_only turns off every user hook. Doctor reports both.
• Cards say Grok but come from the Claude Code hooks. Without needs-you's own Grok hooks, Grok runs the Claude Code ones, which post for it. With both installed, only the Grok ones post.
• Another GROK_HOME. Grok then reads $GROK_HOME/hooks/; run the installer and doctor with the same value.

Cursor, Cline and Aider #

needs-you doctor has cursor hooks, cline hooks and aider notifications lines. None of the three has an approval hook, so no card when the agent asks to run something: that's expected, not a fault. The hook finishes in the background in all three, so log to a file (NEEDS_YOU_HOOK_LOG=/tmp/ny-hook.log on the test commands in Cursor, Cline or Aider).

• Opted in only in your shell. Cursor and Cline in VS Code start hooks from the app, which doesn't read your shell profile. Put NEEDS_YOU_AGENT_ALERTS=1 in ~/.config/needs-you/env.
• Cursor: a prompt seems held up. The hook answers beforeSubmitPrompt with {"continue":true} before anything else. If you see it held anyway, check ~/.cursor/hooks.json for a needs-you entry under a permission hook (preToolUse, beforeShellExecution, …): doctor warns about it; re-run the installer.
• Cline: no card in VS Code. Cline's "Enable Hooks" setting is off, or one of your own hook files took the TaskComplete name (doctor says which).
• Cline: a card stays after you quit the CLI. Interactive cline sessions run in a background hub process that outlives the terminal; the card goes with your next task, when that process stops, or after 48 hours.
• Aider: no card. A .aider.conf.yml in the repo, or AIDER_NOTIFICATIONS_COMMAND, overrides the one in your home directory; or notifications: true is missing (Aider needs both keys). If the installer printed two lines instead of writing them, add them yourself.
• Aider: the card stays while you type. Aider sends nothing when you answer. It goes when Aider exits (within 5 minutes, by needs-you flush) or after NEEDS_YOU_AIDER_EXPIRY_HOURS.

GitHub poller #

• needs-you-github -v prints what it saw (notifications, PRs) and any gh error. It always exits 0, so a broken cron job is silent; after 3 failed runs in a row it posts one low card, "GitHub alerts stopped on <host>".
• gh: Bad credentials or gh auth login errors: log in again as the user cron runs as. cron and systemd have a short PATH; set NEEDS_YOU_GITHUB_GH to the full path of gh if it isn't in /usr/bin.
• Too many cards: narrow it with NEEDS_YOU_GITHUB_EXCLUDE, NEEDS_YOU_GITHUB_REASONS or NEEDS_YOU_GITHUB_PR_DAYS (integrations/github).
• A card that doesn't clear: it clears on the run after the condition goes away, or 15 minutes after the poller stops. Notification cards clear when you read the thread on GitHub.

Orca automations #

• needs-you must be on the PATH that Orca's agent terminals get. From an Orca terminal: command -v needs-you.
• An automation that stopped posting after a template re-render: the block was added to the live prompt, not the template.
• An orca:// link refused with 400: the hub no longer accepts orca:// at all (Orca has no terminal or worktree links; its only link, orca://skills/share/<id>, imports a skill). Remove it from the automation prompt or NEEDS_YOU_AGENT_LINK; the card's Terminal button (needsyou://orca/terminal) and the body's orca terminal switch command are the way back to the terminal.
• A vscode:// or cursor:// link refused with 400, or shown as plain text on an older card: only vscode://file/<abs path>[:line[:col]], vscode://vscode-remote/ssh-remote+<host>[/<path>] (or tunnel+<name>) and vscode://anthropic.claude-code/open?session=<id> are allowed, without a query string (API). The Claude Code hook posts its card again without links when the hub refuses a custom NEEDS_YOU_AGENT_LINK.
• orca terminal switch says the terminal isn't found: the agent runs on a paired Orca server. Set NEEDS_YOU_ORCA_ENVIRONMENT in ~/.config/needs-you/env on that server to the name orca environment list shows on the Mac.

This page is docs/guides/troubleshooting.md in the repo. View or edit it on GitHub.