# Navigators Source: https://zshot-cli.com/reference/navigator/navigators/ Markdown: https://zshot-cli.com/reference/navigator/navigators/index.md Section: [Reference](https://zshot-cli.com/reference/) › [Navigator](https://zshot-cli.com/reference/navigator/) Repeat [`--navigator-type`](/reference/flags/navigator/navigator-type) to add navigators to a session. The first acts. It is offered `ESCALATE` and a list of the others, each with its name, provider, model, abilities (`vision`, `writes_text`, `reasons`) and when to choose it. Name each navigator and say when to choose it with `name=` and `when=`. A name defaults to the provider and must be unique; two navigators with one name exit with code 3. ```sh zshot --navigate "Open the formats page" \ --navigator-type "typesafe://?name=scout&when=routine%20pages" \ --navigator-type "anthropic://?model=claude-opus-5-5&name=opus&when=a%20page%20error%20or%20a%20loop%20the%20scout%20can't%20get%20past" \ https://zshot-cli.com/ ``` A [`--llm-format-model`](/reference/flags/document/llm-format-model) with `escalate=true` joins the navigators, and `escalate=false` keeps a navigator from being escalated to. [`--navigator-max-steps`](/reference/flags/navigator/navigator-max-steps) counts each `ESCALATE` as a step. ## Escalation The navigator chosen takes a turn on the page from the next step: one action, or up to [`--navigator-escalation-max`](/reference/flags/navigator/navigator-escalation-max), ending when it leaves the page. Then the navigator that escalated acts again, reading the other's reasoning first. While its turn lasts, the navigator escalated to cannot escalate back. A press it holds keeps the turn going until released, and a dialog it opens until answered. Reporting the goal impossible or restarting hands control back. If the navigator it hands back to escalates straight back, that second request is taken. ## Stalls A navigator stalls after [`--navigator-stall-escalation`](/reference/flags/navigator/navigator-stall-escalation) steps on one page. A page is its URL, query and fragment included, so a `?step=2` or a single-page app's route is another page. A step whose action changed the page's text, scrolled the page or a panel, or changed what a navigator's screenshot shows starts the count again, so clicking "Load more" many times is not a stall. A navigator that reads images is first shown the page after the stall steps its `vision=` sets, 3 by default. A stalled navigator hands the session to the first other navigator it can escalate to, with the same turn as an `ESCALATE`, and the count starts again. A navigator with no one to escalate to goes on, and fails only once it has taken one action more than the limit in a row, with exit code 9 and a message such as `Navigation failed: CLICK [BTN] "Accept" taken more than 10 times in a row`. ## Outages A navigator whose provider is still down after its retries is passed over for 60 seconds. The session goes on with the navigator that escalated to it, or else the first one it could escalate to, and asks it again once the 60 seconds pass. With none available the navigation fails. A model that gives no reply within [`--navigator-step-timeout`](/reference/flags/navigator/navigator-step-timeout) is unavailable the same way. ## Writer `writer=true` makes a navigator write the text the others choose to write. The acting navigator still chooses every action, element and value; where it chooses written text, the writer is asked for the words alone. Pair it with [`typesafe`](/reference/llm_connections/typesafe), which writes no text, to type a search or fill a form without a credential for every field: ```sh zshot --navigate "Search the docs for WARC" \ --navigator-type typesafe \ --navigator-type "anthropic://?name=writer&writer=true&escalate=false" \ https://zshot-cli.com/ ``` Without `escalate=false` the writer can also be escalated to. Only one navigator may be the writer, and it must write text: `typesafe` as the writer exits with code 3. While the writer's provider is down, no text is offered to the navigators it writes for. ## Related Flags: - [`--navigator-type`](https://zshot-cli.com/reference/flags/navigator/navigator-type/) - [`--navigator-escalation-max`](https://zshot-cli.com/reference/flags/navigator/navigator-escalation-max/) - [`--navigator-stall-escalation`](https://zshot-cli.com/reference/flags/navigator/navigator-stall-escalation/) - [`--navigator-max-steps`](https://zshot-cli.com/reference/flags/navigator/navigator-max-steps/) - [`--llm-format-model`](https://zshot-cli.com/reference/flags/document/llm-format-model/) Topics: - [LLM Connections](https://zshot-cli.com/reference/llm_connections/) - [Connection String Options](https://zshot-cli.com/reference/llm_connections/options/) — Navigator options - [Exit Codes](https://zshot-cli.com/reference/exit_codes/) ## Navigation - [Examples](https://zshot-cli.com/examples/) - [Download](https://zshot-cli.com/download/) - [Purchase](https://zshot-cli.com/purchase/) - [Reference](https://zshot-cli.com/reference/) - [Formats](https://zshot-cli.com/reference/formats/) - [Flags](https://zshot-cli.com/reference/flags/) - [Agents](https://zshot-cli.com/reference/agents/) - [Configuration](https://zshot-cli.com/reference/configuration/) - [Crawling](https://zshot-cli.com/reference/crawling/) - [Docker](https://zshot-cli.com/reference/docker/) - [Exit Codes](https://zshot-cli.com/reference/exit_codes/) - [Linux](https://zshot-cli.com/reference/linux/) - [LLM Connections](https://zshot-cli.com/reference/llm_connections/) - [LLM Formatting](https://zshot-cli.com/reference/llm_formatting/) - [Local Inputs](https://zshot-cli.com/reference/inputs/) - [Navigator](https://zshot-cli.com/reference/navigator/) - [Actions](https://zshot-cli.com/reference/navigator/actions/) - **Navigators** - [Scope](https://zshot-cli.com/reference/navigator/scope/) - [Credentials](https://zshot-cli.com/reference/navigator/credentials/) - [Data and Files](https://zshot-cli.com/reference/navigator/data-and-files/) - [Security](https://zshot-cli.com/reference/security/) - [Server](https://zshot-cli.com/reference/server/) - [Shell completions](https://zshot-cli.com/reference/shell_completions/) - [Storage](https://zshot-cli.com/reference/storage/) - [Timeouts](https://zshot-cli.com/reference/timeouts/) - [Web Bot Auth](https://zshot-cli.com/reference/web_bot_auth/) - [Support](https://zshot-cli.com/support/) - [Changelog](https://zshot-cli.com/changelog/) Site index: https://zshot-cli.com/llms.txt