DeepSeek-first agent sessions

Run agent work inside WispTerm

Open a native AI Agent tab that can inspect terminal context, run local PowerShell or cmd tools, work with WSL and SSH sessions, load local skills, and keep approvals in the terminal UI.

Configure DeepSeek Agent tools

wispterm — AI Agent

agent

pwsh

ssh: lab

You Inspect this repo and find the test command.
WispTerm tool request
terminal_list visible surfaces: pwsh, ssh: lab
terminal_select surface=pwsh
powershell_exec rg -n "test" README.md build.zig
approved

Agent Use zig build test. I found it in build.zig.

AI that understands the terminal

WispTerm keeps agent work close to the shell state you already have open. It does not need a separate browser workspace to understand tabs, split panes, local commands, WSL, and SSH sessions.

DeepSeek V4 profiles

The default profile targets OpenAI-compatible Chat Completions at https://api.deepseek.com with deepseek-v4-pro. Use deepseek-v4-flash when you want a faster, lighter profile.

Switch models in-session

Use /model, /model <name>, the /模型 alias, or the clickable model label to move the current chat or Copilot session to another saved profile. WispTerm summarizes prior context for the new model without changing your global default profile.

Terminal-aware tools

Agent tools can list visible terminal surfaces, select the intended tab or panel, run local commands, and type into active REPL, WSL, or SSH contexts.

Approval-based execution

Tool requests appear in WispTerm before execution when permission is set to ask. Use auto for trusted unattended work that should still stop on protected paths and dangerous commands; use full only when you want the agent to run without those guard prompts.

Saved conversations

Agent sessions are persisted so you can reopen work from the command center with Copilot History. The picker groups saved AI Chat and Copilot sidebar conversations by date, searches titles and models, and lets you filter the source with Tab.

Markdown exports

Run Export AI Chat Markdown to save the full transcript, or Export AI Chat Markdown Clean to save only user prompts and the final answer without thinking or tool details. WispTerm opens a save dialog and copies the saved path.

Configure DeepSeek V4

Open the session launcher with CtrlShiftT, choose AI Agent, and fill the AI profile. If no profile exists, WispTerm opens this form before the first agent launch.

Recommended agent profile

Profile name	`DeepSeek`
Base URL	`https://api.deepseek.com`
API key	Your DeepSeek key, or leave empty when `DEEPSEEK_API_KEY` is set
Model	`deepseek-v4-pro`
Protocol	`chat_completions`; use `responses` for OpenAI Responses API providers
Thinking	`enabled`
Effort	`max` for coding-heavy agent work; `high` is WispTerm's built-in default
Stream	`false`
Agent	`true`

Environment key

When the profile base URL points to DeepSeek and the profile key is empty, WispTerm reads DEEPSEEK_API_KEY from the process environment.

# Windows (PowerShell)
$env:DEEPSEEK_API_KEY = "sk-your-deepseek-api-key"
# Persist for future sessions:
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY","sk-your-deepseek-api-key","User")

# macOS / Linux (shell)
export DEEPSEEK_API_KEY="sk-your-deepseek-api-key"
# Persist: add the export line to ~/.zshrc or ~/.bashrc

DeepSeek V4 models expose a 1M context length and support thinking mode through thinking plus reasoning_effort. Chat Completions remains the default protocol; Responses profiles use instructions, input, and Responses-style function tools.

Agent tools and boundaries

The agent can help with local work without losing track of which terminal it is controlling. WispTerm requires an explicit terminal selection before write tools target another surface.

Local commands

Shell commands run as background child processes where possible, so tool execution does not flash a separate console window. The agent uses powershell_exec on Windows and shell_exec on macOS/Linux.

WSL and SSH routing

The agent can inspect visible terminal surfaces, save WispTerm SSH profiles with ssh_profile_save, and route writes to the selected WSL or SSH session rather than guessing from focus alone.

Terminal selection

Tool calls use surface IDs from terminal_list. Before writing, the agent calls terminal_select to make the target explicit.

Permission mode

Keep ai-agent-permission = ask for normal use. Use auto when ordinary tools may run unattended but private-file and destructive-command guards should remain active. Use full only when you trust both the task and the opened workspace completely.

# AI Chat agent tools
ai-agent-enabled            = true
ai-agent-permission         = ask       # ask | auto | full
ai-agent-command-timeout-ms = 60000
ai-agent-output-limit       = 16384

Skills and fast paths

Skills let you keep reusable instructions next to the terminal. They are loaded into the next request and saved into chat history as replayable context.

Skill locations

WispTerm discovers SKILL.md files under the platform config directory (%APPDATA%\wispterm on Windows, ~/Library/Application Support/wispterm on macOS) in skills/ and plugins/skills/, plus the same two sub-paths next to the executable and in the current working directory.

Skill Center also manages Agent tools. Imported executable tools are stored under the WispTerm config directory with a canonical SKILL.md and keep their own enable state. First-party WispTerm tools, including web, terminal, file, docs, and memory tools, appear in the same inventory; their state is stored separately in agent_tools.json. Turning a built-in tool off hides it from newly built AI request tool lists and blocks stale or hallucinated calls at runtime.

