AI Agent

Note

Available on all editions. Bring your own provider API key.

Experimental

The AI Agent is an experimental feature. Its actions and options may change.

Overview

The AI Agent is a built-in assistant that turns plain-language requests into shell commands, scripts, and other artifacts you can review and apply. You bring your own provider API key — Gridmux doesn’t ship or proxy a key, and it never sends anything to a provider until you opt in.

It’s designed around review, not autopilot: the agent proposes output, and you decide what to run, save, or apply.

Opening the panel

The agent lives in a floating panel you can drag and resize. Toggle it with Ctrl+Alt+A.

Bring your own key

The agent supports four providers:

• Anthropic
• OpenAI
• Azure OpenAI
• a mock provider for offline development / testing (canned responses)

Your API keys are stored in your operating system’s keychain (secure credential store) and are handled only in Gridmux’s main process — they never pass through the renderer. A request goes directly to the provider you’ve selected; nothing is routed through a Gridmux server.

Adding your key

Open Settings → AI Agent. There you can:

• pick your provider and fill in its details;
• Test, Save, or Delete the key;
• choose the model from a dropdown (Anthropic offers a built-in list; OpenAI lists your available chat models; Azure is deployment-driven).

First use: consent

The first time you make a request, the agent shows a consent dialog naming the provider and endpoint your prompt will be sent to. You must accept it before any request goes out.

What it can do

Actions are grouped into buckets, shown as tabs at the top of the panel:

Terminal

• Generate command — natural language → a single shell command.
• Explain error — paste an error → a plain-English explanation.
• Convert shell — translate a command from one shell to another (e.g. PowerShell → Bash).
• Generate alias — describe a routine → a proposed alias you can save.
• Generate script — describe a task → a multi-line shell script.

Templates

• Generate template — describe a workspace → a workspace template.
• Generate layout — describe a pane arrangement → a workspace layout.

Audit

• Summarize audit — summarize recent file operations.
• Interpret signal — interpret recent in-app signals.

Workflows

• Generate notes — draft Markdown notes (appended to your Team Notes).
• Generate workflow — produce a numbered, step-by-step procedure.

Responses stream in as they’re generated; the Generate button becomes a Cancel button while a request is in flight.

Reviewing output & safety

Output is never executed automatically. Depending on the action, you choose what to do with it:

• Generated commands are written to the active terminal only after you confirm in a dialog — a deliberate guard against prompt-injection.
• Generated scripts go to your clipboard (direct insertion is disabled for multi-line scripts).
• Other outputs offer the matching action: Save as Alias, Apply (template / layout), Save Notes, or Copy.

Privacy & context controls

By default, the agent sends only your prompt. You can optionally let it include context about your session to get better answers. There are seven context buckets — shell, cwd, aliases, project, template, signals, audit — and every one is off by default.

Before any context leaves your machine, a sanitizer redacts secrets, file paths, and email addresses. If sanitizing fails, the entire request is aborted — nothing unsanitized is ever sent. The Privacy section in the panel shows a live preview of the exact JSON block that will be included, so you can see what’s shared before you send it.

One always-shared detail

For Generate command and Generate script, the active shell’s type (e.g. cmd, bash) is always included — it’s needed to produce output valid for your shell, and it’s neither a path nor a secret. This is disclosed permanently in the Privacy section so the preview is never the only source of truth.

History

The agent can keep a local history of your requests in a file on your machine (ai-history.json). History is off by default — enable it in Settings → AI Agent. It is local-only (never synced), capped to a maximum number of entries (default 200, oldest dropped first), and you can clear it at any time.

Token usage warning

The agent tracks the tokens used in your session and warns you once you cross a configurable threshold. You can raise the threshold in settings, or choose Continue anyway to proceed for the current session.

Notes & limitations

• The AI Agent itself is free on every edition — you only pay your chosen provider for usage.
• It is experimental; actions and options may change.
• The mock provider returns canned responses and needs no key — useful for trying the panel without calling a real API.
• Some outputs hand off to other features: applying a generated template uses the Templates feature, which requires an Extended Subscription. (Generating a layout instead creates a new workspace and is only subject to your workspace limit.)