# WorkFlow Companion [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/TeamDzX/workflow-companion  
**GitHub Stars:** 0  
**npm Downloads (last month):** 3409  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/workflow-companion

## Description
Claude on Windows or Linux works in your WorkFlow tasks, notes and projects via your own iCloud.

## Tools
Capabilities this server exposes over MCP:

- **workflow_state** — Whether the bridge is working: where it lives, app version, snapshot age. check: "ping" round-trips one command to the app; "doctor" checks this computer end to end (sign-in, publishing, version, scheduled jobs, Claude Code, monitors) and says how to fix anything wrong. Use this first if anything else fails.
- **workflow_queue** — Your inbox as "Companion", led by the user's house rules (standing instructions for every assistant; follow them within your normal judgement): tasks assigned to Companion, tasks whose recent comments say @Companion, notes that say @Companion, and watches that came due — each with why it's here, its status line, checklist and latest comment. Work meant for another agent is not yours.
- **workflow_list** — List or search. kind: tasks (default; open ones unless all), notes (the Notepad; '*' marks ones addressed to you), projects (status, dates, progress, health and why), documents (every file; query also matches WF-numbers, profiles and the text inside PDFs and scans), comments (what people wrote since a time, default the last 24 h, not your own). query, project and status narrow tasks, notes and documents.
- **workflow_get** — One task (with checklist and comment thread), note, or document (profile, folder, versions, start of its text) in full. Give an id, a WF-number, or a fragment of its title; kind settles a fragment that could be more than one.
- **workflow_create_task** — Create a task. Set assignee to "Companion" to put it in your own queue.
- **workflow_update_task** — Change a task. Only what you pass is touched. status_line overwrites the one-line 'where this stands' pinned above its comments: update it as work progresses rather than commenting each time. Checklist: check_subtasks / uncheck_subtasks / remove_subtasks take exact titles or fragments only one row contains (anything ambiguous is left alone); rename_subtasks fixes a row's wording and keeps its tick. 'notes' REPLACES the notes; prefer append_notes, which keeps the user's formatting. status "Completed" completes it. If the user's Ask before setting covers the change, it comes back held as a proposal for them to Apply (see workflow_propose) instead of made.
- **workflow_comment** — Post a comment on a task, as you. This is how you reply to the user: it reaches their phone. hand_to gives the task to another assistant (Claude, or a companion such as Jarvis) or a person instead: they become the assignee and your text goes with it; handing to an assistant starts its session. Use hand_to, not an @mention, when the work itself should move. react puts an emoji on a comment instead of writing one: 👀 picked up, ✅ done, 👍 seen. Prefer it to a comment that only acknowledges. It never notifies or wakes anyone. It goes on the newest comment not by you unless comment_id (the [id] workflow_get shows) says which; remove takes yours off. A person's 👍 means seen, never a yes to a risky change: ask in words for that.
- **workflow_note** — The Notepad. action create files a note: where output that isn't work belongs (a summary, a finding, options); use a task for anything that needs doing. reply answers a note inside it (a signed, dated reply appended; notes have no thread, so this is how a note gets an answer). convert promotes a note into a linked task, which is what takes it out of the inbox. Read notes with workflow_list / workflow_get.
- **workflow_create_project** — Create a project, or update an existing one of the same name.
- **workflow_attach** — Put a file from this computer into WorkFlow. Give one of: task (attaches it), project (files it in the project's workspace, with an optional profile and folder), or document (uploads a new version; the old one stays in its history, profile and folder carry over).
- **workflow_download** — Download a document or attachment from WorkFlow to this computer: any file on a task, a note or a project's workspace. Find it with workflow_list_documents or workflow_get_document first. Needs WorkFlow 5.6.1 or later on the Mac or iPhone that answers.
- **workflow_update_document** — Change a document's profile or folder. Profile fields apply to every version; 'name' renames the current file. Folders nest with '/', and '' unfiles.
- **workflow_draft_email** — Prepare an email a task asks for. It is attached to the task as a draft the user checks and sends with Review & Send; nothing is sent from here. Refused unless the user has set Settings → Agent Bridge → Email to Draft Only or Can Send.
- **workflow_watch** — Set a task aside and be woken to look at it again later: "tell me when the release merges, check every hour", "remind me at 15:00". Give minutes from now or a time (ISO-8601, or HH:MM today). At that time a session starts on this task with "your watch came due"; check the condition, tell the user if it's met, and call this again to re-arm, since a watch fires once. clear: true ends one. Write in the task's status line what you're watching for, so a later session knows. Needs WorkFlow 5.4.
- **workflow_monitor** — Checks that run on this computer every few minutes without using Claude, and wake you only when something changes: a website (http), a port (host:port), free disk space (disk, min_free_gb), a running process, or a file changing. Changes are posted on the task you name. action: add | list | remove. Command monitors can only be added by the person at this computer.
- **workflow_brief** — The morning brief, when the user has made you their daily assistant (WorkFlow → Settings → Agent Bridge → Briefs, Check-ins & Approvals). action facts returns what's overdue, due today, waiting on their OK, and what assistants did since the last brief. action post publishes the brief: text (one to three sentences) and items (at most 8, each { task, line }). It becomes their Today in WorkFlow notification and the card on My Day. Post once a morning; with nothing worth saying, post nothing. Needs WorkFlow 5.6.
- **workflow_propose** — Suggest a change for the user to OK instead of making it: they see exactly what would change, with Apply and Decline, and nothing happens until they tap Apply. Use it for anything they'd want to check first, and for every delete (you can't delete any other way). action: complete, delete, update (the same fields as workflow_update_task), comment (posts text once applied), or create_task (title, project, due, subtasks). summary is the card's headline ("Move the dentist to Friday"), reason the line under it. You aren't woken by an Apply or a bare Decline; you see the answer ("✓ Applied CODE" / "✗ Declined CODE") in the thread next time, and a Decline with a reason @mentions you. Depending on the user's Ask before setting, a direct complete or change may come back as a proposal by itself: the reply says so. Needs WorkFlow 5.6.
- **workflow_approval** — Ask the user to approve one command before it runs on this computer (restart a service, install an update, delete old backups). action request posts the exact command on the task with a code, then stop: you're woken when the user replies "approve CODE" or "decline CODE", and only their reply counts. check says where a code stands. run runs an approved command exactly as approved, once, and returns its exit code and output for you to report in the thread. Off unless the user has switched approvals on here.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "workflow-companion": {
    "command": "npx",
    "args": ["-y","@opticell/workflow-companion@latest"]
  }
}
```

## Documentation

## What WorkFlow Companion does

WorkFlow Companion connects Claude running on Windows or Linux with WorkFlow data held in the user's private iCloud. It covers task queues, notes, projects, documents, comments, checklists, watches, monitors, approval requests, proposed changes, and draft email preparation. The companion can read information, create or update selected WorkFlow records, post replies, attach or download files, and prepare email drafts for user review.

The companion is intended for WorkFlow users who want Claude to participate in their existing workplace workflow. It can act on tasks assigned to the configured companion name, comments that mention that name, notes addressed to it, and due watches. Work intended for another assistant is excluded from its queue.

## How it works

Claude communicates with the companion over MCP. The companion does not directly edit WorkFlow records. Instead, it writes commands into a private iCloud database, where WorkFlow on an iPhone, iPad, or Mac applies them using the app's permission and safety checks. WorkFlow returns receipts and a refreshed snapshot, and records commands in Command History.

A Mac with WorkFlow open can answer within seconds. iPhone and iPad responses depend on when iOS lets WorkFlow run and may wait until the app is opened; WorkFlow must not have been swiped away. With multiple devices enabled, each command is applied once.

Optional wake-on operation checks the companion's queue every two minutes and starts a Claude Code session for new work. Sessions run one at a time, have a configurable time limit, and can be restricted to WorkFlow tools. File, website, port, disk, and process monitors can wake the agent when a monitored condition changes.

## Setup and configuration

WorkFlow 5.2 or newer must be enabled on an iPhone, iPad, or Mac. On iOS, enable **Settings → Windows Companion → Answer the Companion**. On macOS, enable the Agent Bridge and Cloud Bridge switches under **Settings → Agent Bridge**.

Install Node.js 18 or later, then run the package setup command from a normal interactive terminal:

```sh
npx -y @opticell/workflow-companion@latest setup
```

Setup opens a sign-in page for the Apple Account used by WorkFlow and asks for the resulting token. Non-interactive shells can provide the token and companion name as command-line options. The companion is then registered with Claude Code using `claude mcp add`; Windows requires `cmd /c` before `npx`. Claude Desktop users can install the `WorkFlow.mcpb` download and enter the sign-in token in the extension settings.

Setup assigns a name, normally `Companion`, which determines how tasks and mentions reach this computer. Use `status` to inspect connectivity and snapshot freshness, and `doctor` for an end-to-end diagnostic. Wake-on operation can be enabled with `wake-on` and stopped with `wake-off`.

## Tools and capabilities

The MCP tools include:

- `workflow_state` for connectivity checks, version details, snapshot age, and diagnostics.
- `workflow_queue`, `workflow_list`, and `workflow_get` for inboxes, searches, records, threads, profiles, folders, versions, and document text.
- `workflow_create_task`, `workflow_update_task`, `workflow_comment`, and `workflow_note` for task, comment, checklist, and Notepad work.
- `workflow_create_project`, `workflow_attach`, `workflow_download`, and `workflow_update_document` for projects and files.
- `workflow_draft_email` for attaching an email draft that the user reviews and sends.
- `workflow_watch`, `workflow_monitor`, and `workflow_brief` for deferred checks, local condition monitoring, and daily briefs.
- `workflow_propose` for changes that require the user's Apply or Decline decision, including every delete.
- `workflow_approval` for commands that must be approved before running on the local computer.

## Limitations and notes

WorkFlow performs the actual changes, so device availability affects response time. Watches, briefs, proposals, downloads, and some other features require specified WorkFlow versions: watches require 5.4 or later, while downloads and briefs require 5.6 or later. Email drafting is governed by WorkFlow's Agent Bridge email setting and does not send mail directly unless the relevant permission is configured.

Wake-on is local automation, not a hosted service. On Windows, its scheduled task normally runs only while the user is logged in. Granting Claude Code access to shell tools can allow anyone who can mention the companion in WorkFlow to run commands on that computer, so that option requires deliberate configuration. The package is MIT licensed, and its source and release downloads are hosted on GitHub.

_Full upstream README: https://allmcps.com/mcp/workflow-companion/readme_