15 AI Assistant

WxTerm ships with a built-in AI assistant: a chat panel beside your terminal session where you issue instructions in natural language and the AI executes commands, reads and writes files, reads the screen, and reports back — all on the machine connected to the current tab (SSH / Telnet / serial / local terminal). The AI never touches anything outside the bound connection instance.

Typical scenarios:

Scenario	Example prompt
Run commands from a prompt	“Check disk usage and find the largest log files” → the AI runs df -h, du on the remote host and reports findings
Generate/modify remote files	“Change the service port from 8080 to 9090” → the AI reads the remote file, applies a precise replacement, writes it back and shows the diff
Troubleshooting	“Why can’t I reach port 3306?” → the AI runs ss -tlnp remotely, inspects logs, and gives an analysis
Device CLI operation	On firewalls/switches over Telnet/serial: the AI reads the screen to identify the environment, then sends commands and waits for the prompt
Web research	The AI can search the web, fetch pages, and look up library docs, combining results with remote execution

The AI assistant requires you to configure your own model service (compatible with the OpenAI / Anthropic / Responses API protocols — any provider such as DeepSeek, Qwen, GLM, or a local Ollama works). See 15.3. The AI assistant is available on all plans.

15.1 Opening the AI Panel

Each terminal tab group has a vertical tool strip on its right side (the group side strip). Click the [AI] button to open (or close) that group’s AI drawer panel:

• [AI] on the group’s right strip: toggles the AI panel for the current tab group.
• Shortcut Ctrl+Shift+A: toggles the AI panel of the focused tab group.
• ✕ in the drawer’s top-right corner: closes the panel.

While the AI panel is open, the group side strip shows an extra column of function buttons below the [AI] button (names appear on hover): [+] New chat, History, Authorization Rules, MCP Servers, Skills, Model Settings — all dialogs mentioned in this chapter open from there.

The AI panel appears as a drawer on the right side of the terminal area; its width is drag-adjustable and remembered. The panel follows the currently active tab of the group — switching tabs switches the AI conversation context (each tab has its own AI session).

15.2 Panel Layout

┌──────────────────────────────────────┐
│ 🤖 AI Assistant                  ✕  │ ← title bar (✕ collapses the drawer)
├──────────────────────────────────────┤
│ [chat1][chat2][chat3…]           [+] │ ← session tab bar
├──────────────────────────────────────┤
│                                      │
│  Conversation:                       │
│   [user message]                     │
│   [AI reply (Markdown rendered)]     │
│   [tool card: $ df -h  ✓ done]       │
│   [approval card: confirm?]          │
│   [Thinking...]                      │
│                                      │
├──────────────────────────────────────┤
│ Type a message… (Enter to send) [➤] │ ← input area ([➤] becomes [⏹] while generating)
├──────────────────────────────────────┤
│ ●Smart  12.3k tokens    glm-5.3  ▴  │ ← bottom status row (mode/model selectors)
└──────────────────────────────────────┘

• Title bar: AI Assistant title + ✕ to collapse the drawer.
• Session tab bar: multiple sessions coexist as tabs — click to switch, tab ✕ to close; [+] on the right starts a new chat.
• Conversation: user messages, AI replies (Markdown rendered, copyable code blocks), tool-call cards (expandable to full command and output), approval cards, and failure/retry cards.
• Input area: multi-line input box; Enter sends, Shift+Enter inserts a newline; height adapts to content (up to 3 lines). The button on the right sends the message and turns into a stop button while generating.
• Bottom status row: on the left the mode badge (colored dot + mode name; click to open the mode dropdown); token usage in the middle; the model name on the right (click to open a two-level dropdown — pick the API provider first, then a model under it).
• Function buttons: the entries for new chat / history / authorization rules / MCP servers / skills / model settings live on the group side strip (below the [AI] button, see 15.1).

15.3 Model Configuration

Configure a model service before first use. Open the model settings dialog via the Model Settings button on the group side strip (shown while the AI panel is open, see 15.1; or follow the prompt when sending a message):

Adding an API provider

The left side lists API providers. Click “Add API” to create one:

