Chapter 1 · Product Introduction

What is DeskWand?

DeskWand is an open source AI desktop agent. Unlike a regular chatbot, it doesn't just reply — it plans, uses tools, and keeps working until your goal is achieved. It runs locally on your machine with the AI model of your choice, so your data stays private and you remain in control.

Core Capabilities

• Multi-model support — Use OpenAI, Anthropic, Gemini, Ollama, DeepSeek, OpenRouter, or any OpenAI/Anthropic/Gemini-compatible endpoint. Bring your own API key.
• Tool calling — The agent reads and writes files, executes shell commands, searches the web, and fetches content — all autonomously.
• Skill system — Install and enable skills that inject specialized knowledge and workflows (PDF processing, video editing, Lark/Feishu integration, and more).
• MCP connectors — Connect to external tools and data sources via the Model Context Protocol (browsers, databases, third-party APIs).
• Scheduled automation — Set one-time or recurring tasks that run automatically at specified times.
• Long-term memory — The agent remembers your preferences and project context across sessions.

Typical Use Cases

• Code development — Read a codebase, write and edit files, run tests, fix bugs
• Data analysis — Process spreadsheet data, generate charts and reports
• Document authoring — Draft, edit, and format documents
• Web research — Search the internet, extract content from pages, summarize findings
• Daily automation — Schedule recurring tasks like daily reports, email summaries, or data syncs

How Is It Different from a Chatbot?

A regular chatbot gives you an answer and waits for the next question. DeskWand takes initiative: it breaks your goal into steps, picks the right tools for each step (read a file, run a command, search the web), executes them, evaluates the results, and continues. This loop keeps running until the goal is complete or you pause it.

Chapter 2 · Installation & Quick Start

System Requirements

Download & Install

Visit deskwand.com/#download to download the latest release for your platform:

• macOS — Open the .dmg file and drag DeskWand to your Applications folder.
• Windows — Run the .exe installer and follow the setup wizard.
• Linux — Use the .AppImage, .deb, or .rpm package.

First Launch

1. Open DeskWand. The API Setup screen appears automatically on first run.
2. Choose your AI provider (e.g., OpenAI, Anthropic, Gemini) and enter your API key.
3. Select a model from the list or enter a model ID manually.
4. Click Save Settings.
5. You're ready — type a message and hit Enter.

Interface Overview

The main window has four key areas:

Chapter 3 · API Configuration

Supported Providers

DeskWand works with any API provider that follows the OpenAI, Anthropic, or Gemini protocol. Specifically supported:

You can also connect any custom endpoint that exposes an OpenAI or Anthropic-compatible API.

Configuration Workflow

1. Open Settings → API.
2. Select a provider from the list or choose "Other Provider" for a custom endpoint.
3. Enter your API Key.
4. (Optional) Customize the Base URL if connecting to a proxy or self-hosted endpoint.
5. Select or manually enter the Model ID.
6. Click Test Connection to verify everything works.
7. Click Save Settings.

Configuration Profiles

You can create multiple configuration profiles — for example, one for work with OpenAI and another for personal use with a local Ollama model. Switch between them from the API settings page using the dropdown at the top. Each profile stores its own provider, key, base URL, and model list independently.

Vision Model

If your main model doesn't support image understanding (multimodal), you can configure a separate vision model. When you paste or attach an image, the agent uses the vision model to describe what it sees, then passes that description to your main model for reasoning.

Configure this under Settings → API → Vision Model.

Search Configuration

Under Settings → API → Search, you can configure a dedicated model for web search and content fetching. This is separate from your main model and allows you to use a faster or cheaper model for search-related operations while keeping a more powerful model for reasoning.

OAuth Subscription Integration

Instead of entering API keys manually, you can connect your existing subscriptions:

• ChatGPT Plus — Log in with your OpenAI account
• Claude Max — Log in with your Anthropic account (Max with additional usage credits required; Pro is not supported)
• GitHub Copilot — Log in with your GitHub account
• OpenRouter — Log in with your OpenRouter account

Go to Settings → API, scroll to Subscription Access, and click Connect next to your provider.

Connection Diagnostics

If something isn't working, use the built-in diagnostic tool: Settings → API → Run Diagnostics. It runs a step-by-step check:

1. DNS Resolution — Can your machine resolve the API hostname?
2. TCP Connection — Can it reach the server?
3. TLS Handshake — Is the connection secure?
4. API Authentication — Is your key valid?
5. Model Validation — Can the model accept requests?

Each step reports pass/fail with actionable error messages to help you fix the issue.

Chapter 4 · Projects & Sessions

Projects

A project is a named workspace tied to a folder on your disk. Sessions (conversations) belong to a project, which keeps files, context, and tool execution scoped to that directory. This is useful for separating different workstreams — for example, a "Website" project and a "Data Analysis" project.

Create a new project from the sidebar: click the + button next to the project section, enter a name, and DeskWand creates the directory for you.

Session Management

