deferred-tools.md

CronCreate

Schedule a prompt to be enqueued at a future time. Use for both recurring schedules and one-shot reminders.

Uses standard 5-field cron in the user's local timezone: minute hour day-of-month month day-of-week. "0 9 * * *" means 9am local — no timezone conversion needed.

One-shot tasks (recurring: false)

For "remind me at X" or "at , do Y" requests — fire once then auto-delete. Pin minute/hour/day-of-month/month to specific values: "remind me at 2:30pm today to check the deploy" → cron: "30 14 <today_dom> <today_month> *", recurring: false "tomorrow morning, run the smoke test" → cron: "57 8 <tomorrow_dom> <tomorrow_month> *", recurring: false

Recurring jobs (recurring: true, the default)

For "every N minutes" / "every hour" / "weekdays at 9am" requests: "*/5 * * * *" (every 5 min), "0 * * * *" (hourly), "0 9 * * 1-5" (weekdays at 9am local)

Avoid the :00 and :30 minute marks when the task allows it

Every user who asks for "9am" gets 0 9, and every user who asks for "hourly" gets 0 * — which means requests from across the planet land on the API at the same instant. When the user's request is approximate, pick a minute that is NOT 0 or 30: "every morning around 9" → "57 8 * * *" or "3 9 * * *" (not "0 9 * * *") "hourly" → "7 * * * *" (not "0 * * * *") "in an hour or so, remind me to..." → pick whatever minute you land on, don't round

Only use minute 0 or 30 when the user names that exact time and clearly means it ("at 9:00 sharp", "at half past", coordinating with a meeting). When in doubt, nudge a few minutes early or late — the user will not notice, and the fleet will.

Session-only

Jobs live only in this Claude session — nothing is written to disk, and the job is gone when Claude exits.

Not for live watching

CronCreate re-runs a prompt at fixed wall-clock intervals. To watch a log file, process, or command output and be notified the moment something changes, use the Monitor tool instead — Monitor streams events as they happen; cron polls on a schedule.

Runtime behavior

Jobs only fire while the REPL is idle (not mid-query). The scheduler adds a small deterministic jitter on top of whatever you pick: recurring tasks fire up to 10% of their period late (max 15 min); one-shot tasks landing on :00 or :30 fire up to 90 s early. Picking an off-minute is still the bigger lever.

Recurring tasks auto-expire after 7 days — they fire one final time, then are deleted. This bounds session lifetime. Tell the user about the 7-day limit when scheduling recurring jobs.

Returns a job ID you can pass to CronDelete.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "cron": {
      "description": "Standard 5-field cron expression in local time: \"M H DoM Mon DoW\" (e.g. \"*/5 * * * *\" = every 5 minutes, \"30 14 28 2 *\" = Feb 28 at 2:30pm local once).",
      "type": "string"
    },
    "durable": {
      "description": "true = persist to .claude/scheduled_tasks.json and survive restarts. false (default) = in-memory only, dies when this Claude session ends. Use true only when the user asks the task to survive across sessions.",
      "type": "boolean"
    },
    "prompt": {
      "description": "The prompt to enqueue at each fire time.",
      "type": "string"
    },
    "recurring": {
      "description": "true (default) = fire on every cron match until deleted or auto-expired after 7 days. false = fire once at the next match, then auto-delete. Use false for \"remind me at X\" one-shot requests with pinned minute/hour/dom/month.",
      "type": "boolean"
    }
  },
  "required": ["cron", "prompt"],
  "type": "object"
}

---

CronDelete

Cancel a cron job previously scheduled with CronCreate. Removes it from the in-memory session store.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Job ID returned by CronCreate.",
      "type": "string"
    }
  },
  "required": ["id"],
  "type": "object"
}

---

CronList

List all cron jobs scheduled via CronCreate in this session.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

---

EnterPlanMode

Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.

When to Use This Tool

Prefer using EnterPlanMode for implementation tasks unless they're simple. Use it when ANY of these conditions apply:

1. New Feature Implementation: Adding meaningful new functionality

   • Example: "Add a logout button" - where should it go? What should happen on click?
   • Example: "Add form validation" - what rules? What error messages?

2. Multiple Valid Approaches: The task can be solved in several different ways

   • Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
   • Example: "Improve performance" - many optimization strategies possible

3. Code Modifications: Changes that affect existing behavior or structure

   • Example: "Update the login flow" - what exactly should change?
   • Example: "Refactor this component" - what's the target architecture?

4. Architectural Decisions: The task requires choosing between patterns or technologies

   • Example: "Add real-time updates" - WebSockets vs SSE vs polling
   • Example: "Implement state management" - Redux vs Context vs custom solution

5. Multi-File Changes: The task will likely touch more than 2-3 files

   • Example: "Refactor the authentication system"
   • Example: "Add a new API endpoint with tests"

6. Unclear Requirements: You need to explore before understanding the full scope

   • Example: "Make the app faster" - need to profile and identify bottlenecks
   • Example: "Fix the bug in checkout" - need to investigate root cause

7. User Preferences Matter: The implementation could reasonably go multiple ways

   • If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
   • Plan mode lets you explore first, then present options with context

When NOT to Use This Tool

Only skip EnterPlanMode for simple tasks:

• Single-line or few-line fixes (typos, obvious bugs, small tweaks)
• Adding a single function with clear requirements
• Tasks where the user has given very specific, detailed instructions
• Pure research/exploration tasks (use the Agent tool with explore agent instead)

What Happens in Plan Mode

In plan mode, you'll:

1. Thoroughly explore the codebase using find/Glob, grep/Grep, and Read
2. Understand existing patterns and architecture
3. Design an implementation approach
4. Present your plan to the user for approval
5. Use AskUserQuestion if you need to clarify approaches
6. Exit plan mode with ExitPlanMode when ready to implement

Examples

GOOD - Use EnterPlanMode:

User: "Add user authentication to the app"

• Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)

User: "Optimize the database queries"

• Multiple approaches possible, need to profile first, significant impact

User: "Implement dark mode"

• Architectural decision on theme system, affects many components

User: "Add a delete button to the user profile"

• Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates

User: "Update the error handling in the API"

• Affects multiple files, user should approve the approach

BAD - Don't use EnterPlanMode:

User: "Fix the typo in the README"

• Straightforward, no planning needed

User: "Add a console.log to debug this function"

• Simple, obvious implementation

User: "What files handle routing?"

• Research task, not implementation planning

Important Notes

• This tool REQUIRES user approval - they must consent to entering plan mode
• If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
• Users appreciate being consulted before significant changes are made to their codebase

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

---

EnterWorktree

Use this tool ONLY when explicitly instructed to work in a worktree — either by the user directly, or by project instructions (CLAUDE.md / memory). This tool creates an isolated git worktree and switches the current session into it.

When to Use

• The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
• CLAUDE.md or memory instructions direct you to work in a worktree for the current task

When NOT to Use

• The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
• The user asks to fix a bug or work on a feature — use normal git workflow unless worktrees are explicitly requested by the user or project instructions
• Never use this tool unless "worktree" is explicitly mentioned by the user or in CLAUDE.md / memory instructions

Requirements

• Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
• Must not already be in a worktree

Behavior

• In a git repository: creates a new git worktree inside .claude/worktrees/ on a new branch. The base ref is governed by the worktree.baseRef setting: fresh (default) branches from origin/; head branches from your current local HEAD
• Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
• Switches the session's working directory to the new worktree
• Use ExitWorktree to leave the worktree mid-session (keep or remove). On session exit, if still in the worktree, the user will be prompted to keep or remove it

Entering an existing worktree

