_claude

#compdef claude

# Zsh completion script for Claude Code CLI
# https://github.com/anthropics/claude-code
# Auto-generated for Claude v2.1.296

_claude_session_ids() {
  # Claude stores each project under ~/.claude/projects/ with a mangled
  # folder name, Claude Code's `path.replace(/[^a-zA-Z0-9]/g, "-")`. That
  # regex runs per UTF-16 code unit, so a character beyond U+FFFF such as
  # `💩` becomes `--` while `ü`, ` `, `_`, `/` and `.` each become `-`. Zsh
  # substitutes per character, hence the separate first pass for the astral
  # range. Under a non-UTF-8 locale both passes yield extra hyphens, no
  # folder matches, and the originalPath fallback below applies.
  local mangled="${PWD//[$'\U00010000'-$'\U0010FFFF']/--}"
  mangled="${mangled//[^a-zA-Z0-9]/-}"
  local project_dir="$HOME/.claude/projects/$mangled"

  # Fallback: if the mangled folder isn't found (e.g. unknown future naming
  # scheme, or the session was created from a different canonical path such
  # as a resolved symlink), locate the project by matching the authoritative
  # `originalPath` recorded in each sessions-index.json.
  if [[ ! -d "$project_dir" ]]; then
    project_dir=""
    local f
    for f in "$HOME/.claude/projects"/*/sessions-index.json(N); do
      if [[ "$(jq -r '.originalPath // ""' "$f" 2>/dev/null)" == "$PWD" ]]; then
        project_dir="${f:h}"
        break
      fi
    done
    [[ -z "$project_dir" ]] && return 1
  fi

  local index_file="$project_dir/sessions-index.json"
  local -a ids labels

  # Cap the number of sessions offered by completion. Projects with a long
  # history can accumulate hundreds of session files — enumerating them all
  # triggers zsh's "show all N possibilities?" pager prompt and (worse)
  # forces the expensive JSONL parse below to run once per file on every
  # TAB press. Default to the 20 most recent; override via
  # CLAUDE_COMPLETION_SESSION_LIMIT, where 0 (or any non-positive int)
  # disables the cap for users who want the old behavior.
  local max_sessions=${CLAUDE_COMPLETION_SESSION_LIMIT:-20}

  # Pull branch + summary from sessions-index.json, keyed by sessionId.
  # `.summary` here is the same human-readable title `/resume` displays
  # (e.g. "refactor-auth-flow"); we prefer it over the first
  # user prompt for indexed sessions, falling back to the JSONL when the
  # session isn't indexed yet.
  local -A index_summary index_branch
  if [[ -f "$index_file" ]]; then
    local _iid _ibranch _isummary
    while IFS=$'\t' read -r _iid _ibranch _isummary; do
      [[ -z "$_iid" ]] && continue
      index_summary[$_iid]="$_isummary"
      index_branch[$_iid]="$_ibranch"
    done < <(jq -rs '[.[].entries[]] | .[] | [.sessionId, (.gitBranch // "?"), (.summary // "")] | @tsv' "$index_file" 2>/dev/null)
  fi

  # Single batched `zstat` for both mtime (epoch seconds) and size (bytes)
  # on every jsonl file. Using one stat source for all sessions keeps the
  # sort key uniform and gives us the size that `/resume` shows alongside
  # the relative-time label. `zstat` is preferred over external `stat`
  # because GNU/BSD `stat` flags disagree (GNU `stat -f` means
  # filesystem-status, not "format"), so the BSD invocation produced
  # garbage paths on Linux.
  #
  # Note: all locals used below are declared once here, up-front. zsh
  # prints the current value of a variable when `local`/`typeset` is
  # applied to it a second time in the same scope (treats it like
  # `typeset -p`), so the second pass must *not* redeclare these.
  local -a jsonl_files mtimes sizes candidates top
  local line filepath uuid mtime size title branch info reltime sizestr
  local _jb _jcustom _jai _jsum _jprompt _jcmd
  local count=0 headroom idx d h m days weeks months years kb mb gb now

  jsonl_files=( "$project_dir"/*.jsonl(N) )
  (( ${#jsonl_files} == 0 )) && return 1

  zmodload -F zsh/stat b:zstat 2>/dev/null
  zstat -A mtimes +mtime "${jsonl_files[@]}" 2>/dev/null
  zstat -A sizes  +size  "${jsonl_files[@]}" 2>/dev/null

  idx=1
  for filepath in "${jsonl_files[@]}"; do
    mtime="${mtimes[$idx]}"
    size="${sizes[$idx]:-0}"
    (( idx++ ))
    uuid="${filepath:t:r}"
    [[ -z "$mtime" ]] && continue
    candidates+=("${mtime}"$'\t'"${uuid}"$'\t'"${size}"$'\t'"${filepath}")
  done

  # Sort newest first (numeric epoch), then cap. Headroom covers JSONL
  # files filtered out in pass 2 (only meta / <command-*> entries) so the
  # list doesn't come up short.
  if (( ${#candidates} > 0 )); then
    if (( max_sessions > 0 )); then
      headroom=$(( max_sessions * 2 + 5 ))
      while IFS= read -r line; do top+=("$line"); done \
        < <(printf '%s\n' "${candidates[@]}" | sort -nr | head -n $headroom)
    else
      while IFS= read -r line; do top+=("$line"); done \
        < <(printf '%s\n' "${candidates[@]}" | sort -nr)
    fi
  fi

  zmodload -F zsh/datetime p:EPOCHSECONDS 2>/dev/null
  now=${EPOCHSECONDS:-$(date +%s)}

  # Pass 2: resolve title/branch (from index when possible, else parse the
  # JSONL), compute the same "1 day ago · main · 2.5MB" trio `/resume`
  # displays, and build the label. Newest-first order is preserved by
  # `sort -nr` above and by `-o nosort` on the compadd call below.
  for line in "${top[@]}"; do
    (( max_sessions > 0 && count >= max_sessions )) && break
    IFS=$'\t' read -r mtime uuid size filepath <<< "$line"

    branch="${index_branch[$uuid]:-?}"
    # Parse the JSONL for live title signals — `/rename`-set custom titles
    # (type: custom-title) and auto-generated `ai-title` records both live
    # there and outrank any frozen `summary` recorded in sessions-index.json.
    # We always check, so renaming a session immediately reflects in the
    # completer. Both record types get appended throughout the session, so
    # reading `head -100; tail -50` catches them without parsing multi-MB
    # files. Fields are emitted one per line (with newlines stripped) so
    # zsh's `read` doesn't collide with tab-collapsing IFS rules when
    # intermediate values are empty.
    _jb=""; _jcustom=""; _jai=""; _jsum=""; _jprompt=""; _jcmd=""
    {
      IFS= read -r _jb
      IFS= read -r _jcustom
      IFS= read -r _jai
      IFS= read -r _jsum
      IFS= read -r _jprompt
      IFS= read -r _jcmd
    } < <( { head -100 "$filepath"; tail -50 "$filepath"; } 2>/dev/null | jq -rs '
      [.[] | select(.type=="user")] as $users |
      ([.[] | select(.type=="custom-title") | .customTitle] | last // "") as $custom |
      ([.[] | select(.type=="ai-title")     | .aiTitle]     | last // "") as $ai     |
      ([.[] | select(.type=="summary")      | .summary]     | first // "") as $sum  |
      ([
        $users[]
        | select((.isMeta // false) != true and .message.content != null)
        | .message.content
        | if type=="array" then .[0].text else . end
        | select(. != null)
        | select(test("^\\s*<(command|local-command)") | not)
      ] | first // "") as $prompt |
      # Command-only sessions (e.g. a quick `/exit`) still show in `/resume`
      # labelled by the slash command itself; extract that from the
      # <command-name>...</command-name> tag so they surface here too.
      ([
        $users[]
        | (.message.content | if type=="array" then .[0].text else . end)
        | select(. != null and test("<command-name>"))
        | capture("<command-name>(?<c>[^<]+)</command-name>") | .c
      ] | first // "") as $cmd |
      ($users[0].gitBranch // "") as $br |
      [$br, $custom, $ai, $sum, $prompt, $cmd][]
      | gsub("\n"; " ")
    ' 2>/dev/null )
    [[ -n "$_jb" ]] && branch="$_jb"
    # Priority: /rename customTitle → aiTitle → index summary →
    # inline summary record → first user prompt → first slash command.
    if   [[ -n "$_jcustom" ]]; then title="$_jcustom"
    elif [[ -n "$_jai"     ]]; then title="$_jai"
    elif [[ -n "${index_summary[$uuid]}" ]]; then title="${index_summary[$uuid]}"
    elif [[ -n "$_jsum"    ]]; then title="$_jsum"
    elif [[ -n "$_jprompt" ]]; then title="$_jprompt"
    elif [[ -n "$_jcmd"    ]]; then title="$_jcmd"
    else title=""
    fi
    [[ -z "$title" ]] && continue
    # Trim/normalize for one-line display.
    title="${title//$'\n'/ }"
    (( ${#title} > 80 )) && title="${title:0:80}"

    # Relative time — same buckets `/resume` uses.
    d=$(( now - mtime ))
    (( d < 0 )) && d=0
    if (( d < 60 )); then
      (( d == 1 )) && reltime="1 second ago" || reltime="${d} seconds ago"
    elif (( d < 3600 )); then
      m=$(( d / 60 ))
      (( m == 1 )) && reltime="1 minute ago" || reltime="${m} minutes ago"
    elif (( d < 86400 )); then
      h=$(( d / 3600 ))
      (( h == 1 )) && reltime="1 hour ago" || reltime="${h} hours ago"
    elif (( d < 604800 )); then
      days=$(( d / 86400 ))
      (( days == 1 )) && reltime="1 day ago" || reltime="${days} days ago"
    elif (( d < 2592000 )); then
      weeks=$(( d / 604800 ))
      (( weeks == 1 )) && reltime="1 week ago" || reltime="${weeks} weeks ago"
    elif (( d < 31536000 )); then
      months=$(( d / 2592000 ))
      (( months == 1 )) && reltime="1 month ago" || reltime="${months} months ago"
    else
      years=$(( d / 31536000 ))
      (( years == 1 )) && reltime="1 year ago" || reltime="${years} years ago"
    fi

    # Human-readable size, one decimal place. Avoids forking awk/bc; zsh
    # integer arithmetic keeps the pass-2 loop hot for projects with
    # hundreds of sessions.
    if (( size < 1024 )); then
      sizestr="${size}B"
    elif (( size < 1048576 )); then
      kb=$(( size * 10 / 1024 ))
      (( kb % 10 == 0 )) && sizestr="$((kb/10))KB" || sizestr="$((kb/10)).$((kb%10))KB"
    elif (( size < 1073741824 )); then
      mb=$(( size * 10 / 1048576 ))
      (( mb % 10 == 0 )) && sizestr="$((mb/10))MB" || sizestr="$((mb/10)).$((mb%10))MB"
    else
      gb=$(( size * 10 / 1073741824 ))
      (( gb % 10 == 0 )) && sizestr="$((gb/10))GB" || sizestr="$((gb/10)).$((gb%10))GB"
    fi

    ids+=("$uuid")
    labels+=("${reltime} · ${branch} · ${sizestr} - ${uuid:0:8}: ${title}")
    (( count++ ))
  done

  [[ ${#ids} -eq 0 ]] && return 1
  local expl
  # `-V sessions` names the group (for zstyle targeting). `-o nosort` is
  # what actually disables alphabetical re-sorting — `-V` alone is
  # sometimes overridden by the display layer. `-o nosort` is the canonical
  # zsh API (used throughout core completion functions) and is stable in
  # zsh 5.0.1+, so this is safe for any modern zsh.
  _wanted session-ids expl 'session' compadd -V sessions -o nosort -d labels -a ids
}

# Background-session ID completer for `claude attach|logs|stop|kill|respawn|rm`.
# Mirrors how the `claude agents` view itself enumerates sessions: walk
# ~/.claude/jobs/<id>/state.json. A state.json file is the only authoritative
# marker — entries that appear only in daemon/roster.json without a state.json
# are pre-spawn placeholders (no real session) and sessions imported via /bg
# from an interactive terminal land in jobs/ without ever touching roster.json,
# so the roster is neither necessary nor sufficient. Honors CLAUDE_CONFIG_DIR
# per the docs (background sessions are stored there instead of ~/.claude when
# set).
_claude_background_session_ids() {
  local config_dir="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
  local jobs_dir="$config_dir/jobs"

  [[ -d "$jobs_dir" ]] || return 1

  # Gather every job dir that has a state.json. The state.json mtime is the
  # session's last-activity timestamp (the supervisor rewrites it on every
  # turn), so it's the right key for matching `claude agents`'s newest-first
  # ordering. zstat (zsh/stat module) gets all mtimes in a single syscall —
  # avoids forking `stat` per file when the user has many sessions.
  local -a job_dirs state_files mtimes
  local d
  for d in "$jobs_dir"/*(N/); do
    [[ -r "$d/state.json" ]] || continue
    job_dirs+=("$d")
    state_files+=("$d/state.json")
  done
  (( ${#job_dirs} == 0 )) && return 1

  zmodload -F zsh/stat b:zstat 2>/dev/null
  zstat -A mtimes +mtime "${state_files[@]}" 2>/dev/null

  # Build "<mtime>\t<id>\t<label>" rows so a single `sort -nr` orders the
  # whole list newest-first regardless of how many sessions there are.
  local -a rows
  local idx=1 id state_file info name state label mtime
  for d in "${job_dirs[@]}"; do
    state_file="${state_files[$idx]}"
    mtime="${mtimes[$idx]:-0}"
    (( idx++ ))
    id="${d:t}"
    # Observed state.json fields (Claude v2.1.139): `name` (auto-generated or
    # user-set), `intent` (the original prompt seed), `state` ("done", "idle",
    # etc.). Fall back through other plausible names so a future rename
    # doesn't blank the menu entirely.
    info=$(jq -r '
      [
        (.name // .displayName // .title // .sessionName // .intent // .summary // .prompt // ""),
        (.state // .status // .lifecycle // "")
      ] | @tsv
    ' "$state_file" 2>/dev/null)
    name="${info%%$'\t'*}"
    state="${info#*$'\t'}"
    if [[ -n "$name" && -n "$state" ]]; then
      label="${id} [${state}] ${name}"
    elif [[ -n "$name" ]]; then
      label="${id} ${name}"
    elif [[ -n "$state" ]]; then
      label="${id} [${state}]"
    else
      label="${id}"
    fi
    rows+=("${mtime}"$'\t'"${id}"$'\t'"${label}")
  done

  local -a ids labels
  local line
  while IFS=$'\t' read -r mtime id label; do
    ids+=("$id")
    labels+=("$label")
  done < <(printf '%s\n' "${rows[@]}" | sort -nr)

  local expl
  _wanted bg-session-ids expl 'background session' compadd -o nosort -d labels -a ids
}

# Offer the model aliases Claude accepts in place of a full model name.
# The list mirrors the alias table at
# https://code.claude.com/docs/en/model-config#model-aliases. Full model
# ids are left out on purpose: they change with every model release.
#
# "$@" carries the options the caller adds (`_arguments`' description
# options, or `_sequence`'s separator and already-chosen values for the
# comma-separated --fallback-model), so it has to reach `_describe`.
_claude_models() {
  local -a models
  models=(
    'default:Clear any model override and use the default for your account'
    'best:Fable where it is available to you, otherwise the same model as opus'
    'fable:Fable, for your hardest and longest-running tasks'
    'sonnet:Latest Sonnet, for daily coding tasks'
    'opus:Latest Opus, for complex reasoning tasks'
    'haiku:Fast and efficient Haiku, for simple tasks'
    'sonnet[1m]:Sonnet with a 1 million token context window'
    'opus[1m]:Opus with a 1 million token context window'
    'opusplan:opus during plan mode, then sonnet for execution'
  )
  _describe -t models 'model' models "$@"
}

# Set $reply to the directories Claude treats as the current project: the
# working directory and each parent up to the repository root, closest
# first. Outside a repository that is the working directory alone. Symlinks
# are resolved, because Claude keys project state by the resolved path.
_claude_project_dirs() {
  local d=${PWD:A} root=""
  reply=($d)
  while true; do
    if [[ -e $d/.git ]]; then root=$d; break; fi
    [[ $d == / ]] && break
    d=${d:h}
  done
  d=$reply[1]
  while [[ -n $root && $d != "$root" ]]; do
    d=${d:h}
    reply+=($d)
  done
}

# Set $reply to the `name` and the `description` in the frontmatter of the
# agent file $1, each empty when it is missing. Only the frontmatter is
# read, in zsh itself, so no process is started per file.
_claude_agent_frontmatter() {
  setopt localoptions extendedglob
  local line key val name="" desc=""
  local -i n=0 block=0

  while IFS= read -r line || [[ -n $line ]]; do
    (( n++ ))
    line=${line%$'\r'}
    if (( n == 1 )); then
      # A byte-order mark may precede the opening `---`.
      line=${line#$'\xef\xbb\xbf'}
      [[ ${line%%[[:space:]]#} == '---' ]] || break
      continue
    fi
    [[ ${line%%[[:space:]]#} == '---' ]] && break
    (( n > 200 )) && break
    if (( block )); then
      # First line of a `description: |` or `>` block.
      block=0
      if [[ $line == [[:space:]]##[^[:space:]]* ]]; then
        desc=${${line##[[:space:]]#}%%[[:space:]]#}
        continue
      fi
    fi
    [[ $line == (name|description):* ]] || continue
    key=${line%%:*}
    val=${${line#*:}##[[:space:]]#}
    if [[ $val == \"* ]]; then
      val=${${val#\"}%%\"*}
    elif [[ $val == \'* ]]; then
      val=${${val#\'}%%\'*}
    else
      # Unquoted: drop a trailing ` # comment`, then trailing blanks.
      [[ $val == \#* ]] && val=""
      val=${${val%%[[:space:]]##\#*}%%[[:space:]]#}
    fi
    if [[ $key == name ]]; then
      name=$val
    elif [[ $val == [\|\>]([+-]|)([0-9]|) ]]; then
      block=1
    else
      desc=$val
    fi
  done < $1 2>/dev/null

  # Descriptions often carry escaped examples; keep the first line short.
  desc=${desc%%\\n*}
  (( ${#desc} > 80 )) && desc="${desc[1,77]}..."
  reply=("$name" "$desc")
}

# Set $reply to the agents of the installed plugins, as `_describe` items.
# The arguments are the project directories (`_claude_project_dirs`).
#   - installed_plugins.json names each plugin's `installPath`. The cache
#     directory also keeps older versions, so it is not searched. An
#     install with project or local scope counts only inside its project.
#   - a plugin is skipped when `enabledPlugins` turns it off, or when
#     nothing sets it and its manifest says `defaultEnabled: false`. The
#     files are the ones Claude reads (checked with `claude plugin list`
#     in 2.1.296), the later one winning: the user's settings.json, the
#     working directory's .claude/settings.json and settings.local.json,
#     and the main repository's .claude/settings.local.json. No other
#     parent directory counts, and neither does the repository's
#     settings.json below its root.
#   - the agent is `<plugin>:<subfolders of agents/>:<name>`, the name
#     being the frontmatter `name`, or the file name without it. `<plugin>`
#     is the manifest's `name`, the part before `@` without a manifest.
#   - `agents` in the manifest replaces the `agents/` scan with the listed
#     `.md` files, which get no subfolder in their name.
# See https://code.claude.com/docs/en/plugins/components#agents. Two jq
# processes read every JSON file: one for installed_plugins.json and the
# settings, one for the manifests. Each file is handed over as text and
# parsed inside jq, so a broken one is skipped instead of ending the run.
_claude_plugin_agents() {
  setopt localoptions extendedglob
  local config=${CLAUDE_CONFIG_DIR:-$HOME/.claude}
  local installed=${CLAUDE_CODE_PLUGIN_CACHE_DIR:-$config/plugins}/installed_plugins.json
  local -a jqargs rows fields ids roots preset manifests files out
  local -A seen
  local f row root plugin name desc text main="" gitdir common
  local -i i=0 listed

  reply=()
  [[ -f $installed && -r $installed ]] || return 1

  # The main repository is the last project directory when that is a
  # checkout. A linked worktree names its git directory in a `.git` file,
  # and `commondir` there leads to the repository it belongs to.
  (( $# )) && main=${@[-1]}
  if [[ -n $main && -f $main/.git ]]; then
    gitdir=$(<$main/.git) 2>/dev/null
    gitdir=${${gitdir%%$'\n'*}#gitdir: }
    [[ $gitdir == /* ]] || gitdir=$main/$gitdir
    common=""
    [[ -f $gitdir/commondir && -r $gitdir/commondir ]] && common=$(<$gitdir/commondir) 2>/dev/null
    common=${common%%$'\n'*}
    if [[ -n $common ]]; then
      [[ $common == /* ]] || common=$gitdir/$common
      main=${common:A:h}
    fi
  elif [[ ! -d $main/.git ]]; then
    main=""
  fi

  jqargs=(--rawfile installed $installed)
  for f in $config/settings.json $1/.claude/settings.json $1/.claude/settings.local.json \
      ${main:+$main/.claude/settings.local.json}; do
    (( i++ ))
    if [[ -f $f && -r $f ]]; then
      jqargs+=(--rawfile settings$i $f)
    else
      jqargs+=(--arg settings$i '')
    fi
  done
  (( i < 4 )) && jqargs+=(--arg settings4 '')

  # One row per usable plugin: id, install path, and whether a settings
  # file sets `enabledPlugins` for it.
  rows=("${(@f)$(command jq -n -r "${jqargs[@]}" '
    def parse: first((try fromjson catch null), null);
    (reduce ($settings1, $settings2, $settings3, $settings4 | parse | objects | .enabledPlugins | objects) as $e
      ({}; . + $e)) as $enabled
    | $installed | parse | objects | .plugins | objects | to_entries[]
    | .key as $id
    | select($enabled[$id] != false)
    | [.value | if type == "array" then .[] else . end | objects
       | select(.installPath | type == "string")] as $installs
    | ([$installs[] | select(.projectPath as $p | $p != null and any($ARGS.positional[]; . == $p))][0]
       // [$installs[] | select(.scope != "project" and .scope != "local")][0])
    | objects
    | select($id + .installPath | test("[[:cntrl:]]") | not)
    | [$id, .installPath, ($enabled | has($id) | tostring)] | join("\u001f")
  ' --args "$@" 2>/dev/null)}")

  for row in $rows; do
    fields=("${(@ps:\x1f:)row}")
    root=${fields[2]%/}
    (( $#fields == 3 )) && [[ -d $root ]] || continue
    text=""
    f=$root/.claude-plugin/plugin.json
    [[ -f $f && -r $f ]] && text=$(<$f) 2>/dev/null
    ids+=("$fields[1]") roots+=("$root") preset+=("$fields[3]") manifests+=("$text")
  done
  (( $#ids )) || return 1

  # One row per manifest, in order: name, defaultEnabled, whether it has
  # an `agents` key, and the paths under that key.
  rows=()
  if [[ -n ${(j::)manifests} ]]; then
    rows=("${(@f)$(command jq -n -r '
      $ARGS.positional[] | first((try fromjson catch null), null) as $m
      | if ($m | type) == "object" then
          [ ($m.name | if type == "string" then . else "" end),
            ($m.defaultEnabled != false | tostring),
            ($m | has("agents") | tostring),
            ($m.agents | if type == "string" then [.] elif type == "array" then map(strings) else [] end
             | join("\u001e")) ]
        else ["", "true", "false", ""] end
      | join("\u001f") | gsub("[\\n\\r]"; "")
    ' --args "${manifests[@]}" 2>/dev/null)}")
  fi

  for (( i = 1; i <= $#ids; i++ )); do
    root=$roots[i] plugin=${ids[i]%%@*} listed=0
    files=($root/agents/**/*.md(N-.))
    if (( $#rows == $#ids )); then
      fields=("${(@ps:\x1f:)rows[i]}")
      [[ -n $fields[1] ]] && plugin=$fields[1]
      [[ $preset[i] == false && $fields[2] == false ]] && continue
      if [[ $fields[3] == true ]]; then
        listed=1 files=()
        for f in "${(@ps:\x1e:)fields[4]}"; do
          # Paths start with `./` and stay inside the plugin.
          [[ $f == ./*.md && $f != *..* && -f $root/$f ]] && files+=($root/$f)
        done
      fi
    fi
    for f in $files; do
      _claude_agent_frontmatter $f
      # Claude's own fallbacks for a file without usable frontmatter.
      name=${reply[1]:-${f:t:r}} desc=${reply[2]:-Agent from $plugin plugin}
      if (( listed )); then
        name=$plugin:$name
      else
        name=$plugin${${${f:h}#$root/agents}//\//:}:$name
      fi
      (( ${+seen[$name]} )) && continue
      seen[$name]=1
      out+=("${name//:/\\:}:$desc")
    done
  done
  reply=("${out[@]}")
}

# Offer the agents `--agent` accepts, the way Claude finds them
# (https://code.claude.com/docs/en/sub-agents):
#   - project: every `.claude/agents/` from the working directory up to the
#     repository root, closest first, so `claude --agent` works from a
#     subdirectory. Outside a repository only the working directory counts.
#   - user: `$CLAUDE_CONFIG_DIR/agents`, `~/.claude/agents` by default.
#   - both are searched recursively, and the agent is identified by the
#     `name` in its frontmatter, never by its path or file name. A file
#     without usable frontmatter is skipped.
#   - plugin: see `_claude_plugin_agents`. Only the scoped name is offered.
#     Claude also takes the last part alone, but then a user or project
#     agent of that name wins, and so does the first of two plugins.
#   - built-in: the agents Claude registers itself. A user or project
#     agent of the same name replaces one, so it is listed once.
_claude_agents() {
  local -a reply dirs agents
  local -A seen
  local d f name desc

  _claude_project_dirs
  dirs=("${reply[@]}")

  for d in ${^dirs}/.claude/agents "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/agents"; do
    for f in $d/**/*.md(N-.); do
      _claude_agent_frontmatter $f
      name=$reply[1] desc=$reply[2]
      # `:` is reserved for plugin-scoped agents; Claude skips such a file.
      [[ -n $name && $name != *:* ]] || continue
      (( ${+seen[$name]} )) && continue
      seen[$name]=1
      agents+=("${name}${desc:+:$desc}")
    done
  done

  _claude_plugin_agents "${dirs[@]}"
  agents+=("${reply[@]}")

  # The descriptions are from the sub-agents page.
  for name desc in \
    general-purpose 'Complex, multi-step tasks that need both exploration and action' \
    statusline-setup 'Configures your status line' \
    claude 'Catch-all with every tool available to subagents' \
    Explore 'Fast, read-only agent for searching and analyzing codebases' \
    Plan 'Research agent that gathers context before presenting a plan' \
    claude-code-guide 'Answers questions about Claude Code features'; do
    (( ${+seen[$name]} )) || agents+=("$name:$desc")
  done

  _describe -t agents 'agent' agents "$@"
}

# Offer the MCP servers configured for the current directory, read from
# Claude's own files (https://code.claude.com/docs/en/mcp):
#   - user scope:    `mcpServers` in ~/.claude.json
#   - local scope:   `projects.<project path>.mcpServers` in ~/.claude.json
#   - project scope: `mcpServers` in the project's `.mcp.json`
# With CLAUDE_CONFIG_DIR set, .claude.json is read from that directory.
# The project is looked up from the working directory up to the repository
# root (see _claude_project_dirs), so servers are also found from a
# subdirectory or through a symlinked path. Needs `jq` 1.6 or newer (for
# `$ARGS`); without it, or with a missing or malformed file, nothing is
# offered.
_claude_mcp_servers() {
  local -a reply servers
  local d cfg="${CLAUDE_CONFIG_DIR:-$HOME}/.claude.json"
  # One `name:scope - type target` row per server. A `:` in the name is
  # escaped for _describe. The query string of a URL is dropped, since it
  # can hold a token. Control characters are taken out of the description:
  # `.mcp.json` comes with the repository, and a newline in it would
  # otherwise turn into an extra row.
  local rows='def rows($scope):
    objects | to_entries[]
    | select((.value | type) == "object")
    | select(.key | test("[[:cntrl:]]") | not)
    | (.value.url // .value.command // "" | tostring | split("?")[0] // "") as $target
    | (.value.type // (if .value.url then "http" else "stdio" end) | tostring) as $type
    | "\(.key | gsub(":"; "\\:")):\("\($scope) - \($type) \($target)" | gsub("[[:cntrl:]]"; " ") | .[0:100])";'

  _claude_project_dirs
  if [[ -r $cfg ]]; then
    servers+=("${(@f)$(command jq -r "$rows"'
      (.mcpServers | rows("user")),
      (.projects as $p | $ARGS.positional[] | $p[.]?.mcpServers? | rows("local"))
    ' "$cfg" --args $reply 2>/dev/null)}")
  fi
  for d in $reply; do
    [[ -r $d/.mcp.json ]] || continue
    servers+=("${(@f)$(command jq -r "$rows"' .mcpServers | rows("project")' \
      "$d/.mcp.json" 2>/dev/null)}")
  done
  servers=(${servers:#})

  _describe -t mcp-servers 'MCP server' servers "$@"
}

# The three helpers below complete plugin and marketplace values from the
# files Claude keeps under `$CLAUDE_CONFIG_DIR/plugins` (`~/.claude/plugins`
# by default), or under `$CLAUDE_CODE_PLUGIN_CACHE_DIR` when that is set,
# as Claude does. They need `jq` 1.6 or newer, never run `claude` and never use the
# network. A missing or malformed file, or a malformed entry in one,
# leaves the remaining values in place.

# Installed plugins, as `name@marketplace`, from installed_plugins.json.
# The value of an entry is a list of installs, or a single install in the
# older format. An install made for one project (project or local scope,
# with a `projectPath`) only counts inside that project, as found by
# _claude_project_dirs; the first install that counts supplies the
# description.
_claude_installed_plugins() {
  local -a reply plugins
  local file="${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/installed_plugins.json"
  [[ -r $file ]] || return 1
  _claude_project_dirs
  plugins=("${(@f)$(command jq -r '
    $ARGS.positional as $dirs
    | .plugins | objects | to_entries[]
    | select(.key | test("[[:cntrl:]]") | not)
    | ([.value | if type == "array" then .[] else . end | objects
        | select((.projectPath | type) != "string" or (.projectPath as $p | $dirs | index($p) != null))
       ] | first) as $install
    | select($install != null)
    | "\(.key | gsub(":"; "\\:")):\("\($install.version // "unknown" | tostring) (\($install.scope // "user" | tostring) scope)" | gsub("[[:cntrl:]]"; " ") | .[0:80])"
  ' "$file" --args $reply 2>/dev/null)}")
  plugins=(${plugins:#})

  _describe -t plugins 'installed plugin' plugins "$@"
}

# Marketplace names, from known_marketplaces.json.
_claude_marketplaces() {
  local -a marketplaces
  local file="${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/known_marketplaces.json"
  [[ -r $file ]] || return 1
  marketplaces=("${(@f)$(command jq -r '
    objects | to_entries[]
    | select((.value | type) == "object")
    | select(.key | test("[[:cntrl:]]") | not)
    | ((.value.source | objects | (.repo // .url // .path // .source) | strings | split("?")[0]) // "") as $source
    | "\(.key | gsub(":"; "\\:")):\($source)"
  ' "$file" 2>/dev/null)}")
  marketplaces=(${marketplaces:#})

  _describe -t marketplaces 'marketplace' marketplaces "$@"
}

# Plugins that can be installed, as `name@marketplace`, from the manifest
# each known marketplace caches under marketplaces/<name>/.
# All manifests go through one jq process. Each is handed over as text
# (`--rawfile <marketplace> <file>`) and parsed inside jq, so a manifest
# that is not valid JSON is skipped. Passed as input files instead, jq
# would give up at the first broken one.
_claude_marketplace_plugins() {
  local -a manifests rawfiles plugins
  local manifest
  manifests=("${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}"/marketplaces/*/.claude-plugin/marketplace.json(N-.))
  (( $#manifests )) || return 1
  for manifest in $manifests; do
    rawfiles+=(--rawfile ${manifest:h:h:t} $manifest)
  done
  plugins=("${(@f)$(command jq -n -r $rawfiles '
    $ARGS.named | to_entries[]
    | .key as $marketplace
    | .value | fromjson? | objects | .plugins | arrays | .[] | objects
    | select((.name | type) == "string")
    | select(.name | test("[[:cntrl:]]") | not)
    | ((.description | strings | gsub("[[:cntrl:]]"; " ") | .[0:80]) // "") as $description
    | "\("\(.name)@\($marketplace)" | gsub(":"; "\\:")):\($description)"
  ' 2>/dev/null)}")
  plugins=(${plugins:#})

  _describe -t plugins 'plugin' plugins "$@"
}

# Offer a freshly-generated UUID for --session-id, which expects a NEW,
# user-assigned session identifier (not an existing session to resume).
local curcontext="$curcontext" state line
typeset -A opt_args

# Top-level commands. This is the one list to maintain: known_commands and the
# '1:command:(...)' spec below are derived from it. It must not be named
# `commands`: that is zsh's special hash of executables, and a local of that
# name hides it from every completer called from here.
local -a claude_commands
claude_commands=(
  'agents:Open agent view (manage background sessions)'
  'attach:Open a background session in this terminal'
  'auth:Manage authentication'
  'auto-mode:Inspect auto mode classifier configuration'
  'daemon:Manage the background session supervisor'
  'doctor:Check the health of your Claude Code installation'
  'gateway:Run the enterprise auth/telemetry gateway'
  'import:Import config from another AI coding agent into Claude Code'
  'install:Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)'
  'kill:Stop a background session (alias for stop)'
  'logs:Print a background session'\''s recent terminal output'
  'mcp:Configure and manage MCP servers'
  'plugin:Manage Claude Code plugins'
  'plugins:Manage Claude Code plugins'
  'project:Deprecated - `claude project purge` is now `claude purge`'
  'purge:Delete all Claude Code state for a project (transcripts, tasks, file history, config entry)'
  'respawn:Restart a background session (or all of them) so it picks up the current Claude binary'
  'rm:Delete a background session and its worktree (works on already-exited sessions)'
  'self-hosted-runner:Start a runner process that hosts Claude Code cloud sessions on your infrastructure'
  'setup-token:Set up a long-lived authentication token (requires Claude subscription)'
  'remote-control:Connect your local environment to claude.ai/code'
  'stop:Stop a background session'
  'ultrareview:Run a cloud-hosted multi-agent code review of the current branch (or a PR number / base branch) and print the findings'
  'update:Check for updates and install if available'
  'upgrade:Check for updates and install if available'
)

local -a auth_commands
auth_commands=(
  'help:Display help for command'
  'login:Sign in to your Anthropic account'
  'logout:Log out from your Anthropic account'
  'status:Show authentication status'
)

local -a mcp_commands
mcp_commands=(
  'add:Add an MCP server to Claude Code'
  'add-from-claude-desktop:Import MCP servers from Claude Desktop (Mac and WSL only)'
  'add-json:Add an MCP server (stdio, SSE, HTTP, or WebSocket) with a JSON string'
  'get:Get details about an MCP server'
  'help:Display help for command'
  'list:List configured MCP servers'
  'login:Authenticate with an MCP server (HTTP, SSE, or claude.ai connector)'
  'logout:Clear stored OAuth credentials for an MCP server'
  'remove:Remove an MCP server'
  'reset-project-choices:Reset all approved and rejected project-scoped (.mcp.json) servers within this project'
  'serve:Start the Claude Code MCP server'
)

local -a plugin_commands
plugin_commands=(
  'configure:Show a plugin'\''s options and which are unset, or save values from stdin with --values-stdin'
  'details:Show a plugin'\''s component inventory and projected token cost'
  'disable:Disable an enabled plugin'
  'enable:Enable a disabled plugin'
  'eval:Run eval cases against a plugin and report scored results'
  'help:Display help for command'
  'init:Scaffold a new plugin at ~/.claude/skills/<name>/'
  'new:Scaffold a new plugin at ~/.claude/skills/<name>/'
  'install:Install a plugin from available marketplaces (use plugin@marketplace for specific marketplace)'
  'i:Install a plugin from available marketplaces (use plugin@marketplace for specific marketplace)'
  'list:List installed plugins'
  'marketplace:Manage Claude Code marketplaces'
  'prune:Remove auto-installed dependencies that are no longer needed'
  'autoremove:Remove auto-installed dependencies that are no longer needed'
  'uninstall:Uninstall an installed plugin'
  'remove:Uninstall an installed plugin'
  'tag:Create a {name}--v{version} git tag for a plugin release, validating that plugin.json and any enclosing marketplace entry agree'
  'test:Run a mod'\''s tests'
  'update:Update a plugin to the latest version (restart required to apply)'
  'validate:Validate a plugin or marketplace manifest, or the skills, agents, and commands in a directory'
)

local -a marketplace_commands
marketplace_commands=(
  'add:Add a marketplace from a URL, path, or GitHub repo'
  'help:Display help for command'
  'list:List all configured marketplaces'
  'remove:Remove a configured marketplace'
  'rm:Remove a configured marketplace'
  'update:Update marketplace(s) from their source - updates all if no name specified'
)

# Find the subcommand position by scanning for the first non-flag argument after the command name.
# This handles cases where flags appear before the subcommand (e.g., alias claude='claude --flag').
# Only words before the cursor count: the word being completed is not a
# subcommand yet, and words after it must not change what is offered here.
local subcmd_pos=0
local subcmd="" subcmd2="" subcmd3=""
# Every name in claude_commands must have a branch in the case statement below.
local -a known_commands=(${claude_commands%%:*})
local i
for (( i=2; i < CURRENT; i++ )); do
  # Skip flags and their values
  [[ "$words[$i]" == -* ]] && continue
  # Check if this word is a known subcommand
  if (( ${known_commands[(Ie)$words[$i]]} )); then
    subcmd_pos=$i
    subcmd="$words[$i]"
    break
  fi
done

# If no subcommand found yet, fall through to main _arguments
if [[ -n "$subcmd" ]]; then
# Drop everything before the subcommand so that $words[1] is the subcommand
# itself. `_arguments` counts positionals from $words[2], so each block
# below can list its own arguments without accounting for `claude` or for
# flags an alias put in front. Nested levels shift once more for the same
# reason, right before their own `case`.
shift $(( subcmd_pos - 1 )) words
(( CURRENT -= subcmd_pos - 1 ))

case $subcmd in
  agents)
    _arguments -s \
      '*--add-dir[Additional directory to allow tool access to in dispatched sessions (repeatable)]:directory:_files -/' \
      '--agent[Default agent for sessions dispatched from agent view. Overrides the agent setting]:agent:_claude_agents' \
      '--all[With --json: also include completed background sessions]' \
      '--allow-dangerously-skip-permissions[Make bypass-permissions mode available to dispatched sessions without defaulting to it]' \
      '--cwd[Show only background sessions started under path]:path:_files -/' \
      '--dangerously-skip-permissions[Alias for --permission-mode bypassPermissions]' \
      '--effort[Default effort level for sessions dispatched from agent view]:level:(low medium high xhigh max ultracode)' \
      '(-h --help)'{-h,--help}'[Display help for command]' \
      '--json[Print active sessions (interactive and background) as a JSON array and exit (for scripting; does not require a TTY)]' \
      '*--mcp-config[MCP server configuration to apply to dispatched sessions (repeatable)]:config:_files' \
      '--model[Default model for sessions dispatched from agent view]:model:_claude_models' \
      '--permission-mode[Default permission mode for sessions dispatched from agent view]:mode:(acceptEdits auto bypassPermissions manual dontAsk plan)' \
      '*--plugin-dir[Load plugins from specified directory for the agent view and dispatched sessions (repeatable)]:path:_files -/' \
      '--restricted[Start dispatched sessions in restricted mode]' \
      '--setting-sources[Comma-separated list of setting sources to load (user, project, local)]:sources:_values -s , source user project local' \
      '--settings[Settings file or JSON string to apply to the agent view and dispatched sessions]:file-or-json:_files' \
      '--strict-mcp-config[Only use MCP servers from --mcp-config in dispatched sessions]'
    return
    ;;
  attach|logs|stop|kill)
    _arguments \
      '(-h --help)'{-h,--help}'[Display help for command]' \
      ':session:_claude_background_session_ids'
    return
    ;;
  rm)
    _arguments \
      '--discard-unpushed[Also discard the worktree'\''s unpushed commits (and any uncommitted changes) while it is still the same worktree at that commit - pass the value a previous claude rm <id> reported]:commit@worktree-id:' \
      '--force-remove-worktree[Delete the worktree directory even though the WorktreeRemove hook or git couldn'\''t remove it - pass the value a previous claude rm <id> reported]:worktree-id:' \
      '(-h --help)'{-h,--help}'[Display help for command]' \
      ':session:_claude_background_session_ids'
    return
    ;;
  respawn)
    _arguments \
      '(--all)--all[Restart every stopped session]' \
      '(-h --help)'{-h,--help}'[Display help for command]' \
      '(--all):session:_claude_background_session_ids'
    return
    ;;
  auth)
    if (( CURRENT == 2 )); then
      _describe 'auth command' auth_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        login)
          _arguments \
            '--claudeai[Use Claude subscription (default)]' \
            '--console[Use Anthropic Console (API usage billing) instead of Claude subscription]' \
            '--email[Pre-populate email address on the login page]:email:' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--sso[Force SSO login flow]'
          ;;
        logout)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]'
          ;;
        status)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Output as JSON (default)]' \
            '--text[Output as human-readable text]'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  mcp)
    if (( CURRENT == 2 )); then
      _describe 'mcp command' mcp_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        serve)
          _arguments \
            '(-d --debug)'{-d,--debug}'[Enable debug mode]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--verbose[Override verbose mode setting from config]'
          ;;
        add)
          _arguments \
            '--callback-port[Fixed port for OAuth callback (for servers requiring pre-registered redirect URIs)]:port:' \
            '--client-id[OAuth client ID for HTTP/SSE servers]:clientId:' \
            '--client-secret[Prompt for OAuth client secret (or set MCP_CLIENT_SECRET env var)]' \
            '(-e --env)*'{-e,--env}'[Set environment variables (e.g. -e KEY=value)]:env:' \
            '(-H --header)*'{-H,--header}'[Set headers for HTTP/SSE servers (e.g. -H "X-Api-Key: abc123" -H "X-Custom: value")]:header:' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-s --scope)'{-s,--scope}'[Configuration scope (local, user, or project) (default: local)]:scope:(local user project)' \
            '(-t --transport)'{-t,--transport}'[Transport type (stdio, sse, http). Defaults to stdio if not specified]:transport:(stdio sse http)' \
            ':name:' \
            ':commandOrUrl:_files' \
            '*:args:_files'
          ;;
        remove)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-s --scope)'{-s,--scope}'[Configuration scope (local, user, or project) - if not specified, removes from whichever scope it exists in]:scope:(local user project)' \
            ':name:_claude_mcp_servers'
          ;;
        add-json)
          _arguments \
            '--client-secret[Prompt for OAuth client secret (or set MCP_CLIENT_SECRET env var)]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-s --scope)'{-s,--scope}'[Configuration scope (local, user, or project) (default: local)]:scope:(local user project)' \
            ':name:' \
            ':json:'
          ;;
        add-from-claude-desktop)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-s --scope)'{-s,--scope}'[Configuration scope (local, user, or project) (default: local)]:scope:(local user project)'
          ;;
        get)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            ':name:_claude_mcp_servers'
          ;;
        list|reset-project-choices)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]'
          ;;
        login)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--no-browser[Print the authorization URL instead of opening a browser (for SSH/headless sessions - paste the redirect URL back when prompted)]' \
            ':name:_claude_mcp_servers'
          ;;
        logout)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            ':name:_claude_mcp_servers'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  plugin|plugins)
    if (( CURRENT == 2 )); then
      _describe 'plugin command' plugin_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        configure)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Output as JSON]' \
            '--values-stdin[Read option values from stdin as a JSON object of single-line strings; options left out keep their values]' \
            ':plugin:_claude_installed_plugins'
          ;;
        details)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            ':name:_claude_installed_plugins'
          ;;
        tag)
          _arguments \
            '--dry-run[Print what would be tagged without creating it]' \
            '(-f --force)'{-f,--force}'[Skip the dirty-working-tree and tag-already-exists checks]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-m --message)'{-m,--message}'[Tag annotation message (use %s for the version)]:msg:' \
            '--push[Push the tag to --remote after creating it]' \
            '--remote[Remote to push to with --push (default: origin)]:name:' \
            '::path:_files'
          ;;
        test)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '::dir:_files -/'
          ;;
        validate)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Output the validation report as JSON (same exit codes)]' \
            '--strict[Treat warnings as errors (exit 1). Use in CI to fail on unrecognized fields, missing metadata, and other issues that the runtime tolerates]' \
            ':path:_files'
          ;;
        eval)
          # `eval init` is its own command with its own flags, and it may
          # come after eval flags (`plugin eval --verbose init --bare`). So
          # find the first word before the cursor that is neither an option
          # nor an option's value, and see whether it is `init`. The values
          # have to be skipped, or `--case init` would count: one word for
          # most options, one word if there is one for `--json [path]`, and
          # every word up to the next option for the `<value...>` ones.
          # Keep these lists in step with the eval options below.
          local -a eval_value_opts=(--ablation --case -j --concurrency
            --eval-dir --judge-model --max-cost-usd --mocks --model --output-dir
            --report --runs --threshold)
          local -a eval_optional_value_opts=(--json)
          local -a eval_multi_value_opts=(--allow-tools --disallow-tools --tag)
          i=2
          while (( i < CURRENT )); do
            if (( ${eval_value_opts[(Ie)$words[i]]} )); then
              (( i += 2 ))
            elif (( ${eval_optional_value_opts[(Ie)$words[i]]} )); then
              (( i++ ))
              (( i < CURRENT )) && [[ $words[i] != -* ]] && (( i++ ))
            elif (( ${eval_multi_value_opts[(Ie)$words[i]]} )); then
              (( i++ ))
              while (( i < CURRENT )) && [[ $words[i] != -* ]]; do
                (( i++ ))
              done
            elif [[ $words[i] == -* ]]; then
              (( i++ ))
            else
              break
            fi
          done
          if (( i < CURRENT )) && [[ $words[i] == init ]]; then
            shift $(( i - 1 )) words
            (( CURRENT -= i - 1 ))
            _arguments \
              '--bare[Write a blank template (prompt.md + graders/criteria.md) instead of running the interview]' \
              '--eval-dir[Directory (below the current directory) to write cases into (default: experimental.evals from the plugin.json in the current directory, else evals/)]:dir:_files -/' \
              '(-h --help)'{-h,--help}'[Display help]' \
              '(-i --interactive)'{-i,--interactive}'[Run the authoring interview (already the default in a terminal); requires an interactive terminal]' \
              '::name:'
          else
            # The action is in braces because `_arguments` passes compadd
            # options to a bare action, and `_alternative` rejects them.
            _arguments -s \
              '--ablation[Run a no-plugin baseline arm and report the score delta (none or with-without; default: with-without whenever a plugin resolves by name or target path, none otherwise; with-only graders like tool_used: Skill act as a plugin-fired indicator, not part of the score)]:mode:(none with-without)' \
              '--allow-real-servers[With --mocks record: also start the plugin'\''s real MCP server processes for servers with no mock (runs as you, outside the OS sandbox that confines shell tools; use only on plugins you trust)]' \
              '*--allow-tools[Operator grant for gated tools (Bash, Write, Edit, WebFetch, mcp__*). Supports Tool(pattern:*) syntax]:tools:' \
              '--case[Filter cases by name glob]:glob:' \
              '*--disallow-tools[Built-in tools to keep from Claude in every case, even if granted (e.g. Agent TaskStop)]:tools:' \
              '(-j --concurrency)'{-j,--concurrency}'[Run up to n agent runs at once (1-8; default 1); each is a full claude child on your own credential sharing one rate limit, results keep case order]:n:' \
              '--eval-dir[Directory name (below the plugin) that holds the eval cases; results go to <plugin>/<dir>/results/ (default: the manifest'\''s experimental.evals value, else evals/)]:dir:_files -/' \
              '(-h --help)'{-h,--help}'[Display help]' \
              '--json[Print the full run result (prompts, graders, per-run scores) as JSON to stdout, or write it to a .json file]::path:_files' \
              '--judge-model[Override LLM-grader model (default: haiku)]:model:_claude_models' \
              '--keep-temp[Preserve scaffold dirs for debugging]' \
              '--max-cost-usd[Optional hard cost ceiling; abort and report partial results if hit (exit 2). Checked before each run launches, so overrun is bounded to runs in flight; paid graders are skipped on breach while free graders still score]:usd:' \
              '--mocks[Mock stand-ins for MCP servers, from <eval dir>/mocks/ (default: record). record: a server with no mock isn'\''t started (see --allow-real-servers); off: every real server starts, gated by --allow-tools]:mode:(record off)' \
              '--model[Override model for all cases]:model:_claude_models' \
              '--no-publish[Keep the HTML report local only; skip publishing it to claude.ai]' \
              '--no-scaffold[Explicitly skip scaffold_script]' \
              '--output-dir[Directory for aggregate-result.json (default: ./<eval dir>/results/<timestamp>/)]:dir:_files -/' \
              '--publish-report[Also require publishing the report to claude.ai (already the default when your account supports it); explains why if unavailable]' \
              '--report[Write the self-contained HTML report (scores, prompts, grader verdicts) to path instead of the results dir]:path:_files' \
              '--runs[Override per-case runs (default: case.runs ?? 3)]:n:' \
              '--scaffold[Run each case'\''s scaffold_script (runs author-supplied bash as you; off by default — only use on case files you authored)]' \
              '*--tag[Filter cases by tag (repeatable)]:tag:' \
              '--threshold[Exit 1 if any case score is below this threshold (default: 1.0)]:threshold:' \
              '--trust-plugin[Assert that you trust this plugin'\''s code and eval suite, and skip the first-run trust prompt (for CI; does not imply --scaffold, --allow-tools, or --mocks off)]' \
              '--verbose[Log per-message trace events to the debug log (use --debug-file to read them)]' \
              '::command-or-target:{_alternative "commands:command:(init)" "plugins:installed plugin:_claude_installed_plugins" "files:target:_files"}'
          fi
          ;;
        marketplace)
          if (( CURRENT == 2 )); then
            _describe 'marketplace command' marketplace_commands
          else
            subcmd3=$words[2]
            shift words; (( CURRENT-- ))
            case $subcmd3 in
              add)
                _arguments \
                  '--claudeai[Add the marketplace of this name that claude.ai hosts for you, by its listed name or its local name]' \
                  '(-h --help)'{-h,--help}'[Display help]' \
                  '--json[Print one machine-readable result line as the last line on stdout (same exit codes)]' \
                  '--scope[Where to declare the marketplace: user (default), project, or local]:scope:(user project local)' \
                  '*--sparse[Limit checkout to specific directories via git sparse-checkout (for monorepos), e.g. --sparse .claude-plugin plugins]:path:_files -/' \
                  ':source:_files'
                ;;
              remove|rm)
                _arguments \
                  '(-h --help)'{-h,--help}'[Display help]' \
                  '--json[Print one machine-readable result line as the last line on stdout (same exit codes)]' \
                  '--scope[Remove the marketplace declaration from a specific settings scope: user, project, or local. Omit to remove it from every scope]:scope:(user project local)' \
                  ':name:_claude_marketplaces'
                ;;
              update)
                _arguments \
                  '(-h --help)'{-h,--help}'[Display help]' \
                  '--json[With a marketplace name: print one machine-readable result line as the last line on stdout (same exit codes)]' \
                  '::name:_claude_marketplaces'
                ;;
              list)
                _arguments \
                  '(-h --help)'{-h,--help}'[Display help]' \
                  '--json[Output as JSON]'
                ;;
              *)
                _message 'no more arguments'
                ;;
            esac
          fi
          ;;
        init|new)
          _arguments \
            '--author[Author name (default: git config user.name)]:name:' \
            '--author-email[Author email (default: git config user.email)]:email:' \
            '--description[Manifest description]:text:' \
            '(-f --force)'{-f,--force}'[Overwrite an existing .claude-plugin/ at the target]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '*--with[Also scaffold additional components]:component:(skills agents hooks mcp lsp output-style channel)' \
            ':name:'
          ;;
        install|i)
          _arguments \
            '--accept-command[Accept the marketplace-declared command (a command-source install, or the headersHelper fetching the archive) whose sha256 a previous --json run reported as shownCommand.sha256; only covers that exact command for that plugin/marketplace]:sha256:' \
            '*--config[Set a userConfig option declared in the plugin'\''s manifest (repeatable)]:key=value:' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Print one machine-readable result line on stdout instead of the human message (same exit codes; a marketplace-declared command is still shown and must be confirmed - pass -y when not interactive)]' \
            '--marketplace[Install <plugin> (its bare name) from the marketplace at this source: owner/repo, a git or https URL, or a path; added first if not yet added]:source:_files' \
            '--registry[For a <package>@npm install: resolve and download from this npm registry instead of the one your npm configuration selects]:url:' \
            '(-s --scope)'{-s,--scope}'[Installation scope: user, project, or local (default: user)]:scope:(user project local)' \
            '(-y --yes)'{-y,--yes}'[Accept the displayed marketplace-declared command without the confirmation prompt - a plugin installed by running a command, or one fetched via a headersHelper command (required when stdin or stdout is not a TTY)]' \
            ':plugin:_claude_marketplace_plugins'
          ;;
        prune|autoremove)
          _arguments \
            '--dry-run[List what would be removed without removing]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-s --scope)'{-s,--scope}'[Prune at scope: user, project, or local (default: user)]:scope:(user project local)' \
            '(-y --yes)'{-y,--yes}'[Skip the confirmation prompt (required when stdin or stdout is not a TTY)]'
          ;;
        uninstall|remove)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Print one machine-readable result line on stdout instead of the human message (same exit codes; not with --prune)]' \
            '--keep-data[Preserve the plugin'\''s persistent data directory (~/.claude/plugins/data/{id}/)]' \
            '--prune[Also remove auto-installed dependencies that are no longer needed (requires -y in non-interactive contexts)]' \
            '(-s --scope)'{-s,--scope}'[Uninstall from scope: user, project, or local (default: user)]:scope:(user project local)' \
            '(-y --yes)'{-y,--yes}'[Skip the --prune confirmation prompt (required when stdin or stdout is not a TTY)]' \
            ':plugin:_claude_installed_plugins'
          ;;
        enable)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Print one machine-readable result line on stdout instead of the human message (same exit codes)]' \
            '(-s --scope)'{-s,--scope}'[Installation scope: user, project, local (default: auto-detect)]:scope:(user project local)' \
            ':plugin:_claude_installed_plugins'
          ;;
        disable)
          _arguments \
            '(-a --all)'{-a,--all}'[Disable all enabled plugins]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Print one machine-readable result line on stdout instead of the human message (same exit codes)]' \
            '(-s --scope)'{-s,--scope}'[Installation scope: user, project, local (default: auto-detect)]:scope:(user project local)' \
            '::plugin:_claude_installed_plugins'
          ;;
        update)
          _arguments \
            '--accept-command[Accept the marketplace-declared command (a command-source install, or the headersHelper fetching the archive) whose sha256 a previous --json run reported as shownCommand.sha256; only covers that exact command for that plugin/marketplace]:sha256:' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Print one machine-readable result line on stdout instead of the human message (same exit codes; a marketplace-declared command is still shown and must be confirmed - pass -y when not interactive)]' \
            '(-s --scope)'{-s,--scope}'[Installation scope: user, project, local, managed (default: user)]:scope:(user project local managed)' \
            '(-y --yes)'{-y,--yes}'[Accept the displayed marketplace-declared command without the confirmation prompt - a changed install command, or the headersHelper command that fetches its archive (required when stdin or stdout is not a TTY)]' \
            ':plugin:_claude_installed_plugins'
          ;;
        list)
          _arguments \
            '--available[Include available plugins from marketplaces (requires --json)]' \
            '--data-size[Measure each installed plugin'\''s saved data directory, or only the named plugin'\''s (requires --json)]::plugin:_claude_installed_plugins' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json[Output as JSON]'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  project)
    if (( CURRENT == 2 )); then
      local -a project_commands
      project_commands=(
        'help:Display help for command'
        'purge:Deprecated alias for `claude purge`'
      )
      _describe 'project command' project_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        purge)
          _arguments \
            '--all[Purge state for every project (mutually exclusive with \[path\])]' \
            '--dry-run[List what would be deleted without deleting anything]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-i --interactive)'{-i,--interactive}'[Prompt for each item before deleting]' \
            '(-y --yes)'{-y,--yes}'[Skip confirmation prompt]' \
            '::path:_files -/'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  purge)
    _arguments \
      '--all[Purge state for every project (mutually exclusive with \[path\])]' \
      '--dry-run[List what would be deleted without deleting anything]' \
      '(-h --help)'{-h,--help}'[Display help for command]' \
      '(-i --interactive)'{-i,--interactive}'[Prompt for each item before deleting]' \
      '(-y --yes)'{-y,--yes}'[Skip confirmation prompt]' \
      '::path:_files -/'
    return
    ;;
  daemon)
    if (( CURRENT == 2 )); then
      local -a daemon_commands
      daemon_commands=(
        'run:Run the supervisor in the foreground (default when piped)'
        'status:Show daemon pid, version, uptime'
        'logs:Tail the daemon log (Ctrl-C to stop)'
        'uninstall:Remove the background service (launchctl/systemd)'
        'stop:Shut down the supervisor and terminate background sessions'
      )
      _describe 'daemon command' daemon_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        run)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json-path[Config file (default: ~/.claude/daemon.json)]:path:_files' \
            '--log-file[Log file (default: ~/.claude/daemon.log)]:path:_files' \
            '::json-path:_files'
          ;;
        stop)
          _arguments \
            '--any[Also stop a transient (non-service) daemon]' \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json-path[Config file (default: ~/.claude/daemon.json)]:path:_files' \
            '--keep-workers[Leave detached sessions running]' \
            '--log-file[Log file (default: ~/.claude/daemon.log)]:path:_files'
          ;;
        status|logs|uninstall)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--json-path[Config file (default: ~/.claude/daemon.json)]:path:_files' \
            '--log-file[Log file (default: ~/.claude/daemon.log)]:path:_files'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  self-hosted-runner)
    # setup, doctor and orchestrator are only recognized as the first word;
    # with anything else there (or nothing), the options belong to the runner.
    if (( CURRENT > 2 )) && [[ "$words[2]" == (setup|doctor|orchestrator) ]]; then
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        orchestrator)
          _arguments \
            '--api-url[API base URL (default: https://api.anthropic.com)]:url:' \
            '--debug-dir[DEV ONLY — writes each work-order JWT + decoded JSON + hook stderr to <dir>/<jti>.{jwt,json,stderr}]:path:_files -/' \
            '--environment-secret-file[Path to environment secret file (or set SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET)]:path:_files' \
            '--expected-spawn-seconds[p99 boot time for runners this orchestrator spawns (default: 120)]:n:' \
            '--health-port[Port for /healthz HTTP listener (default: 8080). 0 disables]:port:' \
            '(-h --help)'{-h,--help}'[Show this help message]' \
            '--hook-concurrency[Max spawn-runner hooks running in parallel (default: 4)]:n:' \
            '--hook-timeout[SIGTERM the hook after <sec> seconds (default: 60)]:sec:' \
            '--hooks-dir[Directory containing the spawn-runner hook (REQUIRED)]:path:_files -/' \
            '--log-level[Log level: info or debug (default: info)]:level:(info debug)' \
            '--min-idle[Keep at least <n> idle slots free (free capacity across runners, not runner count; default: 0, disabled)]:n:' \
            '--scm-connector-ca-file[Extra CA bundle (PEM) for TLS to the GHES host]:path:_files' \
            '--scm-connector-host[GHES hostname to forward to (port defaults to 443). Setting this enables the connector]:host:' \
            '--scm-connector-host-rewrite[e2e only — redirect the TCP connect while keeping Host/SNI as --scm-connector-host]:from=to_host\:to_port:' \
            '--scm-connector-id[ghe_configurations.id for this org (REQUIRED with --scm-connector-host)]:n:' \
            '--scm-connector-provider[Provider slug (default: ghe)]:provider:' \
            '--shutdown-drain-sec[On SIGTERM, stop polling but give the poll in flight and the running hooks up to <n> seconds to end (default: 0, stop them at once)]:n:'
          ;;
        setup|doctor)
          # Extra args are passed to the underlying Claude Code session.
          _arguments \
            '(-h --help)'{-h,--help}'[Show this help message]' \
            '*:args:'
          ;;
      esac
    elif (( CURRENT == 2 )) && [[ "$words[2]" != -* ]]; then
      local -a self_hosted_runner_commands
      self_hosted_runner_commands=(
        'setup:Interactive wizard: walks you from zero to a working self-hosted runner environment'
        'doctor:Interactive wizard: diagnoses a self-hosted runner deployment'
        'orchestrator:Poll the spawn-hints queue and run the spawn-runner hook once per hint'
      )
      _describe 'self-hosted-runner command' self_hosted_runner_commands
    else
      _arguments \
        '--api-url[API base URL (default: https://api.anthropic.com)]:url:' \
        '--base-dir[Base directory for repo checkouts (default: /workspace; required on Windows, which has no default)]:path:_files -/' \
        '--capacity[Max concurrent sessions (default: 1)]:n:' \
        '--client-label[Observability label sent at registration (default: hostname)]:label:' \
        '--configure-git[Set global git identity to Claude <noreply@anthropic.com> and enable commit signing via Anthropic'\''s signing service, matching 1P sessions]' \
        '--confine-repo-settings[Repo-committed-settings confine guard mode: warn (default), enforce or off]:mode:(warn enforce off)' \
        '--debug-token-dir[DEBUG ONLY — writes live tokens to disk. Do not use in production]:path:_files -/' \
        '--defer-shutdown-max-min[On the first SIGTERM/SIGINT, stop taking new work and finish shutting down M minutes later instead of draining]:m:' \
        '--drain-grace-sec[Keep the runner warm and re-poll the locked account'\''s queue for that many seconds before exiting (default: 0)]:n:' \
        '--drain-marker-file[Marker file a host writes to announce a graceful drain before sending SIGTERM (telemetry only)]:path:_files' \
        '--drain-wait-sec[On SIGTERM/SIGINT, wait up to N seconds for each session'\''s in-flight turn and running background tasks to finish]:n:' \
        '--environment-secret-file[Path to environment secret file (or set SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET)]:path:_files' \
        '--exec-path[Binary to spawn for child sessions. Default: this process'\''s own binary]:path:_files' \
        '--exit-if-unused-min[Exit the runner if never assigned work for N min (autoscaler scale-down)]:n:' \
        '*--git-host-rewrite[Rewrite https://<f>/... source URLs to https://<t>/... (repeatable)]:from=to:' \
        '*--git-ssh-rewrite[Rewrite https://<host>/... source URLs to git@<host>\:... (repeatable)]:host:' \
        '--health-port[Port for /healthz HTTP listener (default: 8080). 0 disables]:port:' \
        '(-h --help)'{-h,--help}'[Show this help message]' \
        '--hooks-dir[Directory of lifecycle hook scripts (checkout, command, post-session)]:path:_files -/' \
        '--host-config-snapshot[Where the startup snapshot of the host config directory is held (default: disk)]:mode:(disk memory)' \
        '--kill-session-after-min[Cap a session child'\''s wall-clock life at N min (runaway backstop)]:n:' \
        '--lock-to-account[Lock runner to a single account at registration (webhook-driven on-demand spawn)]:id:' \
        '--log-file[Tee runner logs to a file in append mode. Stdout is unchanged]:path:_files' \
        '--log-level[Log level: info or debug (default: info)]:level:(info debug)' \
        '--post-session-hook-timeout-sec[SIGTERM budget for the post-session lifecycle hook, on every session end including runner shutdown. Default: 60]:n:' \
        '--proxy-authorization-command[Shell command whose stdout is the Proxy-Authorization header value, run afresh for each new connection to the egress proxy]:shell command:' \
        '--proxy-authorization-file[Same as --proxy-authorization-command, but the header value is read from a file]:path:_files' \
        '--push-outcome-on-release[On a runner-initiated non-completed session end, push every tracked outcome branch to origin before deleting it]' \
        '--release-idle-session-min[Release a session slot after N min of no user input]:n:' \
        '--remove-session-state[Remove a session'\''s per-session state under <base-dir>/_sessions/ when it ends on this runner. Default: false]::bool:(true false)' \
        '--retire-at[Retire the runner at the given wall-clock time (absolute Unix timestamp, in seconds)]:epoch-seconds:' \
        '--server-auto-mode-lists[Which of the server'\''s auto mode classifier lists a session may receive in its launcher settings: all, no-allow (default) or none]:mode:(all no-allow none)' \
        '--session-stop-grace-sec[How long to wait for the Claude process to exit cleanly after a session ends, before force-killing it. Default: 5]:n:' \
        '--startup-timeout-min[Release a session slot if the child has not completed initialization N min after spawn. Default: 15. 0 disables]:n:' \
        '--trust-workspace[Seed persisted trust for each session'\''s repo paths so repo-level .claude/settings.json grants are honored by the child. Default: true]::bool:(true false)' \
        '--use-anthropic-git-proxy[Opt this runner into Anthropic-managed git. WARNING: deletes and replaces the HOME-level git config of the account running the runner]'
    fi
    return
    ;;
  auto-mode)
    if (( CURRENT == 2 )); then
      local -a auto_mode_commands
      auto_mode_commands=(
        'config:Print the effective auto mode config as JSON: your settings where set, defaults otherwise'
        'critique:Get AI feedback on your custom auto mode rules'
        'defaults:Print the default auto mode environment, allow, soft_deny, and hard_deny rules as JSON'
        'help:Display help for command'
        'reset:Reset auto mode configuration to the shipped defaults by removing the autoMode section from your user settings file'
      )
      _describe 'auto-mode command' auto_mode_commands
    else
      subcmd2=$words[2]
      shift words; (( CURRENT-- ))
      case $subcmd2 in
        critique)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--model[Override which model is used]:model:_claude_models'
          ;;
        reset)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '(-y --yes)'{-y,--yes}'[Skip the confirmation prompt]'
          ;;
        config)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]'
          ;;
        defaults)
          _arguments \
            '(-h --help)'{-h,--help}'[Display help]' \
            '--label[Show only rules whose label starts with this prefix (case-insensitive)]:prefix:'
          ;;
        *)
          _message 'no more arguments'
          ;;
      esac
    fi
    return
    ;;
  install)
    _arguments \
      '--force[Force installation even if already installed]' \
      '(-h --help)'{-h,--help}'[Display help]' \
      ':target:(stable latest)'
    return
    ;;
  import)
    _arguments \
      '--dry-run[Show what would be imported without writing anything]' \
      '(-h --help)'{-h,--help}'[Display help]' \
      '--yes[Skip the interactive picker. On headless surfaces, pass --yes=<digest> from the /import preview]' \
      '::source:(codex gemini cursor)'
    return
    ;;
  remote-control)
    _arguments \
      '--capacity[Max concurrent sessions in worktree or same-dir mode (default: 32)]:n:' \
      '(--no-chrome)--chrome[Turn on Claude in Chrome for spawned sessions (default: off)]' \
      '(--chrome)--no-chrome[Turn off Claude in Chrome for spawned sessions]' \
      '(-c --continue --session-id)'{-c,--continue}'[Resume the last Remote Control session in this directory]' \
      '--create-session-in-dir[Pre-create a session in the current directory when the server starts (default: on)]' \
      '--no-create-session-in-dir[Skip pre-creating a session in the current directory]' \
      '(-d --debug)-d[Enable debug mode for this process]' \
      '(-d --debug)--debug=-[Enable debug mode for this process, with optional category filtering (e.g. --debug=api,hooks)]::filter:' \
      '--debug-file[Write debug logs to a specific file path]:path:_files' \
      '(-h --help)'{-h,--help}'[Display help]' \
      '--name[Name for the session (shown in claude.ai/code)]:name:' \
      '--permission-mode[Permission mode for spawned sessions]:mode:(acceptEdits auto bypassPermissions manual dontAsk plan)' \
      '--remote-control-session-name-prefix[Prefix for auto-generated session names (default: hostname)]:prefix:' \
      '(--session-id -c --continue)--session-id[Resume a specific Remote Control session by ID (cannot be used with spawn flags or --continue)]:id:' \
      '--spawn[Spawn mode for on-demand sessions (default: same-dir)]:mode:(same-dir worktree session)' \
      '(-v --verbose)'{-v,--verbose}'[Show detailed connection and session logs]'
    return
    ;;
  gateway)
    _arguments \
      '--config[Path to gateway YAML config]:path:_files' \
      '(-h --help)'{-h,--help}'[Display help]'
    return
    ;;
  ultrareview)
    _arguments \
      '(-h --help)'{-h,--help}'[Display help]' \
      '--json[Print the raw bugs.json payload instead of formatted findings]' \
      '(--no-post --post)--no-post[Do not post the findings to the PR (the default; accepted for parity with the /ultrareview and /code-review ultra flags)]' \
      '(--no-post --post)--post[Post the finished review'\''s findings to the PR as you (PR targets only; one plain comment, not a review)]' \
      '--timeout[Maximum minutes to wait for the review to finish (default: 45)]:minutes:' \
      '::target:'
    return
    ;;
  setup-token|doctor|update|upgrade)
    _arguments \
      '(-h --help)'{-h,--help}'[Display help]'
    return
    ;;
esac
fi # end: if [[ -n "$subcmd" ]]

# Only show global flags and commands if no subcommand matched
_arguments -s \
  '*--add-dir[Additional directories to allow tool access to]:directory:_files -/' \
  '--advisor[Enable a server-side advisor tool using the specified model]:model:(fable opus sonnet)' \
  '--agent[Agent for the current session. Overrides the agent setting]:agent:_claude_agents' \
  '--agents[JSON object defining custom agents]:json:' \
  '--allow-dangerously-skip-permissions[Enable bypassing all permission checks as an option, without it being enabled by default. Recommended only for sandboxes with no internet access]' \
  '*--allowedTools[Comma or space-separated list of tool names to allow (e.g. "Bash(git:*) Edit")]:tools:' \
  '*--allowed-tools[Comma or space-separated list of tool names to allow (e.g. "Bash(git:*) Edit")]:tools:' \
  '--append-subagent-system-prompt[Append a system prompt to every Task-tool subagent'\''s system prompt, propagated to nested subagents (only works with --print)]:prompt:' \
  '--append-subagent-system-prompt-file[Read a system prompt from a file and append it to every Task-tool subagent'\''s system prompt (only works with --print)]:file:_files' \
  '--append-system-prompt[Append a system prompt to the default system prompt]:prompt:' \
  '--append-system-prompt-file[Append a system prompt from a file to the default system prompt]:file:_files' \
  '--autocompact[Auto-compact window size (auto, or 100k-1M tokens)]:size:' \
  '--ax-screen-reader[Render screen-reader friendly output (flat text, no decorative borders or animations)]' \
  '--bare[Minimal mode: skip hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets CLAUDE_CODE_SIMPLE=1]' \
  '(--bg --background)'{--bg,--background}'[Start the session as a background agent and return immediately (manage with `claude agents`)]' \
  '*--betas[Beta headers to include in API requests (API key users only)]:betas:' \
  '--brief[Enable SendUserMessage tool for agent-to-user communication]' \
  '*--channels[MCP servers to listen for channel notifications (e.g. plugin:<name>@<marketplace> or server:<name>)]:server:' \
  '--chrome[Enable Claude in Chrome integration]' \
  '--client-data-url[URL for a signed configuration document. Claude Code exits if it cannot load it or it does not cover the selected model]:url:' \
  '(--cloud --remote)'{--cloud,--remote}'[Create a cloud session with the given description, or attach to an existing one by session ID or claude.ai/code URL (--remote is a deprecated alias)]::description:' \
  '(-c --continue)'{-c,--continue}'[Continue the most recent conversation in the current directory]' \
  '*--dangerously-load-development-channels[Bypass the channel plugin allowlist for local testing]:server:' \
  '--dangerously-skip-permissions[Bypass all permission checks. Recommended only for sandboxes with no internet access]' \
  '(-d --debug)'{-d,--debug}'[Enable debug mode with optional category filtering (e.g., "api,hooks" or "!1p,!file")]:filter:' \
  '--debug-file[Write debug logs to a specific file path (implicitly enables debug mode)]:path:_files' \
  '--desktop[Open in the Claude Desktop app instead of the terminal (with --continue or --resume <id> to pick the session)]' \
  '--disable-slash-commands[Disable all skills]' \
  '*--disallowedTools[Comma or space-separated list of tool names to deny (e.g. "Bash(git:*) Edit")]:tools:' \
  '*--disallowed-tools[Comma or space-separated list of tool names to deny (e.g. "Bash(git:*) Edit")]:tools:' \
  '--effort[Effort level for the current session (low, medium, high, xhigh, max)]:level:(low medium high xhigh max ultracode)' \
  '--environment[Create a new cloud session that runs on the given self-hosted environment (ccpool_...)]:environment_id:' \
  '--exclude-dynamic-system-prompt-sections[Move per-machine sections (cwd, env info, memory paths, git status) from the system prompt into the first user message. Improves cross-user prompt-cache reuse. Only applies with the default system prompt (ignored with --system-prompt)]' \
  '--exec[Run a shell command as a background job instead of a Claude session (requires --bg)]:command:' \
  '--fallback-model[Enable automatic fallback to specified model(s) when default model is overloaded or not available. Accepts a comma-separated list to try each in order. Re-tries the primary at the start of each user turn (only works with --print)]:model:_sequence _claude_models' \
  '*--file[File resources to download at startup. Format: file_id:relative_path (e.g., --file file_abc:doc.txt file_def:img.png)]:file:' \
  '--fork-session[When resuming, create a new session ID instead of reusing the original (use with --resume or --continue)]' \
  '--forward-subagent-text[Forward subagent text and thinking blocks as assistant/user messages with parent_tool_use_id set (only works with --print and --output-format=stream-json)]' \
  '--from-pr[Resume a session linked to a PR by PR number/URL, or open interactive picker with optional search term]:value:' \
  '(-h --help)'{-h,--help}'[Display help for command]' \
  '--ide[Automatically connect to IDE on startup if exactly one valid IDE is available]' \
  '--include-hook-events[Include all hook lifecycle events in the output stream (only works with --output-format=stream-json)]' \
  '--include-partial-messages[Include partial message chunks as they arrive (only works with --print and --output-format=stream-json)]' \
  '--init[Run Setup hooks with the init matcher before starting the session]' \
  '--init-only[Run Setup hooks with the init matcher, then exit]' \
  '--input-format[Input format (only works with --print): "text" (default), or "stream-json" (realtime streaming input)]:format:(text stream-json)' \
  '--json-schema[JSON Schema for structured output validation. Example: {"type":"object","properties":{"name":{"type":"string"}},"required":["name"\]\}]:schema:' \
  '--maintenance[Run Setup hooks with the maintenance matcher, then continue]' \
  '--max-budget-usd[Maximum dollar amount to spend on API calls (only works with --print)]:amount:' \
  '--max-turns[Limit the number of agentic turns (only works with --print)]:turns:' \
  '*--mcp-config[Load MCP servers from JSON files or strings (space-separated)]:config:_files' \
  '--model[Model for the current session. Provide an alias for the latest model (e.g. '\''fable'\'', '\''opus'\'', or '\''sonnet'\'') or a model'\''s full name (e.g. '\''claude-fable-5'\'')]:model:_claude_models' \
  '(-n --name)'{-n,--name}'[Set a display name for this session (shown in the prompt box, /resume picker, and terminal title)]:name:' \
  '--no-chrome[Disable Claude in Chrome integration]' \
  '--no-session-persistence[Disable session persistence - sessions will not be saved to disk and cannot be resumed (only works with --print)]' \
  '--output-format[Output format (only works with --print): "text" (default), "json" (single result), or "stream-json" (realtime streaming)]:format:(text json stream-json)' \
  '--permission-mode[Permission mode to use for the session]:mode:(acceptEdits auto bypassPermissions manual dontAsk plan)' \
  '--permission-prompt-tool[MCP tool name to handle permission prompts (only works with --print)]:tool:' \
  '--permission-prompts[Who answers permission prompts with --print: host (the SDK host or --permission-prompt-tool) or none (deny automatically)]:target:(host none)' \
  '*--plugin-dir[Load a plugin from a directory or .zip for this session only (repeatable: --plugin-dir A --plugin-dir B.zip)]:directory:_files -/' \
  '*--plugin-url[Fetch a plugin .zip from a URL for this session only (repeatable: --plugin-url A --plugin-url B)]:url:' \
  '(-p --print)'{-p,--print}'[Print response and exit (useful for pipes). Note: The workspace trust dialog is skipped when Claude is run in non-interactive mode. Only use this in directories you trust]' \
  '--prompt-suggestions[Enable prompt suggestions. In print/SDK mode, emits a prompt_suggestion message after each turn with a predicted next user prompt]:value:(true false 1 0 yes no on off)' \
  '--ref[Branch, tag, or SHA to check out in the remote session; defaults to local current branch (requires --cloud or --environment)]:ref:' \
  '(--remote-control --rc)'{--remote-control,--rc}'[Start an interactive session with Remote Control enabled (optionally named)]::name:' \
  '--remote-control-session-name-prefix[Prefix for auto-generated Remote Control session names (default: hostname)]:prefix:' \
  '--replay-user-messages[Re-emit user messages from stdin back on stdout for acknowledgment (only works with --input-format=stream-json and --output-format=stream-json)]' \
  '--restricted[Restricted mode: removes the built-in tools that run commands or code (Bash, PowerShell and the other code-running tools) and WebFetch unless --tools names them, and ignores user, project and local settings files (managed settings and --settings still apply; add --strict-mcp-config to skip MCP servers too). Also confines the file tools to the working directories (--add-dir included), refuses bypassPermissions, and lets only a person or the configured permission handler approve writes to settings, git and tool-configuration files]' \
  '(-r --resume)'{-r,--resume}'[Resume a conversation by session ID, or open interactive picker with optional search term]:session:_claude_session_ids' \
  '--safe-mode[Start with all customizations disabled — useful for troubleshooting a broken configuration. Admin-managed settings still apply. Sets CLAUDE_CODE_SAFE_MODE=1]' \
  '--session-id[Use a specific session ID for the conversation (must be a valid UUID)]:uuid:' \
  '--setting-sources[Comma-separated list of setting sources to load (user, project, local)]:sources:_values -s , source user project local' \
  '--settings[Path to a settings JSON file or a JSON string to load additional settings from]:file:_files' \
  '--strict-mcp-config[Only use MCP servers from --mcp-config, ignoring all other MCP configurations]' \
  '--system-prompt[System prompt to use for the session]:prompt:' \
  '--system-prompt-file[Read system prompt from a file]:file:_files' \
  '--system-prompt-snapshot[Record the system prompt once per conversation and reuse it verbatim on every request and resume]:mode:(on off)' \
  '--teammate-mode[Set agent team display mode]:mode:(auto tmux iterm2 in-process)' \
  '--teleport[Resume a cloud session in the local terminal, or open an interactive picker with optional session ID]::session-id:' \
  '--tmux[Create a tmux session for the worktree (requires --worktree). Uses iTerm2 native panes when available; use --tmux=classic for traditional tmux]::style:(classic)' \
  '*--tools[Specify the list of available tools from the built-in set. Use "" to disable all tools, "default" to use all tools, or specify tool names (e.g. "Bash,Edit,Read")]:tools:' \
  '--verbose[Override verbose mode setting from config]' \
  '(-v --version)'{-v,--version}'[Output the version number]' \
  '(-w --worktree)'{-w,--worktree}'[Create a new git worktree for this session (optionally specify a name)]::name:' \
  "1:command:($known_commands)" \
  '*:prompt:'