• New session — Click New in the sidebar to start a fresh conversation.
• Switch sessions — Click any session in the sidebar to switch context.
• Search — Use the search bar at the top of the sidebar to find sessions by title or project name.

Sidebar Organization

Sessions are grouped by project and sorted by recency: Running, Today, Yesterday, Previous 7 Days, Older. Projects can be collapsed or expanded. Active sessions show a running indicator.

Archive & Restore

Archive sessions you no longer need to keep the sidebar clean. Right-click (or long-press) a session and choose Archive. View and restore archived sessions under Settings → Archived.

Context Compaction

Long conversations can exceed the model's context window. When this happens, DeskWand automatically compacts the conversation — summarizing earlier messages to free up space. You can also trigger compaction manually by typing /compact or using the slash menu.

Goal Mode

Goal mode lets the agent work autonomously toward a high-level objective:

1. Set a goal — e.g., "Research and summarize the top 5 AI papers from this week"
2. The agent plans, executes, evaluates, and repeats until the goal is achieved.
3. You can pause, resume, or clear the goal at any time.
4. The status bar shows progress: current iteration, tokens used, and time elapsed.

Access goal mode via the slash menu (/goal) or the action bar.

Chapter 5 · Chat Interaction

Sending Messages

Type your prompt in the input bar at the bottom and press Enter to send. You can also:

• Paste images from your clipboard — the agent will see them (if your model or vision model supports images).
• Attach files — drag and drop or use the attach button in the input bar.
• Expand the input bar — click the expand button or press Shift+Enter for multi-line input.

Slash Commands

Press / in the input bar to open the slash command menu. This lists available commands and skills, organized by category. Use arrow keys to navigate and Enter to select. Categories include:

• Commands — Built-in actions (compact, goal, etc.)
• Skills — Installed skills for specialized tasks

Streaming Output & Thinking

As the agent works, you'll see responses stream in real time. The agent may also show its thinking process — the reasoning steps it takes before acting. This is displayed in a collapsible block above each response, so you can inspect or hide it.

Tool Call Cards

When the agent uses a tool (reading a file, running a command, searching the web), a card appears in the chat showing:

• The tool name and input
• The output or result
• Execution time and token usage

Cards are color-coded and compact — click to expand if you want full details.

Artifact Panel

The right-side panel (toggle with the artifact button) shows all files created or modified during the session. Each entry shows:

• File path
• Diff summary (± lines added/removed)
• Quick actions: preview, reveal in folder, copy path

Message Actions

Hover over any message to reveal action buttons: Copy the message text, or reveal the file in your file manager if the message references a file.

Permission Approvals

Some tools require your approval before executing — especially those that write to files or run shell commands. When a tool needs permission:

• A dialog appears showing the tool, its input, and a warning.
• You can Allow once, Always Allow for the rest of the session, or Deny.
• Commands requiring admin privileges prompt for your system password (not stored).

Chapter 6 · Tool System

How Tools Work

The agent automatically selects and uses the right tool for each step — you don't need to specify which tool to use. Just describe what you want, and the agent decides whether to read a file, run a command, search the web, or combine multiple tools.

File Tools

Shell Commands (Bash)

The agent can execute shell commands in your working directory. This is how it installs dependencies, runs scripts, builds projects, and performs system operations. Commands requiring admin privileges will prompt for your password.

Web Tools

Web Access Configuration

Choose your search provider under Settings → Web Access. Available providers: OpenAI, Brave, Exa, Tavily, Perplexity, Gemini, Auto. Each provider can use its own dedicated API key or inherit the key from your main API configuration.

Artifact Panel

The artifact panel (right sidebar) automatically tracks every file created or modified during a session. It's the fastest way to find, preview, or locate a file the agent just worked on. Each artifact card shows the file path, a diff summary, and quick-action buttons.

Chapter 7 · Skill System

What is a Skill?

A skill is a reusable extension package that gives the agent specialized knowledge, instructions, and tool configurations for a specific domain. Skills make the agent more effective at tasks like PDF processing, video editing, financial analysis, weather lookups, or interacting with services like Lark/Feishu and Slack.

Built-in Skills

DeskWand ships with a set of built-in skills covering common tasks. You can enable or disable them individually under Settings → Skills. Built-in skills are automatically available and don't need installation.

Skill Marketplace

Browse, install, and update community-contributed skills from the Skill Cloud:

1. Open Skill Cloud from the sidebar or Settings → Skills.
2. Browse by category or search for a specific skill.
3. Click a skill card to view details (description, version, download count).
4. Click Install to add it to your collection.

Installed skills appear in your My Skills list, where you can enable/disable or remove them. The marketplace shows update indicators when newer versions are available.

Skill Cloud (Login Required)

Log into your DeskWand account to unlock cloud features:

• Sync your skills across devices
• Share skills with your team
• Publish your own skills to the marketplace

Custom Skills

You can import skills from a local folder: go to Settings → Skills and click Import from Folder. This is useful for testing your own skills or using skills shared directly by a teammate.