Pass path instead of name to switch the session into a worktree that already exists (e.g., one you just created with git worktree add). The path must appear in git worktree list for the current repository — paths that are not registered worktrees of this repo are rejected. ExitWorktree will not remove a worktree entered this way; use action: "keep" to return to the original directory.

Parameters

• name (optional): A name for a new worktree. If neither name nor path is provided, a random name is generated.
• path (optional): Path to an existing worktree of the current repository to enter instead of creating one. Mutually exclusive with name.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "name": {
      "description": "Optional name for a new worktree. Each \"/\"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. A random name is generated if not provided. Mutually exclusive with `path`.",
      "type": "string"
    },
    "path": {
      "description": "Path to an existing worktree of the current repository to switch into instead of creating a new one. Must appear in `git worktree list` for the current repo. Mutually exclusive with `name`.",
      "type": "string"
    }
  },
  "type": "object"
}

---

ExitPlanMode

Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.

How This Tool Works

• You should have already written your plan to the plan file specified in the plan mode system message
• This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
• This tool simply signals that you're done planning and ready for the user to review and approve
• The user will see the contents of your plan file when they review it

When to Use This Tool

IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.

Before Using This Tool

Ensure your plan is complete and unambiguous:

• If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
• Once your plan is finalized, use THIS tool to request approval

Important: Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.

Examples

1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {},
  "properties": {
    "allowedPrompts": {
      "description": "Prompt-based permissions needed to implement the plan. These describe categories of actions rather than specific commands.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "prompt": {
            "description": "Semantic description of the action, e.g. \"run tests\", \"install dependencies\"",
            "type": "string"
          },
          "tool": {
            "description": "The tool this prompt applies to",
            "enum": ["Bash"],
            "type": "string"
          }
        },
        "required": ["tool", "prompt"],
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

---

ExitWorktree

Exit a worktree session created by EnterWorktree and return the session to the original working directory.

Scope

This tool ONLY operates on worktrees created by EnterWorktree in this session. It will NOT touch:

• Worktrees you created manually with git worktree add
• Worktrees from a previous session (even if created by EnterWorktree then)
• The directory you're in if EnterWorktree was never called

If called outside an EnterWorktree session, the tool is a no-op: it reports that no worktree session is active and takes no action. Filesystem state is unchanged.

When to Use

• The user explicitly asks to "exit the worktree", "leave the worktree", "go back", or otherwise end the worktree session
• Do NOT call this proactively — only when the user asks

Parameters

• action (required): "keep" or "remove"
  • "keep" — leave the worktree directory and branch intact on disk. Use this if the user wants to come back to the work later, or if there are changes to preserve.
  • "remove" — delete the worktree directory and its branch. Use this for a clean exit when the work is done or abandoned.
• discard_changes (optional, default false): only meaningful with action: "remove". If the worktree has uncommitted files or commits not on the original branch, the tool will REFUSE to remove it unless this is set to true. If the tool returns an error listing changes, confirm with the user before re-invoking with discard_changes: true.

Behavior

• Restores the session's working directory to where it was before EnterWorktree
• Clears CWD-dependent caches (system prompt sections, memory files, plans directory) so the session state reflects the original directory
• If a tmux session was attached to the worktree: killed on remove, left running on keep (its name is returned so the user can reattach)
• Once exited, EnterWorktree can be called again to create a fresh worktree

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "action": {
      "description": "\"keep\" leaves the worktree and branch on disk; \"remove\" deletes both.",
      "enum": ["keep", "remove"],
      "type": "string"
    },
    "discard_changes": {
      "description": "Required true when action is \"remove\" and the worktree has uncommitted files or unmerged commits. The tool will refuse and list them otherwise.",
      "type": "boolean"
    }
  },
  "required": ["action"],
  "type": "object"
}

---

Monitor

Start a background monitor that streams events from a long-running script. Each stdout line is an event — you keep working and notifications arrive in the chat. Events arrive on their own schedule and are not replies from the user, even if one lands while you're waiting for the user to answer a question.

Pick by how many notifications you need:

• One ("tell me when the server is ready / the build finishes") → use Bash with run_in_background and a command that exits when the condition is true, e.g. until grep -q "Ready in" dev.log; do sleep 0.5; done. You get a single completion notification when it exits.
• One per occurrence, indefinitely ("tell me every time an ERROR line appears") → Monitor with an unbounded command (tail -f, inotifywait -m, while true).
• One per occurrence, until a known end ("emit each CI step result, stop when the run completes") → Monitor with a command that emits lines and then exits.

Your script's stdout is the event stream. Each line becomes a notification. Exit ends the watch.

Each matching log line is an event

tail -f /var/log/app.log | grep --line-buffered "ERROR"

Each file change is an event

inotifywait -m --format '%e %f' /watched/dir

Poll GitHub for new PR comments and emit one line per new comment

last=$(date -u +%Y-%m-%dT%H:%M:%SZ) while true; do now=$(date -u +%Y-%m-%dT%H:%M:%SZ) gh api "repos/owner/repo/issues/123/comments?since=$last" --jq '.[] | "(.user.login): (.body)"' last=$now; sleep 30 done

Node script that emits events as they arrive (e.g. WebSocket listener)

node watch-for-events.js

Per-occurrence with a natural end: emit each CI check as it lands, exit when the run completes

prev="" while true; do s=$(gh pr checks 123 --json name,bucket) cur=$(jq -r '.[] | select(.bucket!="pending") | "(.name): (.bucket)"' <<<"$s" | sort) comm -13 <(echo "$prev") <(echo "$cur") prev=$cur jq -e 'all(.bucket!="pending")' <<<"$s" >/dev/null && break sleep 30 done

Don't use an unbounded command for a single notification. tail -f, inotifywait -m, and while true never exit on their own, so the monitor stays armed until timeout even after the event has fired. For "tell me when X is ready," use Bash run_in_background with an until loop instead (one notification, ends in seconds). Note that tail -f log | grep -m 1 ... does not fix this: if the log goes quiet after the match, tail never receives SIGPIPE and the pipeline hangs anyway.

Script quality:

• Always use grep --line-buffered in pipes — without it, pipe buffering delays events by minutes.
• In poll loops, handle transient failures (curl ... || true) — one failed request shouldn't kill the monitor.
• Poll intervals: 30s+ for remote APIs (rate limits), 0.5-1s for local checks.
• Write a specific description — it appears in every notification ("errors in deploy.log" not "watching logs").
• Only stdout is the event stream. Stderr goes to the output file (readable via Read) but does not trigger notifications — for a command you run directly (e.g. python train.py 2>&1 | grep --line-buffered ...), merge stderr with 2>&1 so its failures reach your filter. (No effect on tail -f of an existing log — that file only contains what its writer redirected.)

Coverage — silence is not success. When watching a job or process for an outcome, your filter must match every terminal state, not just the happy path. A monitor that greps only for the success marker stays silent through a crashloop, a hung process, or an unexpected exit — and silence looks identical to "still running." Before arming, ask: if this process crashed right now, would my filter emit anything? If not, widen it.

Wrong — silent on crash, hang, or any non-success exit

tail -f run.log | grep --line-buffered "elapsed_steps="

Right — one alternation covering progress + the failure signatures you'd act on

tail -f run.log | grep -E --line-buffered "elapsed_steps=|Traceback|Error|FAILED|assert|Killed|OOM"

For poll loops checking job state, emit on every terminal status (succeeded|failed|cancelled|timeout), not just success. If you cannot confidently enumerate the failure signatures, broaden the grep alternation rather than narrow it — some extra noise is better than missing a crashloop.

