Manage browser personas. Actions: create, get, update, list, delete.

Create: navvi_persona(action="create", name="mybot", description="GitHub admin", stealth="high") List: navvi_persona(action="list") Get: navvi_persona(action="get", name="mybot") Update: navvi_persona(action="update", name="mybot", purpose="new purpose", profile="Casual tone, uses emoji") Delete: navvi_persona(action="delete", name="mybot")

The profile field stores voice, phrases, and writing style notes for the persona. This gets injected into generate_brief() so sessions adopt the right tone.

Personas store config (locale, timezone, stealth, purpose) and track accounts + action history. Each persona maps to a persistent Docker volume (navvi-profile-). Read persona state via resource: persona:///state

Manage accounts linked to a persona. Actions: add, list, update, delete.

Add: navvi_account(action="add", persona="mybot", service="github", email="bot@x.com", creds_ref="gopass://navvi/mybot/github") List: navvi_account(action="list", persona="mybot") Update: navvi_account(action="update", account_id=1, status="blocked", notes="captcha") Delete: navvi_account(action="delete", account_id=1)

Accounts track which services a persona has registered on, with credential references (gopass://) and status.

Curated lifetime timeline for a persona — milestones with evidence. Actions: add, list, export, delete.

Add: navvi_milestone(action="add", persona="chet", event="Signed up for Reddit", detail="Username: chestertownwilliams. Subscribed to r/selfhosted.", url="https://reddit.com/user/chestertownwilliams", tags="first,reddit,signup", screenshot=true) Import (retroactive): navvi_milestone(action="add", persona="chet", event="Created Outlook account", detail="Email: chester.town.williams@outlook.com", ts="2026-03-27T11:00:00", screenshot_file="/path/to/old-screenshot.png", source="import") List: navvi_milestone(action="list", persona="chet") or navvi_milestone(action="list", persona="chet", tag="reddit", limit=10) Export: navvi_milestone(action="export", persona="chet") — generates full markdown timeline Brief: navvi_milestone(action="brief", persona="chet") — generates persona brief (who am I, my accounts, my email, my history, my writing style). READ THIS BEFORE ACTING AS A PERSONA. Delete: navvi_milestone(action="delete", milestone_id=3)

Tags: comma-separated string. Use 'first' tag for firsts (first post, first signup, etc.). Screenshot: if true, captures current browser screen and attaches it. For retroactive imports, use screenshot_file to attach an existing image. Detail: include FULL content — exact post text, comment body, form values. This builds the persona's voice and style for consistency.

Persistent knowledge store for a persona — what they know. Actions: add, list, search, update, remove, digest, save_digest.

Add: navvi_context(action="add", persona="chet", summary="InboxGuard: email deliverability scanner with SPF/DMARC checks", source="https://inboxguard.me/", tags="competitor,inbox-angel") List: navvi_context(action="list", persona="chet") or navvi_context(action="list", persona="chet", tags="competitor") Search: navvi_context(action="search", persona="chet", query="email deliverability", tags="competitor") Update: navvi_context(action="update", context_id=3, summary="Updated finding", tags="competitor,updated") Remove: navvi_context(action="remove", context_id=3) — soft-deletes, included in next digest Digest: navvi_context(action="digest", persona="chet") — returns current summary + undigested entries for LLM synthesis Save digest: navvi_context(action="save_digest", persona="chet", summary="Synthesized knowledge summary...") — stores digest, marks entries processed

Milestones = what a persona did. Context = what a persona knows.

Start a Navvi browser container (Firefox + Xvfb + xdotool). Local=Docker, Remote=Codespace. Workflow: navvi_open(url) -> navvi_find(selector) -> navvi_click/navvi_fill -> navvi_screenshot to verify. All input is OS-level (isTrusted:true). If you hit a CAPTCHA you cannot solve (Arkose/FunCaptcha, image puzzles, reCAPTCHA), call navvi_vnc and send the user the noVNC URL so they can solve it manually.

Stop a Navvi container. Stops all if no persona specified. Firefox profile is preserved in the Docker volume.

Show current Navvi state -- running containers, API health, active persona.

List available Codespaces for Navvi (remote mode).

Navigate to a URL in the active browser. After navigating, use navvi_find to locate elements on the page, then navvi_click/navvi_fill to interact.

Click at (x, y) screen coordinates using OS-level xdotool input (isTrusted: true). IMPORTANT: Use navvi_find to get coordinates -- it returns screen-ready (x, y) values. Do NOT use raw JS getBoundingClientRect() -- those are viewport coords that miss the browser chrome offset.

Click at (x, y) to focus an input field, then type text using OS-level xdotool. Selects existing text before typing to replace any current value.

Uses triple-click to select all text in the field (works in all input contexts), then types the new value which replaces the selection.

Press a keyboard key (Enter, Tab, Escape, Backspace, ArrowDown, etc.). Sends to currently focused element.

Drag from (x1,y1) to (x2,y2) with interpolated mouse moves. Uses OS-level input -- works on CAPTCHAs and canvases. Get coordinates from navvi_find.

Press and hold at (x, y) for duration_ms milliseconds. Use for press-and-hold CAPTCHAs. Get coordinates from navvi_find.

Press mouse button at (x, y). Pair with navvi_mouseup for manual hold control. For simple press-and-hold, use navvi_hold instead.

Release mouse button at (x, y). Pair with navvi_mousedown.

Move mouse to (x, y) without clicking. Useful for hover effects.

Scroll the page in a given direction (up, down, left, right).

Take a screenshot of the virtual display. Returns file path to a PNG image -- use Read tool to view it. Use for VISUAL VERIFICATION only (confirming what happened). To get clickable coordinates, use navvi_find instead -- screenshot pixel positions include browser chrome and are not reliable for targeting elements.

Get the current page URL.

Get the noVNC URL for live browser view. Share with the user when human intervention is needed: visual CAPTCHAs that require image recognition, OAuth consent screens, or 2FA code entry. The user opens this URL in their real browser to interact directly.

Find element(s) by CSS selector and return screen-ready (x, y) coordinates. THIS IS THE PRIMARY WAY TO GET COORDINATES -- use before navvi_click, navvi_fill, navvi_drag, navvi_mousedown. Automatically corrects for browser chrome offset. Workflow: navvi_find -> get (x, y) -> navvi_click/navvi_fill at those coords -> navvi_screenshot to verify. For dropdowns: navvi_find the button -> navvi_click to open -> navvi_find the options (selector="[role=option]", all=true) -> navvi_click the desired option.

Manage credentials stored in gopass inside the container. Five actions:

• "list": show available entries (no secrets)

• "get": retrieve a non-secret field (username, url, email — refuses password)

• "generate": create a new credential with a random password that NEVER leaves the container. Requires entry + username. Optional length (default 24). Use this for signups.

• "import": bulk-import credentials from a JSON file on the host. Requires file_path pointing to a JSON array of {entry, username, password} objects. File is read and deleted after import.

• "autofill": fill a login form from gopass — password goes gopass → xdotool → browser, NEVER in this response.

Manage browser tabs within a persona. Four actions:

• "list": list all open tabs with handle, url, and title

• "new": open a new tab (optionally navigate to url). Switches to the new tab.

• "switch": switch to a tab by handle

• "close": close a tab by handle (cannot close the last tab)

Start recording the browser via screenshot polling. Captures frames in background, assembles to MP4 on stop.

Stop recording and assemble frames into MP4. Optionally trims dead time between actions.

Convert a recorded video to an optimized GIF (1600px wide, 8fps, palette-optimized).

Quick reference for atomic browser tools (navvi_click, navvi_find, navvi_fill, etc.).

Atomic tools are always available. Call this for a summary of tools and workflow.

Example: navvi_atomic() → lists all atomic tools with parameters

Manage flow recipes — reusable browser workflows that improve over time.

Actions: list — list all flows, or filter by domain navvi_flow(action="list") navvi_flow(action="list", domain="outlook.live.com")

show — show full detail for a specific flow navvi_flow(action="show", flow="outlook.live.com/read-email")

save — store a verified flow recipe (call after navvi_browse prompts you) navvi_flow(action="save", flow="outlook.live.com/read-email", description="Read emails from inbox", steps='[{"action":"navigate","url":"https://outlook.live.com"}, ...]', caveats='["Login required first"]', refs='["outlook.live.com/login"]')

delete — remove a flow recipe navvi_flow(action="delete", flow="outlook.live.com/read-email")

The flow parameter uses the format "domain/action-name". Steps, caveats, and refs are JSON strings (arrays).

Flows are automatically loaded by navvi_browse when it visits a matching domain. High-confidence flows execute via fast path (no screenshots); low-confidence flows serve as guidance while still using visual analysis.

PRIMARY BROWSING TOOL — use this for ANY web interaction instead of manually calling navvi_open, navvi_find, navvi_click, navvi_fill. Give a natural language instruction and optional URL; it handles navigation, element finding, clicking, typing, and screenshots internally.

Examples:

• navvi_browse(instruction="search for 'Python FastMCP'", url="https://duckduckgo.com")

• navvi_browse(instruction="click the first link in the results")

• navvi_browse(instruction="accept cookie banners and screenshot the clean page", url="https://example.com")

• navvi_browse(instruction="read the inbox and list unread emails", url="https://app.tuta.com")

Handles cookie banners, login detection, CAPTCHAs (escalates to VNC), and multi-step flows automatically. Returns screenshots and a step-by-step log.

If a stored flow recipe exists for the target domain, it will be used to guide or fast-track execution depending on confidence level. After completion, you'll be prompted to save new flows for reuse.

Only fall back to atomic tools (navvi_open, navvi_find, navvi_click) if this tool explicitly asks for guidance.

Log into a service using stored credentials — use this instead of manually navigating to a login page and calling navvi_creds autofill.

Give it a service name (e.g. "tuta.com", "github.com") and it reads gopass credentials, navigates to the login page, fills the form, submits, and verifies login success. Handles 2FA by providing a VNC URL for human intervention.

Example: navvi_login(service="tuta.com", persona="default")

Requires: an account registered via navvi_account with a creds_ref pointing to a gopass entry.