Chapter 8 · MCP Connectors

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools and data sources. MCP connectors let your agent interact with browsers, databases, APIs, and other services — just like built-in tools.

Quick-Add Presets

DeskWand includes preset configurations for popular MCP servers (e.g., Chrome DevTools). Go to Settings → Connectors and click a preset to add it instantly. Presets are pre-configured — you just need to enable them.

Custom Connectors

Add your own MCP connector by clicking Add Connector in Settings → Connectors. Choose from three transport types:

Each connector can have environment variables for authentication tokens (e.g., NOTION_TOKEN, DATABASE_URL).

Managing Connectors

Once a connector is added and enabled, its tools become available to the agent during conversations. The connector card shows:

• Connection status (connected / connecting / failed)
• Number of tools available
• Edit and delete options

Chapter 9 · Scheduled Tasks

Overview

Scheduled tasks let you automate prompts to run at specific times — like an alarm clock for your AI agent. Use this for daily reports, periodic data checks, recurring research, or any task you want to run on a schedule.

Calendar View

Access scheduled tasks under Settings → Schedule. The calendar view shows all your tasks organized by day, week, or month. Click any empty slot to create a new task, or click an existing task to edit it.

Task Modes

Configuring a Task

1. Choose a mode (once, daily, weekly, interval).
2. Set the time(s) — click to add time points (format: HH:MM).
3. Enter the prompt — what the agent should do when triggered.
4. Optionally specify a working directory (defaults to current project).
5. Toggle Enabled to activate the task.

Monitoring & Control

• See each task's next run time and last execution status.
• Click Run Now to trigger a task immediately for testing.
• Pause/resume individual tasks without deleting them.
• A running task creates a session in the sidebar — you can stop it manually or view its progress.

Chapter 10 · Memory System

How Memory Works

DeskWand builds a long-term memory of your preferences, past work, and project context so future sessions are more effective. There are two types:

Enable / Disable

Go to Settings → Memory to toggle the memory system on or off. When disabled, the agent won't inject past memories into new sessions, and it won't learn from current sessions. Existing memory data is preserved and resumes when re-enabled.

Searching Memory

Use the search bar in Settings → Memory to find past memories by keyword. Filter by scope: current workspace, all workspaces, or core memory only. Click any result to see the full summary and original source excerpt.

Maintenance

Under Settings → Memory → Maintenance, you can:

• Rebuild workspace — Re-scan historical sessions to regenerate workspace memory.
• Clear workspace — Delete all memory for the current project.
• Clear core memory — Delete all global preferences and patterns.

Chapter 11 · Settings & Preferences

Appearance

Under Settings → General:

• Theme — Light, Dark, or follow system preference.
• Color Palette — Choose from presets: Graphite, Paper, Void, Ocean, Forest, Ember, Aurora.
• Language — English or 中文 (Chinese).

Automatic Skill Learning

When enabled (default), the agent can automatically discover and learn new skills during conversations and periodically organize existing ones. Turn this off if you prefer manual skill management. Note: automatic learning is not available in project mode.

Anonymous Telemetry

DeskWand collects anonymous usage statistics to help improve the product. This includes only a random device identifier and app version — no personal data. You can opt out under Settings → General → Telemetry.

Updates

Go to Settings → About to check your current version and look for updates. DeskWand supports automatic update checking and one-click install. If a new version is available, a notification appears in the status bar.

Chapter 12 · FAQ & Troubleshooting

API connection fails — what should I check?

1. Is your API key correct and not expired?
2. Is the Base URL correct? (Especially if using a proxy or self-hosted endpoint.)
3. Run Settings → API → Run Diagnostics for a step-by-step diagnosis.
4. Check your network — firewalls or VPNs may block API connections.

My model isn't listed — how do I use it?

Switch to Manual Model mode and enter the model ID directly. Make sure you've selected the correct protocol (OpenAI / Anthropic / Gemini) that matches your model's API.

The agent keeps getting errors when running commands

• Check that the working directory exists and is accessible.
• For system-level commands (installations, builds), check if admin privileges are needed.
• Review the tool call cards in the chat for exact error messages.

How do I export logs for support?

Go to Settings → Logs and click Export Diagnostic Package. This creates a ZIP file containing app logs, sanitized environment info, and metadata about recent sessions and errors. Share this file with the DeskWand team for faster troubleshooting.

Can I use DeskWand offline?

Yes — use a local model via Ollama. Install Ollama, pull a model (ollama pull llama3), and configure DeskWand to use the Ollama endpoint. Local models work without an internet connection.

Where is my data stored?

Everything is local-first. Your API keys, conversations, settings, and memory are stored on your machine. Nothing is sent to DeskWand servers unless you explicitly use cloud features (Skill Cloud sync, OAuth subscriptions) or enable telemetry (anonymous and minimal).

How do I get help or report a bug?

• GitHub — github.com/deskwand/agent — open an issue or discussion
• Website — deskwand.com
• X (Twitter) — @deskwanda