Load a skill

Use $skill-name your request in the AI Agent tab to load that skill for the next request without changing global configuration.

Third-party tools

WispTerm also works with external utilities. For example, Claude ChatMap is a local Claude Code history dashboard that groups chats by folder and can resume a selected chat in a WispTerm tab through wisptermctl. Community tools are not bundled with WispTerm.

Slash commands

/commands lists the current command set. Common commands include /model for profile switching, /cwd for the conversation working directory, /permission for agent approval mode, /export for Markdown, /distill for reusable skills, and /remember / /memory / /forget for long-term memory.

/loop repeats a prompt on an interval and /watch schedules daily or one-shot prompts. /clear, /rewind, /resume, /skills, /reload-skills, and /reload-commands cover conversation lifecycle and local command refresh.

Lookup shortcuts

Type $websearch <query>, $webread <url | file path>, or $pubmed <query> to run a read-only lookup from the composer without starting a normal AI turn. $websearch uses the configured jina-api-key; $webread can read anonymously; $pubmed uses NCBI PubMed anonymously.

Command center paths

Run New Agent from CtrlShiftP, reopen saved sessions with Copilot History, or export Markdown records from the active AI tab.

Feishu/Lark direct control

Use a Feishu enterprise self-built app to send messages into WispTerm's Copilot/Agent flow. The desktop app opens a long connection at startup, so save the credentials first, then restart WispTerm.

Step 1: Create an enterprise self-built app

Open https://open.feishu.cn/app and create an enterprise self-built app, for example WispTerm-Lab. For international Lark tenants, use https://open.larksuite.com.

Feishu enterprise self-built app creation form — Create an enterprise self-built app, for example `WispTerm-Lab`.

Step 2: Add the Robot capability

In Add app capabilities, choose Robot. This is the capability WispTerm uses for chat messages, cards, and user interaction.

Feishu Add app capabilities page with Robot selected — Add the **Robot** capability.

Step 3: Import permissions

In Permission management, open Bulk import/export permissions, switch to Import, and paste this JSON:

{
  "scopes": {
    "tenant": [
      "application:application:self_manage",
      "application:bot.basic_info:read",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "docs:document.comment:create",
      "docs:document.comment:delete",
      "docs:document.comment:read",
      "docs:document.comment:update",
      "docs:document.comment:write_only",
      "docx:document.block:convert",
      "docx:document:readonly",
      "docx:document:write_only",
      "drive:drive.metadata:readonly",
      "im:chat.members:bot_access",
      "im:chat:create",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.pins:read",
      "im:message.pins:write_only",
      "im:message.reactions:read",
      "im:message.reactions:write_only",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message:send_multi_users",
      "im:message:send_sys_msg",
      "im:message:update",
      "im:resource",
      "wiki:node:read"
    ],
    "user": [
      "offline_access"
    ]
  }
}

Feishu bulk permission import dialog with JSON editor — Bulk-import the permission JSON.

Step 4: Configure long-connection events

Open Events & Callbacks → Event configuration and select Long connection. Then add im.message.receive_v1. A connection-failed status is normal until WispTerm has the app credentials.

Feishu event configuration page with long connection selected — Use long connection mode; no public callback URL is required.

Feishu add event dialog showing im.message.receive_v1 — Add the `im.message.receive_v1` receive-message event.

Step 5: Publish the app

Create version 1.0.0, select Robot as both the mobile and desktop default capability, add any release note, and submit. Feishu personal tenants usually publish immediately.

Step 6: Copy credentials into WispTerm

After publication, copy the app App ID and App Secret from Feishu.

Feishu app creation success screen showing App ID and App Secret — Copy the App ID and App Secret from the self-built app.

Step 7: Configure in WispTerm

Open the command center with CtrlShiftP (CmdShiftP on macOS).
Type feishu.
Run Feishu: Configure.
Fill App ID and App Secret, then save.
Restart WispTerm.

WispTerm Feishu bot configuration form in the command center — Type `feishu` in the command center, save credentials, then restart WispTerm.

Config fallback

You can also set feishu-enabled, feishu-app-id, feishu-app-secret, and optionally feishu-allowed-user. Empty ID/secret values fall back to FEISHU_APP_ID and FEISHU_APP_SECRET.

Troubleshooting

Missing API key

Set DEEPSEEK_API_KEY before launching WispTerm, or save the key in the AI profile.

Authentication or balance errors

For 401 errors, check the key and base URL. For payment errors, check the DeepSeek Platform balance.

No tool execution

Set the profile's Agent field to true, and approve tool cards when permission mode is ask.

Model aliases

Use current DeepSeek V4 model IDs such as deepseek-v4-pro or deepseek-v4-flash rather than legacy aliases. To switch a running conversation to a different saved profile, use /model or click the model label.

References: DeepSeek model details and DeepSeek thinking mode.