Claude Code Setup

Two ways to use Pushary with Claude Code: MCP tools (agent sends notifications and asks questions) and permission hooks (approve or deny tool calls from your phone). Use both together for the full experience.

Setup wizard

The setup wizard configures everything in one command:

npx @pushary/agent-hooks setup

The wizard configures these files:

It will:

• Add the Pushary MCP server to ~/.claude.json
• Add permission hooks for Bash, Write, and Edit (PreToolUse)
• Add event tracking hooks (PostToolUse, Stop)
• Auto-allow Pushary MCP tools
• Save your API key to your shell profile
• Send a test notification

MCP tools

Once connected, Claude Code can use these tools:

Question types

Confirm (yes/no):

Ask me via Pushary: should I delete the 3 unused migration files?

Select (multiple choice):

Ask me via Pushary which auth strategy to use: JWT tokens, Session cookies, or OAuth2

Input (free text):

Ask me via Pushary what the new API endpoint path should be

Rich context notifications

When a task completes or fails, Claude Code sends a notification with a detail page:

Send me a Pushary notification that the refactoring is complete.
Include the files changed and suggested next steps.

The notification links to a detail page showing the summary, files changed, error messages, and next steps.

Permission hooks

Permission hooks intercept Claude Code's built-in tool approval prompts and route them through push notifications. When Claude Code wants to run a bash command or edit a file, you get a push notification to approve or deny from your phone.

Manual setup

If you didn't use the setup wizard, add the MCP server to ~/.claude.json:

{
  "mcpServers": {
    "pushary": {
      "type": "http",
      "url": "https://pushary.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer pk_xxx.xxx"
      }
    }
  }
}

Then add hooks and MCP permissions to ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__pushary__*"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pushary-hook",
            "timeout": 120
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pushary-post-hook",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pushary-stop-hook",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

And set your API key in your shell profile:

export PUSHARY_API_KEY="pk_xxx.xxx"

Timeout policies

Configure what happens when you don't respond in time at pushary.com/dashboard/agent/policies:

Auto-approve: allow the action without waiting. Use for safe read-only tools.

Auto-deny: block the action. Use for destructive tools like Bash.

Ask in terminal: fall back to Claude Code's normal terminal permission prompt. Use when you might be at your computer.

How it works

1. Claude Code wants to run bash: rm -rf ./dist
2. If you are away (When I'm out) or your mode is Every time, the hook sends a push notification: "Allow bash: rm -rf ./dist?" At the keyboard in When I'm out, the decision stays local: in Claude Code's own prompt, or on the Pushary for Mac card when the Mac app owns your hooks. In Updates your phone gets an alert only, in Terminal nothing is sent, and Claude Code's own prompt decides in both.
3. You tap Yes or No on your phone
4. Claude Code proceeds or stops based on your answer
5. If you don't respond within the timeout, the configured fallback kicks in

Agent identification

When you run multiple Claude Code sessions, each notification shows which session is asking. The hook automatically labels notifications as Claude Code - {project folder name}.

Install the skill

For better agent behavior, install the Pushary skill:

npx skills add Pushary/pushary-skill

The skill teaches Claude Code when to send notifications proactively (after multi-step tasks, on errors) and how to write concise notification copy.

Verify a real approval

A setup notification or pushary doctor --roundtrip tests delivery and answer return. It does not invoke Claude Code's hooks. The Mac app's phone test is also separate from hook activation.

1. Finish sign-in and checkout, connect Claude Code, then restart Claude Code so it reads the installed hooks. Keep your normal permissions. If your current mode auto-allows the action or keeps approval in the terminal, that cannot prove a remote Pushary answer was consumed.

2. In an empty scratch folder, generate a new path for this attempt in the terminal where you will run the diagnostic:

   TARGET="$PWD/pushary-activation-$(node -p 'require("node:crypto").randomUUID()').txt"
   printf '%s\n' "$TARGET"

   Ask Claude Code: “Use the Write tool to create this exact absolute path, containing Pushary activation check. Do not run other commands or answer any approval yourself.” Include the printed path. Approve that Write request yourself on your chosen surface and check that the file appears with the expected content.

3. On builds with the activation diagnostic, run pushary doctor --activation claude_code --activation-target "$TARGET" --no-push --json. It reads the runtime-tagged Write decision for that exact target from the last ten minutes on this machine and workspace. approved_executed means a matching runtime completion was recorded after the answer. Save the decision, session and tool-call IDs, answer source and transport alongside claude --version, pushary --version, and the Mac app version when applicable. Credentials and file contents are excluded from the evidence.

4. Generate another new target and repeat, this time denying the request yourself. Confirm that the file was not created. denied_observed requires a matching runtime denial event. Some host paths do not emit that event: those stay unverified; absence of a completion event alone never proves denial. Record the actual host result for interactive acceptance.

5. Restart the agent and repeat with a new target. For the negative control, remove only the Pushary hooks in an isolated test profile and generate another new target: a synthetic round trip may still pass, but that attempt must not produce correlated hook evidence. Restore the test profile afterward. Never reuse a prior target: its historical approval does not test your current configuration.

The reader never creates a question or changes permissions. unexpected_execution means a matching completion was reported after a denial and must be investigated; tool_failed means the host reported a tool error. Unknown answer sources, synthetic questions, duplicate decisions, reused targets, missing hooks and stale evidence remain unverified. Queued events retain their original runtime timestamp; missing or inconsistent client clocks leave the check unverified. These are runtime-reported observations, not independently attested execution. If no approval appeared, check the agent's permission mode and the existing Pushary delivery policy before repairing configuration. On CLI-owned hooks, run pushary doctor; on Mac-owned hooks, use the Mac app's agent setup and recovery controls. Preserve the existing owner.

Cancel an active test in the agent or on its existing approval surface. The hook owns its normal deadline and retirement path; stopping the read-only diagnostic does not cancel an unrelated agent request. A successful diagnostic is evidence for that one invocation, not a guarantee that every agent or future request is configured correctly. Real allow/deny, restart and released-build acceptance are still required.