Output volume: Every stdout line is a conversation message, so the filter should be selective — but selective means "the lines you'd act on," not "only good news." Never pipe raw logs; use grep --line-buffered, awk, or a wrapper that emits exactly the success and failure signals you care about. Monitors that produce too many events are automatically stopped; restart with a tighter filter if this happens.

Stdout lines within 200ms are batched into a single notification, so multiline output from a single event groups naturally.

The script runs in the same shell environment as Bash. Exit ends the watch (exit code is reported). Timeout → killed. Set persistent: true for session-length watches (PR monitoring, log tails) — the monitor runs until you call TaskStop or the session ends. Use TaskStop to cancel early.

When an event lands that the user would want to act on now — an error appeared, the status they were waiting on flipped — send a PushNotification. Not every event is worth a push; the ones that change what they'd do next are.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "command": {
      "description": "Shell command or script. Each stdout line is an event; exit ends the watch.",
      "type": "string"
    },
    "description": {
      "description": "Short human-readable description of what you are monitoring (shown in notifications).",
      "type": "string"
    },
    "persistent": {
      "default": false,
      "description": "Run for the lifetime of the session (no timeout). Use for session-length watches like PR monitoring or log tails. Stop with TaskStop.",
      "type": "boolean"
    },
    "timeout_ms": {
      "default": 300000,
      "description": "Kill the monitor after this deadline. Default 300000ms, max 3600000ms. Ignored when persistent is true.",
      "minimum": 1000,
      "type": "number"
    }
  },
  "required": ["description", "timeout_ms", "persistent", "command"],
  "type": "object"
}

---

NotebookEdit

Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "cell_id": {
      "description": "The ID of the cell to edit. When inserting a new cell, the new cell will be inserted after the cell with this ID, or at the beginning if not specified.",
      "type": "string"
    },
    "cell_type": {
      "description": "The type of the cell (code or markdown). If not specified, it defaults to the current cell type. If using edit_mode=insert, this is required.",
      "enum": ["code", "markdown"],
      "type": "string"
    },
    "edit_mode": {
      "description": "The type of edit to make (replace, insert, delete). Defaults to replace.",
      "enum": ["replace", "insert", "delete"],
      "type": "string"
    },
    "new_source": {
      "description": "The new source for the cell",
      "type": "string"
    },
    "notebook_path": {
      "description": "The absolute path to the Jupyter notebook file to edit (must be absolute, not relative)",
      "type": "string"
    }
  },
  "required": ["notebook_path", "new_source"],
  "type": "object"
}

---

PushNotification

This tool sends a desktop notification in the user's terminal. If Remote Control is connected, it also pushes to their phone. Either way, it pulls their attention from whatever they're doing — a meeting, another task, dinner — to this session. That's the cost. The benefit is they learn something now that they'd want to know now: a long task finished while they were away, a build is ready, you've hit something that needs their decision before you can continue.

Because a notification they didn't need is annoying in a way that accumulates, err toward not sending one. Don't notify for routine progress, or to announce you've answered something they asked seconds ago and are clearly still watching, or when a quick task completes. Notify when there's a real chance they've walked away and there's something worth coming back for — or when they've explicitly asked you to notify them.

Keep the message under 200 characters, one line, no markdown. Lead with what they'd act on — "build failed: 2 auth tests" tells them more than "task done" and more than a status dump.

If the result says the push wasn't sent, that's expected — no action needed.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "message": {
      "description": "The notification body. Keep it under 200 characters; mobile OSes truncate.",
      "minLength": 1,
      "type": "string"
    },
    "status": {
      "const": "proactive",
      "type": "string"
    }
  },
  "required": ["message", "status"],
  "type": "object"
}

---

RemoteTrigger

Call the claude.ai remote-trigger API. Use this instead of curl — the OAuth token is added automatically in-process and never exposed.

Actions:

• list: GET /v1/code/triggers
• get: GET /v1/code/triggers/{trigger_id}
• create: POST /v1/code/triggers (requires body)
• update: POST /v1/code/triggers/{trigger_id} (requires body, partial update)
• run: POST /v1/code/triggers/{trigger_id}/run (optional body)

The response is the raw JSON from the API. For create/update, a summary line is appended with the server-parsed run time and the routine's claude.ai URL — relay both to the user so they can confirm the time is right and know where the result will appear.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "action": {
      "enum": ["list", "get", "create", "update", "run"],
      "type": "string"
    },
    "body": {
      "additionalProperties": {},
      "description": "Required for create and update; optional for run",
      "propertyNames": {"type": "string"},
      "type": "object"
    },
    "trigger_id": {
      "description": "Required for get, update, and run",
      "pattern": "^[\\w-]+$",
      "type": "string"
    }
  },
  "required": ["action"],
  "type": "object"
}

---

ScheduleWakeup

Schedule when to resume work in /loop dynamic mode — the user invoked /loop without an interval, asking you to self-pace iterations of a specific task.

Do NOT schedule a short-interval wakeup to poll for background work you started — when harness-tracked work finishes, you are re-invoked automatically, so polling is wasted. Instead schedule a long fallback (1200s+) so the loop survives if the work hangs or never notifies. The exception is external work the harness cannot track (a CI run, a deploy, a remote queue) — there, pick a delay matched to how fast that state actually changes.

Pass the same /loop prompt back via prompt each turn so the next firing repeats the task. For an autonomous /loop (no user prompt), pass the literal sentinel <<autonomous-loop-dynamic>> as prompt instead — the runtime resolves it back to the autonomous-loop instructions at fire time. (There is a similar <<autonomous-loop>> sentinel for CronCreate-based autonomous loops; do not confuse the two — ScheduleWakeup always uses the -dynamic variant.) Omit the call to end the loop.

Picking delaySeconds

The Anthropic prompt cache has a 5-minute TTL. Sleeping past 300 seconds means the next wake-up reads your full conversation context uncached — slower and more expensive. So the natural breakpoints:

• Under 5 minutes (60s–270s): cache stays warm. Right for actively polling external state the harness can't notify you about — a CI run, a deploy, a remote queue.
• 5 minutes to 1 hour (300s–3600s): pay the cache miss. Right when there's no point checking sooner — waiting on something that takes minutes to change, genuinely idle, or as the long fallback heartbeat when something else is the primary wake signal.

Don't pick 300s. It's the worst-of-both: you pay the cache miss without amortizing it. If you're tempted to "wait 5 minutes," either drop to 270s (stay in cache) or commit to 1200s+ (one cache miss buys a much longer wait). Don't think in round-number minutes — think in cache windows.

For idle ticks with no specific signal to watch, default to 1200s–1800s (20–30 min). The loop checks back, you don't burn cache 12× per hour for nothing, and the user can always interrupt if they need you sooner.

Think about what you're actually waiting for, not just "how long should I sleep." If you're polling a CI run that takes ~8 minutes, sleeping 60s burns the cache 8 times before it finishes — sleep ~270s twice instead.

The runtime clamps to [60, 3600], so you don't need to clamp yourself.

The reason field

One short sentence on what you chose and why. Goes to telemetry and is shown back to the user. "watching CI run" beats "waiting." The user reads this to understand what you're doing without having to predict your cadence in advance — make it specific.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "delaySeconds": {
      "description": "Seconds from now to wake up. Clamped to [60, 3600] by the runtime.",
      "type": "number"
    },
    "prompt": {
      "description": "The /loop input to fire on wake-up. Pass the same /loop input verbatim each turn so the next firing re-enters the skill and continues the loop. For autonomous /loop (no user prompt), pass the literal sentinel `<<autonomous-loop-dynamic>>` instead (the dynamic-pacing variant, not the CronCreate-mode `<<autonomous-loop>>`).",
      "type": "string"
    },
    "reason": {
      "description": "One short sentence explaining the chosen delay. Goes to telemetry and is shown to the user. Be specific.",
      "type": "string"
    }
  },
  "required": ["delaySeconds", "reason", "prompt"],
  "type": "object"
}

