Wingman
Wingman is a Chrome side panel that summarizes the page you are reading and answers questions about it. It has three modes: Page answers from the page alone, Web also searches and reads the public web, and Workspace also looks things up, read only, in your research wiki, Jira, Slack, Gmail and Drive. Auto, the default, picks one of the three for each question, or Both: your workspace and the web together, where only search queries that pass a privacy check reach the web. The extension lives in the wingman repo; aimux browser is its back end.
Page text is untrusted input. A page must not be able to cause a write, a message, or data leaving to anywhere except your screen, the model provider and your own read-only lookups.
Wingman is a client of aimux’s remote API, like the iPhone app. The panel talks to a native messaging host (aimux browser host, started by Chrome while a panel is open), which only relays: it turns each panel request into a call on the API over Wingman’s own Unix socket. A Page question starts a session under the page profile, a Web question one under research, and a Workspace question one under work-readonly: those are the profiles behind Web and Workspace. The page profile is a Claude session with no tools, no MCP servers and no user settings. The work-readonly profile is a Claude Code process inside the aimux-work-readonly OpenShell sandbox, which can reach only the model provider and one read-only tool server on your Mac. The research profile is the same Claude Code process inside the aimux-research sandbox, with WebSearch and WebFetch only and no tool server. aimux remote serve creates each sandbox from its compiled profile on its first question and updates its policy when the profile or the pins change.
Every answer prompt (Page, Web and Workspace) tells the model it may include one Mermaid diagram of under 40 nodes. The panel shows a complete Mermaid block as a static image and keeps its source one click away; it enforces its own size and time limits, so the prompt only steers the model.
The mode control under the page title is a radio group: Auto, Page, Web, Workspace. Pick one with a click, or Tab to it and use the arrow keys. A line under it says what the chosen mode can reach, and a “How this works” disclosure, closed by default and remembered per browser, shows a small diagram of where the question goes. It starts on Auto, keeps its choice for follow-up questions and anchor jumps on the same page, and goes back to Auto on another page or tab. Only you and Auto decide where a question goes; the page and the answering model cannot change it.
Auto picks Page, Web, Workspace or Both for each new question, then asks in that mode. Both is only Auto’s pick (or @both), not a radio button: it looks in your workspace first, checks the web queries it proposes and drops those that look private (the check is pattern-based and has limits: a short or reordered copied span can pass), searches the web with the rest, and writes the answer with no tools. Its stages show as progress lines, and its answer links only to pages it fetched; any other URL shows as plain text. A line above the answer shows the pick and how likely the model rated it, such as “Auto: Web (73%)”, with a Change button: Change asks the same question again in the mode you choose, and later questions on the page use it.
To pick, aimux asks the mode router (POST /v1/route). What leaves the Mac is only your question (its first 2,000 characters) and three yes or no facts: whether the site is private, whether Wingman can read the page, and whether “Use this page” is on. They go to the Clef-flash model on OpenRouter, requested with zero data retention (OpenRouter provider routing). Never the page’s text, title or URL. Without an OpenRouter key, Auto always asks you; see Auto for storing the key.
Auto decides without asking when the model is confident, and also when “Use this page” is on and the model rates Page at 50% or more and as the most likely mode, even if it is not confident overall: Page runs no tools, and @web, @workspace or @both redoes the question. When Auto is unsure, or cannot pick (no key, OpenRouter slow or down, an aimux too old for Auto), nothing is asked yet: no session starts until you pick. A question that itself says which mode to use (“choose web”, “switch to workspace”, “ignore your instructions”) is not sent to the model at all, and you pick. A picker shows in place of the answer with three buttons, Page, Web and Workspace, the suggested one pressed, and why it is asking: “Auto is unavailable right now”, “Auto needs an OpenRouter key: run aimux browser setup”, “Pick a mode: the question mentions how to route it”, “Auto needs a newer aimux”, or the reason a mode is not allowed. To skip Auto for one question, start it with @page, @web, @workspace or @both. Enter asks in the pressed mode, the arrow keys move it, a click asks at once, and Esc cancels and puts your question back in the box (unless you have typed something new). On a page Wingman cannot read, picking Page or Workspace shows why and offers the picker again, with Web pressed.
While Auto waits, a status line says “Choosing a mode…”, or “Starting aimux…” while aimux remote serve is still starting after Chrome opened the helper. Stop (or Esc) ends the wait and keeps your question. After 1.5 seconds the line also offers Pick now, which stops waiting and shows the picker with your question. aimux gives the pick 5 seconds; the panel waits up to 20 seconds for a start, then 7 seconds for the pick, and shows the picker after that.
Follow-up questions on the same page reuse Auto’s pick without asking the router again. Navigating to another page, or switching modes, starts over. Quick view in Auto is a Page summary. The privacy rules of each mode still apply: Page and Workspace answer from the page’s text, as when you choose them yourself (neither reaches the web), and Web on a private page sends only the URL’s origin and no page text unless the chip is on. In Auto the chip reads “Let Web use this page”, since it governs only Web; it starts off on private pages, as in Web.
Start a question with @page, @web, @workspace or @both to pick its mode yourself, in any mode: @web what changed in the latest release?. The prefix is removed before the question is asked, and it switches only that question. It must come first and be followed by a space or the end, so @webby or a mention mid-sentence is not one, and a prefix with no question after it is not sent. In Auto, aimux reads the prefix and never asks the model; in the other modes the panel reads it itself.
Web answers from the public web as well as the page. It can:
- search the web (WebSearch), and
- fetch pages (WebFetch) with GET only, on port 443, from hosts under a reviewed list of top-level domains:
com, org, net, io, dev, ai, app, edu, gov, co, me, info, uk, de, eu. Each is a**.*.<tld>wildcard, which matches hosts with three or more labels such asen.wikipedia.org.
Each URL it fetches shows under the answer. It cannot reach your Mac, private or metadata addresses, other ports, other top-level domains, or any write method, and it has no tool server, so it holds none of your private data. The sandbox policy enforces this outside the agent.
The wildcards miss apex hosts, the two-label names such as github.com. A reviewed apex list fills part of that gap with exact entries, each limited to public addresses: github.com, gitlab.com, stripe.com, python.org, kubernetes.io, redhat.com, anthropic.com, openai.com, arxiv.org, npmjs.com, pypi.org, go.dev, endoflife.date. Any other apex host is refused, so an answer that needs one says it could not fetch it. The list goes away once OpenShell can allow any public host.
Use this page
Section titled “Use this page”In Web, the “Use this page” chip decides whether the page’s text goes along with the question. With the chip on, or on a public page, the full URL and the title go too. On a private page with the chip off, the sandbox sees only the URL’s origin (https://docs.google.com, no path, since a path can hold document ids) and no title, since a title can hold private text such as a mail subject. aimux still keeps the conversation under the full URL on your Mac, so each page (each Gmail message) has its own conversation and shows under “Earlier on this page”.
The chip is on by default, except on private pages, where it starts off. Private pages are:
- any URL that is not
httporhttps(file:,chrome:,data:,about:and the rest), any IP-address host, any dotless host such ashttp://intranet/,localhost, and hosts ending in.local,.internal,.localhost,.lanor.corp; - Google Workspace:
mail.google.com,docs.google.com,drive.google.com,calendar.google.com,chat.google.com,meet.google.com; - Slack and Atlassian:
app.slack.comand any*.slack.com,redhat.atlassian.netand any*.atlassian.net; - Red Hat internal hosts:
source.redhat.com,gitlab.cee.redhat.com, and any*.corp.redhat.com,*.int.redhat.comor*.cee.redhat.com; - Microsoft and Zoom:
outlook.office.com,outlook.office365.com,outlook.live.com, any*.sharepoint.com,teams.microsoft.comand any*.zoom.us; - any site you marked with “Always treat this site as private”, next to the chip in Web. It applies to that exact host, is kept in the browser profile’s extension storage, and pressing it again removes it. If Wingman cannot read those marks when the panel opens, it says so and treats every site as private until it can.
Turning the chip on on a private page shows “This page’s text can reach the web in Web mode.”, since private text plus web access is the one way a page’s text could leave. The chip resets with each new page. Web with the chip on and with it off are separate conversations on the same page, so turning it on or off starts a new one: text sent with the chip on never reaches a question asked with it off. On a page Wingman cannot read, the chip is disabled and Web still answers, without the page’s text.
Images
Section titled “Images”Paste or drop an image, such as a screenshot, into the question box and ask about it (not in Both, which takes no image). One image per question, PNG, JPEG, WebP or GIF; the panel scales it down to at most 1,568 pixels on the long edge, and aimux refuses one over 1.5 MiB of base64 or whose bytes are not the type it claims (400 image_invalid). Page, Web and Workspace take it: Page sends it to its Claude session with the question, and Web and Workspace pass it to Claude Code in their sandbox. Both takes none. The image never goes to the mode router, so Auto picks from the question text alone. Like page text, an image is untrusted data from your screen: the prompt says so, and text inside a screenshot cannot change what the mode may reach. The panel’s history shows the question, not the image; the image stays in the session’s transcript on your Mac.
Install
Section titled “Install”Build and load the extension from the wingman repo (npm ci && npm run build, then load extension/dist unpacked in chrome://extensions). Copy the extension id shown there, then:
aimux browser install --extension-id <id>This does four things:
- Installs the ACP adapter
@agentclientprotocol/claude-agent-acp@0.101.0under~/.aimux/wingman/adapterif it is missing. - Writes a wrapper script,
~/.aimux/wingman/host.sh, that runsaimux browser host. - Pins your extension id in
~/.aimux/wingman/extension-id. - Writes the native messaging manifest
com.zanetworker.wingman.jsoninto theNativeMessagingHostsfolder of both Chrome and Chrome Beta (under~/Library/Application Support/Google/).
The manifest allows only your extension id, and the host checks it again: Chrome passes the caller’s origin, and a host started by any other origin answers one error and exits. The host needs no running server. When nothing answers on the Wingman socket it starts aimux remote serve --local-only as a detached daemon (its own session, output in host.log) and waits for the socket. That local-only serve exits on its own after 30 minutes with no request from a panel and no running profile session, removing its socket. While it runs, a full aimux remote serve (for the phone and web) refuses to start and names its pid: stop it with kill <pid> and start the full serve, which Wingman then uses too. --chrome-dirs registers other Chrome user data dirs instead of the two defaults. Install refuses an aimux that runs from a temporary build (go run, /tmp); install aimux first, or pass --allow-temp-binary for tests. The wrapper points at the aimux on your PATH when it is the same binary, so it survives upgrades.
Set up the work lane
Section titled “Set up the work lane”The front door is aimux setup: it checks every concern and runs only the missing steps below (the tool registry, clients.yaml, the sandbox and tool runner images, the providers (the runner’s aimux-github only when an approved source needs it), and, with --extension-id <id>, the install above), asks before each on a terminal (--yes runs them without asking), offers changed tools for review on a terminal only, and ends with one line per concern. aimux doctor checks the same things read-only and names one fix per problem. Troubleshooting has both. The steps one by one:
Page questions work after install. For Workspace and Web, run once:
claude setup-tokensecurity add-generic-password -U -a "$USER" -s wingman-claude-oauth -waimux setupclaude setup-token makes a dedicated Claude subscription token. The second command stores it in the Keychain item wingman-claude-oauth (it prompts for the token). The sandbox never sees the token: an OpenShell provider injects it at the gateway.
aimux setup then runs these steps, skipping those already done (aimux browser setup runs the same steps without asking):
- Makes sure the tool-source registry
~/.config/aimux/tool-sources.yamlexists (mode 0600, folder 0700 when it creates it): it migrates an existing~/.aimux/wingman/readonly.jsononce, or else writes the defaults. An existing registry is never rewritten; one that does not load (a typo) stops setup with the file and key named. It warns on each source or set it skips and on each notes folder that is missing. - Lists each source’s live tools and reports the ones that need review, with the commands to review and approve them. How tools get approved depends on the command:
aimux setupon a terminal offers each tool that needs review and pins it only after you answer yes to its diff and yes to approving it; it never approves with--yesor--json, or without a terminal.aimux browser setupwrites no pins unless you pass--accept-pins(only it has that flag), which approves everything listed without review. - Writes
~/.config/aimux/clients.yaml(mode 0600) with the Wingman client’s profiles and limits if the file does not exist. An existing file is yours and is left alone. - Checks the OpenShell gateway (
-g local). - Builds the sandbox image
localhost/wingman-sandbox:2.1.319with Podman if it is missing, then the tool runner imagelocalhost/aimux-tools:2.103.3(the same image plus a pinnedgh) if that is missing. - Imports the
claude-code-oauthprovider profile and creates thewingman-claudeprovider from the Keychain token. If the Keychain item is missing, setup prints the two commands above and stops. This step reads the token with macOSsecurityonly, so on Linux setup fails here whilewingman-claudeis missing; create that provider withopenshell provider createfirst (see Troubleshooting). Then, if the optional provideraimux-githubis missing, it checks whether the platform’s secret store has the itemaimux-github(the Keychain on macOS, without reading it; the Secret Service on Linux). Only when it does, setup imports aimux’s provider profileaimux-githuband creates the provider from that token; otherwise, or on a platform with no supported store, it prints how to add a fine-grained, read-only GitHub token (on macOSsecurity add-generic-password -U -a "$USER" -s aimux-github -w, on Linuxsecret-tool store --label aimux-github service aimux-github) and carries on. This provider is for theghtools of the tool runner, which runsclitool calls such asgh. - Checks, by existence only (it never reads or prints the key), whether Auto mode has an OpenRouter key, and prints one line:
Auto mode: OpenRouter key found (Keychain aimux-openrouter)or(file ~/.config/aimux/keys/openrouter), whichever source would answer first. A key only in theOPENROUTER_API_KEYenvironment variable is reported as found in your shell environment, with the caveat that the serve Chrome starts does not inherit it (on macOS never; on Linux not when Chrome was started from the desktop), so store it in the Keychain, the Secret Service or the 0600 file instead. Linux key storage in the Secret Service is untested so far; the 0600 file is the tested option on Linux. Without a key it printsAuto mode: no OpenRouter key; Auto will always askand how to add one: on macOSsecurity add-generic-password -U -a "$USER" -s aimux-openrouter -w, on Linux a key file with mode 0600 (or theOPENROUTER_API_KEYvariable). A key file with any other mode is refused, and the line says so. Missing key is not an error: setup carries on. - Prints that
aimux remote servecreates the work sandboxaimux-work-readonlyon first use, and that Workspace needs the tool gateway worker: runaimux mcp proxy gateway installonce, and again after each aimux upgrade (remote serveand the worker are separate processes; an older worker cannot list a source afresh, so approving tools from a client fails until it is reinstalled). Setup creates no sandbox. Thewingman-worksandbox earlier builds made is no longer used; delete it withopenshell -g local sandbox delete wingman-work.
Steps 4 to 6 are aimux sandbox setup, which you can also run on its own. It prints Nothing to do: ... only when both images and both providers (wingman-claude and aimux-github) are there; without the aimux-github item it prints how to add it instead. aimux setup runs this step only when the Wingman image or provider is missing, so run aimux sandbox setup to build the runner image or create aimux-github on a machine that already has Wingman set up. Setup prints a line pointing at aimux sandbox status, which shows the image, the providers (wingman-claude and aimux-github), the gateway and whether each sandbox runs the policy compiled now.
Setup reads the sandbox files from ~/go/src/github.com/zanetworker/wingman/sandbox by default; use --sandbox-dir if the repo lives elsewhere.
Check the browser side
Section titled “Check the browser side”aimux browser statusRead-only: shows whether the native host manifest is in Chrome and in Chrome Beta, the pinned extension id and whether ~/.aimux/wingman/host.sh is there and executable. When the host is not usable it prints Next: aimux browser install --extension-id <id> on stderr. --json gives the same as a document (schema_version, hosts, extension_id, wrapper).
aimux browser uninstall removes the two manifests and host.sh (--all: the pinned extension id too) and keeps the adapter.
Tool sources
Section titled “Tool sources”~/.config/aimux/tool-sources.yaml lists the sources aimux may reach and the reviewed tool sets each one exposes. One file holds both, so an endpoint cannot be paired with the wrong review:
version: 1sources: jira: {type: mcp-http, url: "http://127.0.0.1:8001/mcp"} notes: {type: local-notes, root: /Users/me/notes}sets: jira:readonly: {source: jira, tools: [search_issues_jql, get_issue_details, get_comments, get_jira_issues]} notes:readonly: {source: notes, tools: [wiki_search, wiki_read]}- A source is
mcp-http(an MCP server over HTTP aturl),local-notes(Markdown files under the absolute folderroot, served in process),cli(a built-in command-line pack named bypack, such asgh) orhttp-openapi(an HTTPS API described by a local OpenAPI file:specis its absolute path,base_urlmust behttps://with no user info, query or fragment, and the optionalcredentialis a lowercase provider name (letters, digits and dashes, starting with a letter or digit)). A key that belongs to another type drops the source.clisources run in the tool runner sandboxaimux-tools:aimux tools approve(and the tool gateway worker) start it, whileaimux tools status,aimux tools diffandaimux doctoronly read it, listing aclisource’s tools whenaimux-toolsis already Ready and otherwise showing the source as down with “tool runner not started”.http-openapisources serve each GET operation with anoperationIdin their spec as a read-only tool<source>_<operationId>, listed from the local file and run as acurlGET inaimux-tools(HTTP sources); one withcredentialset serves no tools yet. Its name is the server name the gateway serves it under, so pins, endpoints (/mcp/<name>) and tool names (mcp__<name>__...) key on it. authorship(optional) says who writes what the source returns:self(content only you write, such as your own notes),internal(content written by people you trust, such as your team) oroutside(content anyone outside can write, such as email, Slack Connect or Jira comments from other companies). It defaults tooutsidewhen absent, and any other value drops that source with a message naming it. The built-in Slack, Jira and Google sources areoutside; a notes source added withaimux tools add notesor migrated fromreadonly.jsonisself.aimux tools statusshows it as the CLASS column andGET /v1/toolsasauthorshipon each set.- A set is
<name>:<kind>with itssourceand the exact tool names it may expose. A tool not listed is never exposed, even if the backend gains it later. - Unknown keys anywhere, bad YAML or a
versionother than 1 make the whole file fail with the file and key named. A malformed source or set, or a set naming an unknown source, only drops that entry: the rest keep working, andaimux remote servestill starts, with the dropped set unavailable.
The defaults are Slack at http://127.0.0.1:7381/mcp/slack (the MCP proxy), Jira at http://127.0.0.1:8001/mcp and Google Workspace at http://127.0.0.1:8000/mcp, with these sets:
| Set | Tools |
|---|---|
jira:readonly | search_issues_jql, get_issue_details, get_comments, get_jira_issues |
slack:readonly | search_messages, get_thread, get_thread_messages, get_channel_history, get_user_profile |
google:readonly | search_gmail_messages, get_gmail_message_content, get_gmail_thread_content, search_drive_files, get_doc_as_markdown, read_sheet_values, get_spreadsheet_info, get_drive_file_content, get_presentation, get_events, list_calendars |
There is no notes source by default: aimux tools add notes --folder <dir> adds a local-notes source notes and the set notes:readonly listing wiki_search and wiki_read (then aimux tools approve notes:readonly), aimux tools add cli gh adds the built-in gh pack and the set gh:readonly, aimux tools add http --name api --spec <abs path> --base-url https://... adds an OpenAPI source with a GET tool per operation (credentialed HTTP sources are not supported yet), both followed by aimux tools approve <name>:readonly and, if the runner image or provider is missing, aimux sandbox setup, and aimux tools remove notes takes a source out again; see Adding and removing sources. Those two tools serve only Markdown files under the root, resolve symlinks, and refuse anything outside the root or over the size cap. The built-in work-readonly profile asks for wiki:readonly; when the registry has no set of that name, it gets notes:readonly.
Migration from readonly.json. When the registry is absent and ~/.aimux/wingman/readonly.json exists, the first of aimux setup, aimux browser setup, aimux tools add or remove, or the start of aimux remote serve (which only logs a line) carries it over once: each HTTP backend becomes an mcp-http source, the wiki root a local-notes source named wiki with the set wiki:readonly (the server keeps its name, so its pins, tokens and tool names stay valid and nothing is re-pinned), and each other allowlist entry the set <backend>:readonly. An allowlist entry no backend serves (for example the wiki with an empty root) was never served: it is dropped with a warning, noted in the new file, and setup prints one line for it (Migrated tool config to ~/.config/aimux/tool-sources.yaml; set "wiki:readonly" dropped: ...). aimux tools status, the turns of a running remote serve and GET /v1/tools read readonly.json in memory without migrating it. The registry is written whole and checked before the old file is renamed readonly.json.migrated. A file that cannot be carried over cleanly (unknown keys, or HTTP headers, which the registry does not store) is an error, and nothing is written.
Pinned tools
Section titled “Pinned tools”Setup lists each read-only backend’s tools once and prints the set tools that need review (Tools need review (N): ...), then the two commands to run: aimux tools diff to see what changed, and aimux tools approve <set>... to pin them in ~/.aimux/tools/pins.json. A tool that is new, renamed, missing or changed since it was approved is hidden and refused until you approve it. The tool gateway worker notices a change on a backend that stays up when a turn’s lease arrives (it lists that turn’s servers afresh), at once when the backend announces it (notifications/tools/list_changed), and otherwise when the gateway’s cached listing of it expires (at most 60 seconds; a call before then still checks against that listing) or at its periodic relisting, so not necessarily on the next call: the call is refused, the tool drops out of the sandbox’s tool list, and aimux tools status and GET /v1/tools say changed. aimux browser setup --accept-pins approves everything the backends report at that moment, without review, and warns that it did.
A backend that is down keeps the pins it already had (setup and aimux tools status name it): once it is back, the gateway serves its unchanged tools again without another approval.
What a pin covers, how tool sets resolve and what pins do not prove are in Reviewed tool sets and pins.
aimux also lets the panel approve a changed tool; the panel needs a Wingman build that uses it (the extension is in its own repo). The host relays two requests: tools.diff (the set’s live definitions and pins, answered as a tools_diff event) and tools.approve (the set, the diff’s snapshot and each tool with the pin the panel showed, answered as tools_approved, or an error event with its code); cancelling a tools.approve ends its request, which closes the dialog on the Mac without approving. A diff too large for one message to the panel (Chrome’s 1 MiB) is not split: the panel gets an error with code diff_too_large, and you review that set with aimux tools diff on the Mac. aimux then shows a dialog on this Mac, “aimux: approve tools”, naming the set, each tool and what changed; nothing is approved until you click Approve there, within 60 seconds (see Approving tools from a client). A clients.yaml written by an earlier aimux setup has tools_approve: false for Wingman, and setup never rewrites an existing file: to turn approving on, set tools_approve: true and step_up_kinds: [mac-confirm] under wingman in ~/.config/aimux/clients.yaml and restart the serve Wingman uses: quitting Chrome does not stop it, so stop it with kill <pid> (pgrep -f 'aimux remote serve --local-only' finds it; for a full aimux remote serve, restart that) and the next panel starts it again with the new settings. Leave it false to keep approving on the Mac only.
Verify
Section titled “Verify”aimux sandbox verifyaimux browser verify still works: it runs the same checks and prints a note on stderr that the command moved.
Verify checks the sandbox work questions run in. It compiles work-readonly against your pins, uses the running tool gateway worker (or, when none runs, starts a short-lived read-only server on 127.0.0.1:7390), makes sure aimux-work-readonly exists with the compiled policy (creating it on the first run, which can take a few minutes), issues a test session token, and runs five checks inside the sandbox with node (the compiled policy allows only node and claude, not curl; each request times out after 10 seconds). It prints PASS or FAIL for each:
https://example.comis blocked.- The read-only server accepts the issued session token (on the first pinned server’s endpoint, such as
/mcp/google). - The read-only server rejects a request without a token.
- The host’s Slack proxy at
127.0.0.1:7381is blocked. - The host’s Slack proxy is blocked through the host gateway too (
host.containers.internal:7381).
It exits non-zero if any check fails. Verify needs the OpenShell gateway up (it stops with OpenShell gateway: ... when it is not) and approved tools (run aimux tools approve first). When the tool gateway worker runs, verify uses it (it prints Using the running tool gateway worker); otherwise it needs port 7390 free, and stops with 127.0.0.1:7390 is in use by a program that is not the tool gateway worker ... when another program holds it. remote serve no longer holds the port, so it can keep running.
Files and paths
Section titled “Files and paths”| Path | What |
|---|---|
~/.config/aimux/tool-sources.yaml | Tool sources and reviewed tool sets (see Tool sources); replaces ~/.aimux/wingman/readonly.json, kept as readonly.json.migrated after migration |
~/.aimux/tools/pins.json | The pinned tools (see Pinned tools) |
~/.config/aimux/clients.yaml | The Wingman client’s profiles, socket and limits (see Client scopes) |
~/.aimux/clients/wingman.sock | The socket the host talks to remote serve on (folder 0700, socket 0600) |
~/.aimux/wingman/host.sh | Wrapper Chrome starts |
~/.aimux/wingman/extension-id | The pinned extension id |
~/.aimux/wingman/adapter/ | The pinned ACP adapter |
~/.aimux/wingman/sessions/ | Working directory of the page sessions |
~/.claude/projects/-Users-<you>--aimux-wingman-sessions/ | The page session files (Claude Code files them by working directory) |
~/.aimux/sessions/profiles.json | Which profile, client and page each profile session belongs to |
~/.aimux/archive/ | Transcripts of work-readonly and research sessions, copied out of their sandboxes, and of Both sessions (each completed question and answer, in -Users-<you>--aimux-wingman-runs/, which search and session lists skip) |
~/.aimux/sandboxes/ | The compiled policy and policy digest of each profile sandbox (aimux-work-readonly.policy.yaml, .digest) |
~/.aimux/logs/remote-audit.log | One line per Wingman request (see below) |
~/Library/Logs/aimux/wingman/host.log | The host’s log and the output of the remote serve it started (owner-only) |
The page session files hold the text of the pages you asked about. aimux sessions, the session search index and the aimux MCP tools (search_sessions, list_sessions, get_session) skip every project directory under ~/.aimux/wingman/, so that untrusted text never reaches your session search or an agent reading it.
The audit log records, per request, the time, client: wingman, the action, the session, the profile and its digest, the URL’s host (not its path or query) and whether it succeeded, including refused requests. It does not record questions, answers, page text, titles or tokens. host.log records only that the host started, refused a caller or started remote serve, and what remote serve prints.
History
Section titled “History”The panel’s history is the list of Wingman’s sessions in the remote API: GET /v1/sessions?client=wingman&url=<page>. A page is its URL without a plain #anchor; a fragment holding a / is an app route and its own page, so each Gmail email (#inbox/<id>) and each route of a hash-routed app gets its own conversation. A page’s conversation is the turns of its page, research, work-readonly and research-with-work (Both) sessions, oldest first, and survives restarts like any other session. A Both session keeps its own transcript of each completed question and answer (a failed or stopped turn is not kept), so its turns stay readable in the history after aimux restarts, each with the links to the pages it fetched; the session itself cannot continue, and the next Both question on the page starts a new one. The panel shows the last 50 turns of a page (fewer when they would not fit one message from Chrome) and the 100 most recently asked pages. Deleting a page from the history hides its sessions from the lists (hidden on the session); the transcripts stay, and the page’s next question starts a new session. The old history.db is no longer used. Each browser profile (Chrome, Chrome Beta, or another Chrome profile) has its own conversations; sessions from before this keep showing in every browser.
The :7390 listener
Section titled “The :7390 listener”The read-only tool gateway listens on 127.0.0.1:7390. The sandbox reaches it as host.containers.internal:7390 through the Podman gateway.
- Owner: the tool gateway worker,
aimux mcp proxy gateway serve, run under launchd byaimux mcp proxy gateway install(jobcom.aimux.tool-gateway, logs in~/.aimux/logs/tool-gateway). It has its own pool of backends, separate from the proxy on:7381.aimux mcp proxy gateway statussays whether it runs;aimux doctorchecks it (gateway.worker). - Refresh: a work question rereads
tool-sources.yamland the pins when either changed, and its lease names the snapshot it was compiled at, so the worker loads the same one before serving it; the worker also rereads them once a minute and retries backends that were down. A new lease first lists that turn’s servers afresh, so a tool a backend changed since the last listing is not served to it; a backend that does not answer within 5 seconds does not hold the turn back (the lease is accepted, and each call is still checked against its pin). An approval (aimux tools approve) or a registry edit takes effect on the next work question without restarting anything. - Token: every request needs a bearer token. Each turn gets its own, put on the worker as a lease over
~/.aimux/gateway.sockand deleted when the turn ends; it reaches only the tools of that session’s profile. - No other surface: the listener serves the allowlisted, pinned tools only. The always-on proxy on
:7381is unchanged.
Any container on the Podman machine can reach 127.0.0.1:7390 the same way the sandbox does, which is why the token is required.
Safety model
Section titled “Safety model”- Only the mode you pick, or Auto’s pick, sends a question to Web or Workspace; the page and the answering model cannot switch it. To pick, Auto sends only the question and three yes or no facts to the mode router on OpenRouter (never the page’s text, title or URL), and the chosen mode then runs as if you had picked it, with the same limits.
- Web reaches only the reviewed public hosts above, GET only, and sends a private page’s text only after you turn “Use this page” on. WebSearch queries are run by the model provider (Anthropic’s API), outside the sandbox’s network policy.
- A pasted image is framed as untrusted data like page text, and the mode’s sandbox and tool limits are the same with or without it.
- The page lane has no tools, no MCP servers and no user settings, so a page has nothing to call.
- The work lane runs in a sandbox with default-deny egress: the model provider and
:7390, nothing else. - The read-only server exposes an allowlist of lookup tools; every other call is rejected and logged.
- Only the pinned version of a tool is served; a tool that changed is hidden until you pin it again.
- The notes tools cannot read outside their root.
- The sandbox policy and the gateway enforce this outside the agent; the agent’s own tool list only mirrors it (see Enforced and cooperative).
- Wingman is held to its client scope: it sees only its own sessions, cannot start a profile that runs on your Mac, and is limited to 2 running sessions and 20 turns a minute.
- Only the pinned extension can start the host.