How to set up WorkBuddy and run your first autonomous task

WorkBuddy is a desktop AI agent — you describe a task, it plans the steps, and it executes them on your local machine. Unlike a chatbot, it can read files, run shell commands, and write outputs. Unlike an IDE assistant, it does not live inside an editor — it lives on your desktop. This guide covers the install, the security model, and the first task to try (and what to try second).

What you'll learn

• What WorkBuddy is (and what it isn't — desktop agent, not an IDE)
• Install + first launch
• The folder authorization model explained
• The first task to try (small and observable)
• How to read the task list and the three status states

What WorkBuddy is (and isn't)

WorkBuddy is one of the newer category of desktop AI agents — applications that live on your computer (not in a browser tab) and can take real actions on your files, your terminal, and (with permission) your other applications.

It is not an IDE. You do not open WorkBuddy to write code. You open WorkBuddy to tell it a job — "rename 200 photos by the date in their EXIF metadata" or "open every CSV in this folder and produce a summary spreadsheet" — and it figures out the steps.

It is not a chatbot. It has a chat interface, but the chat is for giving it tasks and getting status updates, not for back-and-forth conversation.

It is not fully autonomous. Every meaningful action requires folder authorization (see below), and most tasks benefit from a human review of the plan before the agent starts executing.

Install + first launch

1. Download WorkBuddy from workbuddy.ai. The download is roughly 200MB; the install adds a background helper service.
2. On first launch, WorkBuddy asks for a workspace folder. Pick a low-stakes folder to start — a ~/workbuddy-sandbox/ you create just for this. Do NOT point it at ~/Documents or ~/Desktop until you understand the authorization model.
3. Sign in. WorkBuddy requires an account; the free tier gives 50 task-credits per month, Pro gives 500.
4. The main window shows three panels: Tasks (left), Chat (center), Files (right).

The folder authorization model

This is the part that surprised me the most, and the part that wastes the most time for new users.

When you give WorkBuddy a task that touches a folder, it asks for folder authorization. This is a one-time grant, scoped to that folder, that lets the agent read and write inside it. Three things to know:

1. Authorization is per-folder, not global. You can grant access to ~/workbuddy-sandbox/photos without granting access to ~/Documents. The model is intentionally granular.
2. Authorization persists across sessions until you revoke it. You can see all current authorizations in Settings → Folder Access.
3. Cross-folder tasks require multiple authorizations. A task that reads from ~/Downloads and writes to ~/workbuddy-output/ will trigger two authorization prompts, in sequence. The task does not start until both are granted.

Your first task

Pick something small and observable — something where you can immediately tell whether the agent did the right thing. My recommendation for the very first task:

"Rename every file in this folder to the date in the file's EXIF metadata, formatted as YYYY-MM-DD_HH-MM-SS.jpg. If a file has no EXIF date, leave the name unchanged."

Why this is a good first task:

• The input is bounded (one folder, all images).
• The output is observable (you can scroll the folder and see the new names).
• The failure mode is obvious (a file with the wrong date is immediately visible).
• It does not require any external service (no API keys, no cloud uploads).

Walkthrough

1. In the Chat panel, type the task above. Press Enter.
2. WorkBuddy proposes a plan. It usually reads like: "Step 1: list the folder. Step 2: read EXIF data. Step 3: rename. Step 4: report."
3. Review the plan. For a first task, click Approve and Run. For more cautious use, you can click Step Through to see each step before it executes.
4. The task status panel updates as the agent works. Three states:
   • Running (blue) — actively executing.
   • Needs input (yellow) — the agent has a question or a permission request. Check the chat.
   • Completed (green) or Failed (red) — done. Check the output.

For the EXIF rename task, expect it to take 30-90 seconds for 50 photos. The completion message will list the renames it performed.

What to try second

After the EXIF rename works, try a task with two steps and a verification:

"Open every CSV in this folder, count the rows, and produce a summary spreadsheet summary.xlsx with columns filename, row_count, and column_count. Use Python with the pandas library."

This tests: file iteration, code execution, output writing to a new file. It usually works in one shot, and the summary file is the verification.

Gotchas

1. File path quoting on Windows vs Mac

On Windows, paths use backslashes (C:\Users\...). The agent sometimes double-escapes them. If you see "file not found" errors on Windows, try re-pasting the path with forward slashes — WorkBuddy's internal path handling is more reliable with / separators.

On Mac, paths with spaces in folder names (~/Library/Application Support/...) sometimes trip the agent. The fix is to either rename the parent folder or quote the path explicitly in the task.

2. When to break a task into smaller ones

A single task that touches 500+ files in 10+ folders is more likely to fail partway through than five tasks of 100 files each. The reason: long tasks accumulate context, and the agent starts to forget the original constraints halfway through. If your task description is longer than 3-4 sentences, split it.

3. The "Completed but wrong" failure mode

WorkBuddy will report Completed even if the output is subtly wrong (e.g., a renamed file has the right date but the wrong extension). Always spot-check the output, especially on the first run of a new task type.

4. Revoking folder authorization does not undo past actions

If you revoke access to a folder, the agent can no longer read or write it — but any files it already wrote or modified stay modified. Revocation is a future-only operation.

FAQ

Does WorkBuddy run code locally or in the cloud?

Locally. The agent runs on your machine. Some model calls go to the API, but the file system access is local.

What file types can it read/write?

Any file the underlying OS lets it touch. The agent is best at text files (Markdown, CSV, JSON, code) and image files (for metadata, not generation). PDFs work for text extraction; binary files (databases, archives) are unreliable.

Is my data sent to a server?

File contents are sent to the model API for processing (just like any AI tool that reads your files). File names and folder structures are visible to the API. To minimize data exposure, use a local LLM backend — WorkBuddy supports Ollama and LM Studio as model providers.

Can I undo a task?

Yes. The Tasks panel keeps a history of every task. Click any past task, then Revert (if the task supports revert — file deletions and renames do, content rewrites may not). The revert restores the prior state within the authorized folders.

How is this different from Claude Code or Codex?

Claude Code and Codex are developer tools — they live in a terminal, understand git, write code. WorkBuddy is an end-user tool — it lives on your desktop, does not assume you can read code, and is built for "I have a tedious file task" workflows. The overlap is "both can run shell commands," but the audience and the UI assumptions are different.

How much does it cost?

The free tier is 50 task-credits per month. A typical small task (rename 50 files) is 1 credit. Pro ($20/month) is 500 credits. Heavy users (daily use, large tasks) should plan for ~$30-50/month in credits.

Can I use it offline?

With a local LLM backend (Ollama, LM Studio), yes — but task quality drops significantly. For most users, online is the right answer.