Approve Claude Code and Codex commands from your phone with hooks
A PreToolUse hook makes Claude Code or Codex ask a person before a shell command runs, and answer from a phone. How it works and how to set it up.
· 6 min read
Claude Code and Codex ask before they run a command, in the terminal they run in. That works while you sit in front of it. Step away and the agent waits on a prompt nobody sees, or you have already switched the prompts off so it can get on with the job. Neither is what you wanted.
A PreToolUse hook gives a third option: the question goes to your phone. The agent keeps working on what it may do, and the one command that matters waits for your yes, wherever you are.
What a hook is
Both tools can run a command of yours before each tool call. The command receives the call as JSON and answers whether it may go ahead. It runs outside the model, so the model cannot talk its way past it.
{
"tool_name": "Bash",
"tool_input": { "command": "rm -rf build && npm run release" },
"cwd": "/home/ada/shop"
}The approvals hook, variantgate hook, turns that call into a request in your inbox:
{
"action": "shell.run",
"summary": "Run the command: rm -rf build && npm run release",
"details": {
"command": "rm -rf build && npm run release",
"cwd": "/home/ada/shop"
}
}It waits for a decision, and answers allow on a yes. On a no it answers deny, with the reason and an instruction not to try another way to do the same thing.
Set it up
Create an agent key for the machine under Agents, and put it in the environment the agent starts from:
export VARIANTGATE_API_URL=https://api.variantgate.com
export VARIANTGATE_KEY=gl_YOUR_KEY
# Optional: wait five minutes for a person instead of two,
# and raise the hook's timeout above 300 seconds to match
export VARIANTGATE_HOOK_WAIT=300Then the hook itself. For Claude Code, in ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "variantgate hook claude-code", "timeout": 180 }
]
}
]
}
}For Codex, in ~/.codex/config.toml. Codex asks you to trust the hook under /hooks before it runs it.
[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "variantgate hook codex"
timeout = 180Both hooks run the variantgate command. Install it once with npm install --global https://variantgate.com/sdk/variantgate-agent-latest.tgz.
Answer from your phone
Open the inbox on your phone and add it to the home screen; it then opens like an app. Turn on browser notifications under Settings, or send waiting requests to a Slack channel, and a request announces itself. The summary shows the exact command and the folder it runs in.
Choose what to gate
The matcher decides which tools go through approval. Gating every read trains you to tap yes without looking, which is worse than no gate.
- Bash
- Gate it. Shell commands are where real damage happens.
- Write, Edit
- Gate them for unattended runs; leave them for a session you watch.
- mcp__github__.*
- Gate tools of MCP servers that act on the outside world.
- Read, Grep, Glob
- Leave them. Reading changes nothing.
Requests from the hook carry actions such as shell.run, file.write and mcp.github.create_issue, so rules can answer the routine ones. A rule matches the action, not the command, so a rule for shell.run covers every command; keep that one with a person.
When nobody answers, or nothing can be reached
- The hook waits two minutes by default, then withdraws the request and denies the call. A late tap can no longer start anything. Keep the hook’s
timeoutlonger than that wait: a hook that times out does not stop the call. - If the service cannot be reached, Claude Code falls back to its own permission prompt. Codex has no such prompt for hooks, so there the call is denied.
- One switch pauses every agent: the emergency stop denies every call from every hook until an owner resumes.
Compared with the built-in permissions
Claude Code’s and Codex’s own permission settings decide on one machine, for the person sitting at it. The hook adds what they cannot give: a person deciding from anywhere, a teammate who can answer for you, and a record of every command an agent ran and who allowed it, across all your machines and agents. Use both: the built-in settings for what never needs asking, the hook for the rest.