---

SendMessage

Send a message to another agent.

{"to": "researcher", "summary": "assign task 1", "message": "start on task #1"}

Your plain text output is NOT visible to other agents — to communicate, you MUST call this tool. Messages from teammates are delivered automatically; you don't check an inbox. Refer to active teammates by name; to resume a completed background agent, use the agentId (format a...-...) from its spawn result. When relaying, don't quote the original — it's already rendered to the user.

Protocol responses (legacy)

If you receive a JSON message with type: "shutdown_request" or type: "plan_approval_request", respond with the matching _response type — echo the request_id, set approve true/false:

{"to": "team-lead", "message": {"type": "shutdown_response", "request_id": "...", "approve": true}}
{"to": "researcher", "message": {"type": "plan_approval_response", "request_id": "...", "approve": false, "feedback": "add error handling"}}

Approving shutdown terminates your process. Rejecting plan sends the teammate back to revise. Don't originate shutdown_request unless asked. Don't send structured JSON status messages — use TaskUpdate.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "message": {
      "anyOf": [
        {"description": "Plain text message content", "type": "string"},
        {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "reason": {"type": "string"},
                "type": {"const": "shutdown_request", "type": "string"}
              },
              "required": ["type"],
              "type": "object"
            },
            {
              "additionalProperties": false,
              "properties": {
                "approve": {"type": "boolean"},
                "reason": {"type": "string"},
                "request_id": {"type": "string"},
                "type": {"const": "shutdown_response", "type": "string"}
              },
              "required": ["type", "request_id", "approve"],
              "type": "object"
            },
            {
              "additionalProperties": false,
              "properties": {
                "approve": {"type": "boolean"},
                "feedback": {"type": "string"},
                "request_id": {"type": "string"},
                "type": {"const": "plan_approval_response", "type": "string"}
              },
              "required": ["type", "request_id", "approve"],
              "type": "object"
            }
          ]
        }
      ]
    },
    "summary": {
      "description": "A 5-10 word summary shown as a preview in the UI (required when message is a string)",
      "type": "string"
    },
    "to": {
      "description": "Recipient: teammate name",
      "type": "string"
    }
  },
  "required": ["to", "message"],
  "type": "object"
}

---

TaskCreate

Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user. It also helps the user understand the progress of the task and overall progress of their requests.

When to Use This Tool

Use this tool proactively in these scenarios:

• Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
• Non-trivial and complex tasks - Tasks that require careful planning or multiple operations and potentially assigned to teammates
• Plan mode - When using plan mode, create a task list to track the work
• User explicitly requests todo list - When the user directly asks you to use the todo list
• User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
• After receiving new instructions - Immediately capture user requirements as tasks
• When you start working on a task - Mark it as in_progress BEFORE beginning work
• After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation

When NOT to Use This Tool

Skip using this tool when:

• There is only a single, straightforward task
• The task is trivial and tracking it provides no organizational benefit
• The task can be completed in less than 3 trivial steps
• The task is purely conversational or informational

NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.

Task Fields

• subject: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
• description: What needs to be done
• activeForm (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.

All tasks are created with status pending.

Tips

• Create tasks with clear, specific subjects that describe the outcome
• After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
• Include enough detail in the description for another agent to understand and complete the task
• New tasks are created with status 'pending' and no owner - use TaskUpdate with the owner parameter to assign them
• Check TaskList first to avoid creating duplicate tasks

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "activeForm": {
      "description": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")",
      "type": "string"
    },
    "description": {
      "description": "What needs to be done",
      "type": "string"
    },
    "metadata": {
      "additionalProperties": {},
      "description": "Arbitrary metadata to attach to the task",
      "propertyNames": {"type": "string"},
      "type": "object"
    },
    "subject": {
      "description": "A brief title for the task",
      "type": "string"
    }
  },
  "required": ["subject", "description"],
  "type": "object"
}

---

TaskGet

Use this tool to retrieve a task by its ID from the task list.

When to Use This Tool

• When you need the full description and context before starting work on a task
• To understand task dependencies (what it blocks, what blocks it)
• After being assigned a task, to get complete requirements

Output

Returns full task details:

• subject: Task title
• description: Detailed requirements and context
• status: 'pending', 'in_progress', or 'completed'
• blocks: Tasks waiting on this one to complete
• blockedBy: Tasks that must complete before this one can start

Tips

• After fetching a task, verify its blockedBy list is empty before beginning work.
• Use TaskList to see all tasks in summary form.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "taskId": {
      "description": "The ID of the task to retrieve",
      "type": "string"
    }
  },
  "required": ["taskId"],
  "type": "object"
}

---

TaskList

Use this tool to list all tasks in the task list.

When to Use This Tool

• To see what tasks are available to work on (status: 'pending', no owner, not blocked)
• To check overall progress on the project
• To find tasks that are blocked and need dependencies resolved
• Before assigning tasks to teammates, to see what's available
• After completing a task, to check for newly unblocked work or claim the next available task
• Prefer working on tasks in ID order (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones

Output

Returns a summary of each task:

• id: Task identifier (use with TaskGet, TaskUpdate)
• subject: Brief description of the task
• status: 'pending', 'in_progress', or 'completed'
• owner: Agent ID if assigned, empty if available
• blockedBy: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)

Use TaskGet with a specific task ID to view full details including description and comments.

Teammate Workflow

When working as a teammate:

1. After completing your current task, call TaskList to find available work
2. Look for tasks with status 'pending', no owner, and empty blockedBy
3. Prefer tasks in ID order (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
4. Claim an available task using TaskUpdate (set owner to your name), or wait for leader assignment
5. If blocked, focus on unblocking tasks or notify the team lead

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

---

TaskOutput

DEPRECATED: Background tasks return their output file path in the tool result, and you receive a with the same path when the task completes.

• For bash tasks: prefer using the Read tool on that output file path — it contains stdout/stderr.

• For local_agent tasks: use the Agent tool result directly. Do NOT Read the .output file — it is a symlink to the full sub-agent conversation transcript (JSONL) and will overflow your context window.

• For remote_agent tasks: prefer using the Read tool on the output file path — it contains the streamed remote session output (same as bash).

• Retrieves output from a running or completed task (background shell, agent, or remote session)

• Takes a task_id parameter identifying the task

• Returns the task output along with status information

• Use block=true (default) to wait for task completion

• Use block=false for non-blocking check of current status

• Task IDs can be found using the /tasks command

• Works with all task types: background shells, async agents, and remote sessions

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "block": {
      "default": true,
      "description": "Whether to wait for completion",
      "type": "boolean"
    },
    "task_id": {
      "description": "The task ID to get output from",
      "type": "string"
    },
    "timeout": {
      "default": 30000,
      "description": "Max wait time in ms",
      "maximum": 600000,
      "minimum": 0,
      "type": "number"
    }
  },
  "required": ["task_id", "block", "timeout"],
  "type": "object"
}

---

TaskStop

• Stops a running background task by its ID
• Takes a task_id parameter identifying the task to stop
• Returns a success or failure status
• Use this tool when you need to terminate a long-running task

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "shell_id": {
      "description": "Deprecated: use task_id instead",
      "type": "string"
    },
    "task_id": {
      "description": "The ID of the background task to stop",
      "type": "string"
    }
  },
  "type": "object"
}

---

TaskUpdate

Use this tool to update a task in the task list.