Field	Description
Name	Display name (e.g. “DeepSeek”)
API URL	Service address with version prefix (e.g. https://api.deepseek.com/v1; Ollama: http://127.0.0.1:11434/v1)
API type	openai (Chat Completions) / anthropic (Messages) / responses (OpenAI Responses API)
API Key	Provider key; leave empty for local services (Ollama)
Use proxy	Whether this API goes through the global proxy

Managing models

The right side lists the models of the selected API:

• Pull model list: fetches available models from the provider online (auto-fills context/output limits).
• Add model: add a model manually with model ID, max context, and max output.
• Enabled / Default: only enabled models appear in the bottom status row’s model dropdown; “Default” is the initial model for new sessions.
• Test connection: verifies the API URL, key, and protocol.

Proxy settings

The “Proxy” tab configures the global proxy (HTTP/SOCKS) used by APIs with “Use proxy” enabled:

Field	Description
Proxy type	HTTP / SOCKS
Server / Port	Proxy address
Authentication required	Check to enter username/password

Model configuration is stored in the configuration directory at ai/provider.json (permission 0600, contains keys).

Configuration directory location (see 01 Getting Started → Configuration File Locations):

• Linux/BSD: ~/.wxterm/
• macOS: ~/Library/Application Support/wxterm/
• Windows: %APPDATA%\wxterm\

This chapter refers to it as <config dir>.

15.4 Conversation and Permission Modes

Sending and streaming

• Type a message and press Enter; AI replies stream in token by token. “Thinking…” process display is supported for reasoning models.
• While generating, click “Stop” or press Ctrl+Shift+S to interrupt.
• Failed requests retry automatically: up to 10 times at 3-second intervals; the failure card stays in place and offers a manual “Retry” button.
• Suggested prompts at the bottom of the panel (e.g. “Check disk usage and suggest cleanup”) send immediately on click.

Permission modes

The mode badge in the bottom status row (click to open its dropdown) offers three levels (terminal side):

Mode	Name	Behavior
ask	Ask	Default. Every command and file write pops an approval card and only runs after you confirm
shell	Smart	Read-only commands (ls, cat, df, …) run automatically; writes and dangerous commands still require approval
yolo	Full	Every action runs without confirmation (a confirmation prompt appears when switching)

Approval cards offer three buttons: Deny / Allow / Always Allow. “Always Allow” adds the command (by atomic command name) to the global command whitelist, exempting it from approval afterwards — it takes precedence over the mode setting. The whitelist is managed in the “Authorization Rules” dialog (allow/block lists with * wildcards).

15.5 Tool Capabilities

The AI works through tools inside the bound connection instance. Tools are assembled automatically according to the current tab’s protocol:

Tool	Protocols	Description
Execute command (remote_exec)	all	Runs a shell command on the connected machine and captures output; the command is injected into the live terminal pipe — you see it in the terminal as it runs
Read screen (read_screen)	all	Reads the current terminal screen as text to identify the environment (shell prompt / device CLI / menu)
Read file (remote_read)	SSH	Reads a remote text file via SFTP (numbered, paged)
Write file (remote_write)	SSH	Writes a remote file via SFTP; the result includes a unified diff
Edit file (remote_edit)	SSH	Precise string replacement via SFTP (must read the file first); the result includes a diff
List files (remote_list)	SSH	Lists a remote directory via SFTP
Send keys (send_keys)	Telnet/serial	Sends raw text/keys to the device CLI (commands, paging space, Y/N answers, Ctrl-C)
Wait for (wait_for)	Telnet/serial	Polls the screen until a pattern appears (the completion signal for device commands)
Web search (web_search)	all	Built-in web search (DuckDuckGo, no API key needed)
Web fetch (web_fetch)	all	Fetches a web page and extracts the text
Library docs (context7)	all	Built-in Context7: resolve library names and query up-to-date library documentation
Task list (todo_write)	all	Maintains the session task list (plan progress shown at the top of the panel)
Load skill (skill)	all	Loads a matching user skill (see 15.8)

Safety constraints:

• Dangerous commands always require approval: dangerous segments such as rm -rf, mkfs, dd, shutdown require user confirmation in every mode (including yolo).
• Device Y/N confirmations are never auto-answered: the AI must pause and ask you.
• Graceful pause on user keystrokes: if you type in the terminal while the AI is working, it pauses (with a first-time explanation) to avoid fighting over the pipe.
• Command output is budget-truncated (tail kept, 30KB); timed-out commands are interrupted with Ctrl-C and partial output is returned.

15.6 Session History

• History button (group side strip): opens the history dialog listing the current connection’s and all past AI sessions (title, time, message count). Click to restore and continue; the delete button deletes a session (deletion is the only cleanup — the app never auto-deletes).
• Session tabs: multiple sessions can be open as tabs at the top of the panel; click to switch, ✕ to close.
• Export: exports the current session to a Markdown file.
• History data is stored in <config dir>/ai/task/task_{id}.dat (SQLite), indexed by <config dir>/ai/wxterm.dat.

15.7 Context Management

• The status line shows token usage for the current turn.
• As the context approaches the model limit it is compacted automatically: a lightweight micro-compaction first (recent turns kept), then early turns are summarized into a structured digest — the task continues seamlessly (the panel shows “Context compacted”).

15.8 Extensions: MCP Servers and Skills

MCP servers

MCP (Model Context Protocol) connects external tool servers. Open the config dialog via the “MCP Servers” button on the group side strip:

• Built-in servers (enabled by default, zero config): web search (web_search / web_fetch) and Context7 library docs.
• External servers: add command-line-launched MCP servers (command, arguments, environment variables); they connect automatically and their tools are listed. You can test connections and restart processes. Each server has an approval policy: “follow session mode” or “ask every time”.
• Configuration is stored in <config dir>/mcp.json.

Skills

Skills are reusable instruction packs placed at <config dir>/ai/skills/<name>/SKILL.md (Markdown with a frontmatter description). The “Skills” button (group side strip) opens a dialog that lists discovered skills, rescans, and opens the skills directory. When a task matches a skill, the AI loads its instructions via the skill tool.

15.9 Data Storage and Privacy

Data	Location	Notes
Model service config (incl. keys)	<config dir>/ai/provider.json	Permission 0600, readable only by the local user
Session index	<config dir>/ai/wxterm.dat	Session list (SQLite)
Session content	<config dir>/ai/task/task_{id}.dat	Full conversation and approval audit trail; deletable only by the user
MCP config	<config dir>/mcp.json	External server list
Skills	<config dir>/ai/skills/	User-level skills directory

• Conversation content is sent only to the model provider you configured, and only when a request is made; command approval records stay local.
• AI sessions survive disconnects and can be continued after reconnecting.