When to Use This Tool

Mark tasks as resolved:

• When you have completed the work described in a task

• When a task is no longer needed or has been superseded

• IMPORTANT: Always mark your assigned tasks as resolved when you finish them

• After resolving, call TaskList to find your next task

• ONLY mark a task as completed when you have FULLY accomplished it

• If you encounter errors, blockers, or cannot finish, keep the task as in_progress

• When blocked, create a new task describing what needs to be resolved

• Never mark a task as completed if:

  • Tests are failing
  • Implementation is partial
  • You encountered unresolved errors
  • You couldn't find necessary files or dependencies

Delete tasks:

• When a task is no longer relevant or was created in error
• Setting status to deleted permanently removes the task

Update task details:

• When requirements change or become clearer
• When establishing dependencies between tasks

Fields You Can Update

• status: The task status (see Status Workflow below)
• subject: Change the task title (imperative form, e.g., "Run tests")
• description: Change the task description
• activeForm: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
• owner: Change the task owner (agent name)
• metadata: Merge metadata keys into the task (set a key to null to delete it)
• addBlocks: Mark tasks that cannot start until this one completes
• addBlockedBy: Mark tasks that must complete before this one can start

Status Workflow

Status progresses: pending → in_progress → completed

Use deleted to permanently remove a task.

Staleness

Make sure to read a task's latest state using TaskGet before updating it.

Examples

Mark task as in progress when starting work:

{"taskId": "1", "status": "in_progress"}

Mark task as completed after finishing work:

{"taskId": "1", "status": "completed"}

Delete a task:

{"taskId": "1", "status": "deleted"}

Claim a task by setting owner:

{"taskId": "1", "owner": "my-name"}

Set up task dependencies:

{"taskId": "2", "addBlockedBy": ["1"]}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "activeForm": {
      "description": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")",
      "type": "string"
    },
    "addBlockedBy": {
      "description": "Task IDs that block this task",
      "items": {"type": "string"},
      "type": "array"
    },
    "addBlocks": {
      "description": "Task IDs that this task blocks",
      "items": {"type": "string"},
      "type": "array"
    },
    "description": {
      "description": "New description for the task",
      "type": "string"
    },
    "metadata": {
      "additionalProperties": {},
      "description": "Metadata keys to merge into the task. Set a key to null to delete it.",
      "propertyNames": {"type": "string"},
      "type": "object"
    },
    "owner": {
      "description": "New owner for the task",
      "type": "string"
    },
    "status": {
      "anyOf": [
        {"enum": ["pending", "in_progress", "completed"], "type": "string"},
        {"const": "deleted", "type": "string"}
      ],
      "description": "New status for the task"
    },
    "subject": {
      "description": "New subject for the task",
      "type": "string"
    },
    "taskId": {
      "description": "The ID of the task to update",
      "type": "string"
    }
  },
  "required": ["taskId"],
  "type": "object"
}

---

TeamCreate

When to Use

Use this tool proactively whenever:

• The user explicitly asks to use a team, swarm, or group of agents
• The user mentions wanting agents to work together, coordinate, or collaborate
• A task is complex enough that it would benefit from parallel work by multiple agents (e.g., building a full-stack feature with frontend and backend work, refactoring a codebase while keeping tests passing, implementing a multi-step project with research, planning, and coding phases)

When in doubt about whether a task warrants a team, prefer spawning a team.

Choosing Agent Types for Teammates

When spawning teammates via the Agent tool, choose the subagent_type based on what tools the agent needs for its task. Each agent type has a different set of available tools — match the agent to the work:

• Read-only agents (e.g., Explore, Plan) cannot edit or write files. Only assign them research, search, or planning tasks. Never assign them implementation work.
• Full-capability agents (e.g., general-purpose) have access to all tools including file editing, writing, and bash. Use these for tasks that require making changes.
• Custom agents defined in .claude/agents/ may have their own tool restrictions. Check their descriptions to understand what they can and cannot do.

Always review the agent type descriptions and their available tools listed in the Agent tool prompt before selecting a subagent_type for a teammate.

Create a new team to coordinate multiple agents working on a project. Teams have a 1:1 correspondence with task lists (Team = TaskList).

{
  "team_name": "my-project",
  "description": "Working on feature X"
}

This creates:

• A team file at ~/.claude/teams/{team-name}/config.json
• A corresponding task list directory at ~/.claude/tasks/{team-name}/

Team Workflow

1. Create a team with TeamCreate - this creates both the team and its task list
2. Create tasks using the Task tools (TaskCreate, TaskList, etc.) - they automatically use the team's task list
3. Spawn teammates using the Agent tool with team_name and name parameters to create teammates that join the team
4. Assign tasks using TaskUpdate with owner to give tasks to idle teammates
5. Teammates work on assigned tasks and mark them completed via TaskUpdate
6. Teammates go idle between turns - after each turn, teammates automatically go idle and send a notification. IMPORTANT: Be patient with idle teammates! Don't comment on their idleness until it actually impacts your work.
7. Shutdown your team - when the task is completed, gracefully shut down your teammates via SendMessage with message: {type: "shutdown_request"}.

Task Ownership

Tasks are assigned using TaskUpdate with the owner parameter. Any agent can set or change task ownership via TaskUpdate.

Automatic Message Delivery

IMPORTANT: Messages from teammates are automatically delivered to you. You do NOT need to manually check your inbox.

When you spawn teammates:

• They will send you messages when they complete tasks or need help
• These messages appear automatically as new conversation turns (like user messages)
• If you're busy (mid-turn), messages are queued and delivered when your turn ends
• The UI shows a brief notification with the sender's name when messages are waiting

Messages will be delivered automatically.

When reporting on teammate messages, you do NOT need to quote the original message—it's already rendered to the user.

Teammate Idle State

Teammates go idle after every turn—this is completely normal and expected. A teammate going idle immediately after sending you a message does NOT mean they are done or unavailable. Idle simply means they are waiting for input.

• Idle teammates can receive messages. Sending a message to an idle teammate wakes them up and they will process it normally.
• Idle notifications are automatic. The system sends an idle notification whenever a teammate's turn ends. You do not need to react to idle notifications unless you want to assign new work or send a follow-up message.
• Do not treat idle as an error. A teammate sending a message and then going idle is the normal flow—they sent their message and are now waiting for a response.
• Peer DM visibility. When a teammate sends a DM to another teammate, a brief summary is included in their idle notification. This gives you visibility into peer collaboration without the full message content. You do not need to respond to these summaries — they are informational.

Discovering Team Members

Teammates can read the team config file to discover other team members:

• Team config location: ~/.claude/teams/{team-name}/config.json

The config file contains a members array with each teammate's:

• name: Human-readable name (always use this for messaging and task assignment)
• agentId: Unique identifier (for reference only - do not use for communication)
• agentType: Role/type of the agent

IMPORTANT: Always refer to teammates by their NAME (e.g., "team-lead", "researcher", "tester"). Names are used for:

• to when sending messages
• Identifying task owners

Example of reading team config:

Use the Read tool to read ~/.claude/teams/{team-name}/config.json

Task List Coordination

Teams share a task list that all teammates can access at ~/.claude/tasks/{team-name}/.

Teammates should:

1. Check TaskList periodically, especially after completing each task, to find available work or see newly unblocked tasks
2. Claim unassigned, unblocked tasks with TaskUpdate (set owner to your name). Prefer tasks in ID order (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
3. Create new tasks with TaskCreate when identifying additional work
4. Mark tasks as completed with TaskUpdate when done, then check TaskList for next work
5. Coordinate with other teammates by reading the task list status
6. If all available tasks are blocked, notify the team lead or help resolve blocking tasks

IMPORTANT notes for communication with your team:

• Do not use terminal tools to view your team's activity; always send a message to your teammates (and remember, refer to them by name).
• Your team cannot hear you if you do not use the SendMessage tool. Always send a message to your teammates if you are responding to them.
• Do NOT send structured JSON status messages like {"type":"idle",...} or {"type":"task_completed",...}. Just communicate in plain text when you need to message teammates.
• Use TaskUpdate to mark tasks completed.
• If you are an agent in the team, the system will automatically send idle notifications to the team lead when you stop.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "agent_type": {
      "description": "Type/role of the team lead (e.g., \"researcher\", \"test-runner\"). Used for team file and inter-agent coordination.",
      "type": "string"
    },
    "description": {
      "description": "Team description/purpose.",
      "type": "string"
    },
    "team_name": {
      "description": "Name for the new team to create.",
      "type": "string"
    }
  },
  "required": ["team_name"],
  "type": "object"
}

---

TeamDelete

Remove team and task directories when the swarm work is complete.

This operation:

• Removes the team directory (~/.claude/teams/{team-name}/)
• Removes the task directory (~/.claude/tasks/{team-name}/)
• Clears team context from the current session

IMPORTANT: TeamDelete will fail if the team still has active members. Gracefully terminate teammates first, then call TeamDelete after all teammates have shut down.

Use this when all teammates have finished their work and you want to clean up the team resources. The team name is automatically determined from the current session's team context.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

---

WebFetch

Fetches a URL, converts the page to markdown, and answers prompt against it using a small fast model.

• Fails on authenticated/private URLs — use an authenticated MCP tool or gh for those instead.
• HTTP is upgraded to HTTPS. Cross-host redirects are returned to you rather than followed; call again with the redirect URL.
• Responses are cached for 15 minutes per URL.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "prompt": {
      "description": "The prompt to run on the fetched content",
      "type": "string"
    },
    "url": {
      "description": "The URL to fetch content from",
      "format": "uri",
      "type": "string"
    }
  },
  "required": ["url", "prompt"],
  "type": "object"
}

---

WebSearch

Search the web. Returns result blocks with titles and URLs. US-only.

• The current month is May 2026 — use this when searching for recent information.
• allowed_domains / blocked_domains filter results.
• After answering from results, end with a "Sources:" list of the URLs you used as markdown links.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "allowed_domains": {
      "description": "Only include search results from these domains",
      "items": {"type": "string"},
      "type": "array"
    },
    "blocked_domains": {
      "description": "Never include search results from these domains",
      "items": {"type": "string"},
      "type": "array"
    },
    "query": {
      "description": "The search query to use",
      "minLength": 2,
      "type": "string"
    }
  },
  "required": ["query"],
  "type": "object"
}

---

mcp__claude-in-chrome__browser_batch

Execute a sequence of browser tool calls in ONE round trip. Each item is {name, input} where input is exactly what you'd pass to that tool standalone. Actions execute SEQUENTIALLY (not in parallel) and stop on the first error. Use this tool extensively to quickly execute work whenever you can predict two or more steps ahead — e.g. navigate, click a field, type, press Return, screenshot. Each tool's own permission check runs per item — if an action navigates to a domain without permission, the next item's check fails and the batch stops. Screenshots and other images are returned interleaved with outputs; coordinates you write in THIS batch refer to the screenshot taken BEFORE this call. browser_batch cannot be nested.

{
  "properties": {
    "actions": {
      "description": "List of tool calls to execute sequentially. Example: [{\"name\":\"computer\",\"input\":{\"action\":\"left_click\",\"coordinate\":[100,200],\"tabId\":123}},{\"name\":\"computer\",\"input\":{\"action\":\"type\",\"text\":\"hello\",\"tabId\":123}},{\"name\":\"navigate\",\"input\":{\"url\":\"https://example.com\",\"tabId\":123}}]",
      "items": {
        "properties": {
          "input": {
            "description": "That tool's input — same shape you'd pass when calling it directly.",
            "type": "object"
          },
          "name": {
            "description": "Tool name (e.g. computer, navigate, find, tabs_create_mcp). browser_batch cannot be nested.",
            "type": "string"
          }
        },
        "required": ["name", "input"],
        "type": "object"
      },
      "minItems": 1,
      "type": "array"
    }
  },
  "required": ["actions"],
  "type": "object"
}

---

mcp__claude-in-chrome__computer

Use a mouse and keyboard to interact with a web browser, and take screenshots. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

• Whenever you intend to click on an element like an icon, you should consult a screenshot to determine the coordinates of the element before moving the cursor.
• If you tried clicking on a program or link but it failed to load, even after waiting, try adjusting your click location so that the tip of the cursor visually falls on the element that you want to click.
• Make sure to click any buttons, links, icons, etc with the cursor tip in the center of the element. Don't click boxes on their edges unless asked.

{
  "properties": {
    "action": {
      "description": "The action to perform:\n* `left_click`: Click the left mouse button at the specified coordinates.\n* `right_click`: Click the right mouse button at the specified coordinates to open context menus.\n* `double_click`: Double-click the left mouse button at the specified coordinates.\n* `triple_click`: Triple-click the left mouse button at the specified coordinates.\n* `type`: Type a string of text.\n* `screenshot`: Take a screenshot of the screen.\n* `wait`: Wait for a specified number of seconds.\n* `scroll`: Scroll up, down, left, or right at the specified coordinates.\n* `key`: Press a specific keyboard key.\n* `left_click_drag`: Drag from start_coordinate to coordinate.\n* `zoom`: Take a screenshot of a specific region for closer inspection.\n* `scroll_to`: Scroll an element into view using its element reference ID from read_page or find tools.\n* `hover`: Move the mouse cursor to the specified coordinates or element without clicking. Useful for revealing tooltips, dropdown menus, or triggering hover states.",
      "enum": ["left_click", "right_click", "type", "screenshot", "wait", "scroll", "key", "left_click_drag", "double_click", "triple_click", "zoom", "scroll_to", "hover"],
      "type": "string"
    },
    "coordinate": {
      "description": "(x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates. Required for `left_click`, `right_click`, `double_click`, `triple_click`, and `scroll`. For `left_click_drag`, this is the end position.",
      "items": {"type": "number"},
      "maxItems": 2,
      "minItems": 2,
      "type": "array"
    },
    "duration": {
      "description": "The number of seconds to wait. Required for `wait`. Maximum 10 seconds.",
      "maximum": 10,
      "minimum": 0,
      "type": "number"
    },
    "modifiers": {
      "description": "Modifier keys for click actions. Supports: \"ctrl\", \"shift\", \"alt\", \"cmd\" (or \"meta\"), \"win\" (or \"windows\"). Can be combined with \"+\" (e.g., \"ctrl+shift\", \"cmd+alt\"). Optional.",
      "type": "string"
    },
    "ref": {
      "description": "Element reference ID from read_page or find tools (e.g., \"ref_1\", \"ref_2\"). Required for `scroll_to` action. Can be used as alternative to `coordinate` for click actions.",
      "type": "string"
    },
    "region": {
      "description": "(x0, y0, x1, y1): The rectangular region to capture for `zoom`. Coordinates define a rectangle from top-left (x0, y0) to bottom-right (x1, y1) in pixels from the viewport origin. Required for `zoom` action. Useful for inspecting small UI elements like icons, buttons, or text.",
      "items": {"type": "number"},
      "maxItems": 4,
      "minItems": 4,
      "type": "array"
    },
    "repeat": {
      "description": "Number of times to repeat the key sequence. Only applicable for `key` action. Must be a positive integer between 1 and 100. Default is 1. Useful for navigation tasks like pressing arrow keys multiple times.",
      "maximum": 100,
      "minimum": 1,
      "type": "number"
    },
    "save_to_disk": {
      "description": "For screenshot/zoom actions: save the image to disk so it can be attached to a message for the user. Returns the saved path in the tool result. Only set this when you intend to share the image — screenshots you're just looking at don't need saving.",
      "type": "boolean"
    },
    "scroll_amount": {
      "description": "The number of scroll wheel ticks. Optional for `scroll`, defaults to 3.",
      "maximum": 10,
      "minimum": 1,
      "type": "number"
    },
    "scroll_direction": {
      "description": "The direction to scroll. Required for `scroll`.",
      "enum": ["up", "down", "left", "right"],
      "type": "string"
    },
    "start_coordinate": {
      "description": "(x, y): The starting coordinates for `left_click_drag`.",
      "items": {"type": "number"},
      "maxItems": 2,
      "minItems": 2,
      "type": "array"
    },
    "tabId": {
      "description": "Tab ID to execute the action on. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "text": {
      "description": "The text to type (for `type` action) or the key(s) to press (for `key` action). For `key` action: Provide space-separated keys (e.g., \"Backspace Backspace Delete\"). Supports keyboard shortcuts using the platform's modifier key (use \"cmd\" on Mac, \"ctrl\" on Windows/Linux, e.g., \"cmd+a\" or \"ctrl+a\" for select all).",
      "type": "string"
    }
  },
  "required": ["action", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__file_upload

Upload one or multiple files from the local filesystem to a file input element on the page. Do not click on file upload buttons or file inputs — clicking opens a native file picker dialog that you cannot see or interact with. Instead, use read_page or find to locate the file input element, then use this tool with its ref to upload files directly. The paths must be absolute file paths on the local machine.

{
  "properties": {
    "paths": {
      "description": "The absolute paths to the files to upload. Can be a single file or multiple files.",
      "items": {"type": "string"},
      "type": "array"
    },
    "ref": {
      "description": "Element reference ID of the file input from read_page or find tools (e.g., \"ref_1\", \"ref_2\").",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID where the file input is located. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["paths", "ref", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__find

Find elements on the page using natural language. Can search for elements by their purpose (e.g., "search bar", "login button") or by text content (e.g., "organic mango product"). Returns up to 20 matching elements with references that can be used with other tools. If more than 20 matches exist, you'll be notified to use a more specific query. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "query": {
      "description": "Natural language description of what to find (e.g., \"search bar\", \"add to cart button\", \"product title containing organic\")",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to search in. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["query", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__form_input

Set values in form elements using element reference ID from the read_page tool. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "ref": {
      "description": "Element reference ID from the read_page tool (e.g., \"ref_1\", \"ref_2\")",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to set form value in. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "value": {
      "description": "The value to set. For checkboxes use boolean, for selects use option value or text, for other inputs use appropriate string/number",
      "type": ["string", "boolean", "number"]
    }
  },
  "required": ["ref", "value", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__get_page_text

Extract raw text content from the page, prioritizing article content. Ideal for reading articles, blog posts, or other text-heavy pages. Returns plain text without HTML formatting. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "tabId": {
      "description": "Tab ID to extract text from. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__gif_creator

Manage GIF recording and export for browser automation sessions. Control when to start/stop recording browser actions (clicks, scrolls, navigation), then export as an animated GIF with visual overlays (click indicators, action labels, progress bar, watermark). All operations are scoped to the tab's group. When starting recording, take a screenshot immediately after to capture the initial state as the first frame. When stopping recording, take a screenshot immediately before to capture the final state as the last frame. For export, either provide 'coordinate' to drag/drop upload to a page element, or set 'download: true' to download the GIF.

{
  "properties": {
    "action": {
      "description": "Action to perform: 'start_recording' (begin capturing), 'stop_recording' (stop capturing but keep frames), 'export' (generate and export GIF), 'clear' (discard frames)",
      "enum": ["start_recording", "stop_recording", "export", "clear"],
      "type": "string"
    },
    "download": {
      "description": "Always set this to true for the 'export' action only. This causes the gif to be downloaded in the browser.",
      "type": "boolean"
    },
    "filename": {
      "description": "Optional filename for exported GIF (default: 'recording-[timestamp].gif'). For 'export' action only.",
      "type": "string"
    },
    "options": {
      "description": "Optional GIF enhancement options for 'export' action. Properties: showClickIndicators (bool), showDragPaths (bool), showActionLabels (bool), showProgressBar (bool), showWatermark (bool), quality (number 1-30). All default to true except quality (default: 10).",
      "properties": {
        "quality": {
          "description": "GIF compression quality, 1-30 (lower = better quality, slower encoding). Default: 10",
          "type": "number"
        },
        "showActionLabels": {
          "description": "Show black labels describing actions (default: true)",
          "type": "boolean"
        },
        "showClickIndicators": {
          "description": "Show orange circles at click locations (default: true)",
          "type": "boolean"
        },
        "showDragPaths": {
          "description": "Show red arrows for drag actions (default: true)",
          "type": "boolean"
        },
        "showProgressBar": {
          "description": "Show orange progress bar at bottom (default: true)",
          "type": "boolean"
        },
        "showWatermark": {
          "description": "Show Claude logo watermark (default: true)",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "tabId": {
      "description": "Tab ID to identify which tab group this operation applies to",
      "type": "number"
    }
  },
  "required": ["action", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__javascript_tool

Execute JavaScript code in the context of the current page. The code runs in the page's context and can interact with the DOM, window object, and page variables. Returns the result of the last expression or any thrown errors. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "action": {
      "description": "Must be set to 'javascript_exec'",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to execute the code in. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "text": {
      "description": "The JavaScript code to execute. The code will be evaluated in the page context. The result of the last expression will be returned automatically. Do NOT use 'return' statements - just write the expression you want to evaluate (e.g., 'window.myData.value' not 'return window.myData.value'). You can access and modify the DOM, call page functions, and interact with page variables.",
      "type": "string"
    }
  },
  "required": ["action", "text", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__list_connected_browsers

List all Chrome browsers (extension instances) currently connected to this account. Returns each browser's deviceId, display name, OS platform, and whether it appears to be on this computer. Use this before select_browser to present choices to the user. Before any browser action, you MUST call the AskUserQuestion tool with a question listing EVERY connected browser as a separate option (use the display name as the label, and include the deviceId in parentheses), plus one final option labeled exactly: "Open a confirmation screen in every connected Chrome extension and let me select the right one there." Do not skip any connected browser and do not pick one yourself. If the user picks a specific browser, call select_browser with that browser's deviceId. If the user picks the final option, call switch_browser — this sends a confirmation prompt to every connected Chrome extension and waits for the user to click Connect in the one they want; it also lets them name that browser.

{
  "properties": {},
  "required": [],
  "type": "object"
}

---

mcp__claude-in-chrome__navigate

Navigate to a URL, or go forward/back in browser history. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "tabId": {
      "description": "Tab ID to navigate. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "url": {
      "description": "The URL to navigate to. Can be provided with or without protocol (defaults to https://). Use \"forward\" to go forward in history or \"back\" to go back in history.",
      "type": "string"
    }
  },
  "required": ["url", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__read_console_messages

Read browser console messages (console.log, console.error, console.warn, etc.) from a specific tab. Useful for debugging JavaScript errors, viewing application logs, or understanding what's happening in the browser console. Returns console messages from the current domain only. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs. IMPORTANT: Always provide a pattern to filter messages - without a pattern, you may get too many irrelevant messages.

{
  "properties": {
    "clear": {
      "description": "If true, clear the console messages after reading to avoid duplicates on subsequent calls. Default is false.",
      "type": "boolean"
    },
    "limit": {
      "description": "Maximum number of messages to return. Defaults to 100. Increase only if you need more results.",
      "type": "number"
    },
    "onlyErrors": {
      "description": "If true, only return error and exception messages. Default is false (return all message types).",
      "type": "boolean"
    },
    "pattern": {
      "description": "Regex pattern to filter console messages. Only messages matching this pattern will be returned (e.g., 'error|warning' to find errors and warnings, 'MyApp' to filter app-specific logs). You should always provide a pattern to avoid getting too many irrelevant messages.",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to read console messages from. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__read_network_requests

Read HTTP network requests (XHR, Fetch, documents, images, etc.) from a specific tab. Useful for debugging API calls, monitoring network activity, or understanding what requests a page is making. Returns all network requests made by the current page, including cross-origin requests. Requests are automatically cleared when the page navigates to a different domain. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "clear": {
      "description": "If true, clear the network requests after reading to avoid duplicates on subsequent calls. Default is false.",
      "type": "boolean"
    },
    "limit": {
      "description": "Maximum number of requests to return. Defaults to 100. Increase only if you need more results.",
      "type": "number"
    },
    "tabId": {
      "description": "Tab ID to read network requests from. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "urlPattern": {
      "description": "Optional URL pattern to filter requests. Only requests whose URL contains this string will be returned (e.g., '/api/' to filter API calls, 'example.com' to filter by domain).",
      "type": "string"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__read_page

Get an accessibility tree representation of elements on the page. By default returns all elements including non-visible ones. Output is limited to 50000 characters by default. If the output exceeds this limit, you will receive an error asking you to specify a smaller depth or focus on a specific element using ref_id. Optionally filter for only interactive elements. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "depth": {
      "description": "Maximum depth of the tree to traverse (default: 15). Use a smaller depth if output is too large.",
      "type": "number"
    },
    "filter": {
      "description": "Filter elements: \"interactive\" for buttons/links/inputs only, \"all\" for all elements including non-visible ones (default: all elements)",
      "enum": ["interactive", "all"],
      "type": "string"
    },
    "max_chars": {
      "description": "Maximum characters for output (default: 50000). Set to a higher value if your client can handle large outputs.",
      "type": "number"
    },
    "ref_id": {
      "description": "Reference ID of a parent element to read. Will return the specified element and all its children. Use this to focus on a specific part of the page when output is too large.",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to read from. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__resize_window

Resize the current browser window to specified dimensions. Useful for testing responsive designs or setting up specific screen sizes. If you don't have a valid tab ID, use tabs_context_mcp first to get available tabs.

{
  "properties": {
    "height": {
      "description": "Target window height in pixels",
      "type": "number"
    },
    "tabId": {
      "description": "Tab ID to get the window for. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    },
    "width": {
      "description": "Target window width in pixels",
      "type": "number"
    }
  },
  "required": ["width", "height", "tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__select_browser

Select a specific Chrome browser by deviceId for browser automation, without broadcasting a pairing request. Use this after list_connected_browsers when the user has chosen one from the list.

{
  "properties": {
    "deviceId": {
      "description": "The deviceId from list_connected_browsers.",
      "type": "string"
    }
  },
  "required": ["deviceId"],
  "type": "object"
}

---

mcp__claude-in-chrome__shortcuts_execute

Execute a shortcut or workflow by running it in a new sidepanel window using the current tab (shortcuts and workflows are interchangeable). Use shortcuts_list first to see available shortcuts. This starts the execution and returns immediately - it does not wait for completion.

{
  "properties": {
    "command": {
      "description": "The command name of the shortcut to execute (e.g., 'debug', 'summarize'). Do not include the leading slash.",
      "type": "string"
    },
    "shortcutId": {
      "description": "The ID of the shortcut to execute",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID to execute the shortcut on. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__shortcuts_list

List all available shortcuts and workflows (shortcuts and workflows are interchangeable). Returns shortcuts with their commands, descriptions, and whether they are workflows. Use shortcuts_execute to run a shortcut or workflow.

{
  "properties": {
    "tabId": {
      "description": "Tab ID to list shortcuts from. Must be a tab in the current group. Use tabs_context_mcp first if you don't have a valid tab ID.",
      "type": "number"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__switch_browser

Send a connection request to every Chrome browser with the extension installed and wait (up to 2 minutes) for the user to click 'Connect' in the one they want to use. The user can name the browser when they connect. Use this when the user wants to pick the browser themselves from inside Chrome rather than choosing from a list; otherwise prefer select_browser with a known deviceId.

{
  "properties": {},
  "required": [],
  "type": "object"
}

---

mcp__claude-in-chrome__tabs_close_mcp

Close a tab in the MCP tab group by its ID. Use to clean up tabs you're done with. Only tabs in this session's group are closable; call tabs_context_mcp first to get valid IDs. If you close the group's last tab, Chrome auto-removes the group — the next tabs_context_mcp with createIfEmpty starts fresh.

{
  "properties": {
    "tabId": {
      "description": "The ID of the tab to close. Must be in this session's tab group. Get valid IDs from tabs_context_mcp.",
      "type": "integer"
    }
  },
  "required": ["tabId"],
  "type": "object"
}

---

mcp__claude-in-chrome__tabs_context_mcp

Get context information about the current MCP tab group. Returns all tab IDs inside the group if it exists. CRITICAL: You must get the context at least once before using other browser automation tools so you know what tabs exist. Each new conversation should create its own new tab (using tabs_create_mcp) rather than reusing existing tabs, unless the user explicitly asks to use an existing tab.

{
  "properties": {
    "createIfEmpty": {
      "description": "Creates a new MCP tab group if none exists, creates a new Window with a new tab group containing an empty tab (which can be used for this conversation). If a MCP tab group already exists, this parameter has no effect.",
      "type": "boolean"
    }
  },
  "required": [],
  "type": "object"
}

---

mcp__claude-in-chrome__tabs_create_mcp

Creates a new empty tab in the MCP tab group. CRITICAL: You must get the context using tabs_context_mcp at least once before using other browser automation tools so you know what tabs exist.

{
  "properties": {},
  "required": [],
  "type": "object"
}

---

mcp__claude-in-chrome__upload_image

Upload a previously captured screenshot or user-uploaded image to a file input or drag & drop target. Supports two approaches: (1) ref - for targeting specific elements, especially hidden file inputs, (2) coordinate - for drag & drop to visible locations like Google Docs. Provide either ref or coordinate, not both.

{
  "properties": {
    "coordinate": {
      "description": "Viewport coordinates [x, y] for drag & drop to a visible location. Use this for drag & drop targets like Google Docs. Provide either ref or coordinate, not both.",
      "items": {"type": "number"},
      "type": "array"
    },
    "filename": {
      "description": "Optional filename for the uploaded file (default: \"image.png\")",
      "type": "string"
    },
    "imageId": {
      "description": "ID of a previously captured screenshot (from the computer tool's screenshot action) or a user-uploaded image",
      "type": "string"
    },
    "ref": {
      "description": "Element reference ID from read_page or find tools (e.g., \"ref_1\", \"ref_2\"). Use this for file inputs (especially hidden ones) or specific elements. Provide either ref or coordinate, not both.",
      "type": "string"
    },
    "tabId": {
      "description": "Tab ID where the target element is located. This is where the image will be uploaded to.",
      "type": "number"
    }
  },
  "required": ["imageId", "tabId"],
  "type": "object"
}