TaskWraith

TaskWraith

[](https://github.com/boggspa/TaskWraith/actions/workflows/ci.yml)

TaskWraith is a local-first desktop workbench for running and reviewing AI coding agents against developer workspaces. Its Electron app ships for macOS, Windows, and Linux; macOS has the deepest native integrations and hosts the optional iOS companion. TaskWraith keeps its orchestration, local history, and workspace authority on the user's machine; prompts and run context still go to whichever cloud provider the user selects.

Read [POSITIONING.md](POSITIONING.md) for the concise product promise, claim boundaries, topology decision guide, and recommended small Ensemble panels.

> iOS companion status: TaskWraith for iPhone/iPad is in TestFlight beta. > It is a Mac companion — it pairs with TaskWraith on macOS over an > end-to-end-encrypted connection to monitor runs, approve actions, and reply > from the phone; it is not a standalone AI app. Remote actions are governed by > the Mac's workspace allowlists and approval policy. Relay/APNs infrastructure > may see routing/status metadata (including aggregate added/deleted line > counts), not plaintext prompts, commands, diff contents or hunks, or model > output. Live Activities are the explicit exception to the ordinary encrypted > task projection: ActivityKit must decode their push state, so Apple receives > only an allowlisted coarse phase, provider names, start time, change counts, > bounded seat states, layout/palette, and an opaque per-card reference—never > task text, titles, paths, workspace/repository names, or run/chat ids. No > privacy-sensitive value may ever be seeded into that state; expanding the > allowlist requires a fresh privacy and security review. Testers can also build > it from this repository with their own Apple Developer team. Push > notifications are opt-in after pairing and require APNs credentials on the > Mac (see > ios/TaskWraithApp/README.md).

Ensemble Threads

TaskWraith's most experimental surface is Ensemble Threads: shared work sessions where multiple AI agents participate in the same conversation instead of living in separate tabs. A thread can include up to thirty named participants across Codex, Claude, AntiGravity, Kimi, Cursor, Grok, Pi, Mistral Vibe, and local Ollama, each with its own model, role, order, and permission posture.

Kimi seats additionally require runtime admission: structural checks (stable binary identity, bounded probes, the ACP-only posture) that are always enabled, packaged builds included. While the reviewed qualification roster is empty, admitted runs are labelled unattested-development; that labelling cannot qualify a release.

Cursor is in the user-approved live set. Its current Path-B route signs in with cursor-agent and works in solo chats, Ensembles, and delegated work. Cursor can use its native tools alongside TaskWraith tools, with the selected permission posture and workspace Tool Grants applying wherever TaskWraith mediates. The provider-native boundary is explained in [Trust & Safety](TRUSTANDSAFETY.md).

This is not just provider switching. Ensemble participants see the same transcript, can build on each other's work, hand off deliberately, run turn-bound or continuous rounds, and fan out in parallel. Qualified tool-capable participants can use TaskWraith's workspace tools under the same local approval and audit model. In practice, a single thread can hold a planner, implementer, adversarial reviewer, docs writer, and local-model scout without losing the workspace timeline or review trail.

Ensembles are designed for work that benefits from disagreement and role separation: code review, architecture critique, bug hunts, migration planning, release checks, and "one agent implements while another watches the diff" flows. They pair with Multiview, Workflows, slash commands, MCP tools, and the activity viewport so multi-agent work remains inspectable rather than becoming a hidden background process.

Normal top-level chats no longer need to be recreated just to change shape. You can now switch provider, model, and reasoning on an existing single-provider thread after it has history, and if a turn is already running those changes queue and apply at turn end. Top-level idle chats can also flip in place between single-provider and Ensemble mode on the same thread, preserving transcript history; the ensemble toggle stays disabled until the current turn finishes.

Trust, Safety, and First Runs

Start with low-risk work. TaskWraith is designed to keep permissions visible and auditable, but it still coordinates powerful local tools. Use a scratch repo and read-only posture first, then widen trust only after the behavior is familiar.

TaskWraith has a broad optional permissions surface: provider CLIs, local models, workspace file tools, shell/git actions, iOS remote control, collaborator sharing, Screen Watch, Canvas/browser-like tools, media tools, and creative-app automation. The default expectation is explicit user control: select a workspace, choose a run posture, review approvals, inspect activity, and check diffs before committing generated work.

New users should start with a scratch repository in Read-only/Recon or Plan workflow. Plan workflow is not general write access: it can save a narrow markdown plan artifact under a validated workspace path for the proposed-plan handoff, but ordinary file edits, shell commands, and tool writes still require a higher permission posture or explicit approval. Do not enable remote pairing, Screen Watch, Canvas/browser automation, creative app bridges, unattended workflow grants, or full-workspace/yolo permissions until the app has earned trust through several low-risk sessions.

Read [TRUSTANDSAFETY.md](TRUSTANDSAFETY.md) for the safe-first-run guide, capability matrix, storage locations, provider data boundaries, release verification steps, and known limits. Optional features that require outside accounts, local services, or macOS permissions are covered in [ADVANCEDOPTIONALSETUP.md](ADVANCEDOPTIONALSETUP.md). [SAFETY.md](SAFETY.md) and [SECURITY.md](SECURITY.md) contain the engineering guardrails and release baseline.

Electron builds configured with TaskWraith's first-party activity endpoint leave privacy-minimised product observation off until you affirmatively choose Share during first launch or under Settings → Safety & Privacy. The choice is optional, sends only the fixed no-content contract, can be withdrawn at any time, and never affects app features. Builds without an endpoint send nothing. [PRIVACY.md](PRIVACY.md) explains platform aggregates, retention, user choices, and the exact data boundary.

Welcome & provider setup

General App Layout

A live Ensemble run

Pop-Out Chat

Diff Studio

File Editor

Features

• Workspace Safety: Workspace selection, trust-state visibility, approval

modes, and run-scoped safety state before agents operate on local files.

• Provider Runs: Integrated run surfaces for Codex, Claude, AntiGravity

(bring-your-own Gemini API key), Kimi, Cursor, Grok, Pi, Mistral Vibe, and local Ollama (curated Qwen, Gemma, GPT-OSS, and Poolside presets). Kimi's integrated surface is admission-dependent: every build applies structural identity, bounded-probe, and ACP-posture checks. The current source-ahead reviewed roster is empty, so structurally admitted runs are labelled unattested-development; credentials or a visible picker row alone do not bypass structural admission. Cursor's current Path-B route signs in normally and works in solo chats, Ensembles, and delegated runs with native tools plus TaskWraith tools. The historical standalone Gemini provider remains readable but retired for new runs; it is distinct from the live, opt-in AntiGravity integration. Run management is provider-neutral: the lifecycle inventory covers all ten stable provider identities and every admitted turn crosses the shared signed posture boundary. Availability remains a separate product decision; missing broker, provenance, or scheduled-seal evidence is reported as a limited or unsealed run and does not by itself remove a provider. Provider names describe compatible integrations only — CLIs and accounts stay user-installed. See the [Model Catalogue](MODEL_CATALOGUE.md) for the curated model rows, reasoning controls, and Fast-tier semantics.

• Multiview and Workflows: Split the workbench into live panes, and run

Workflows as first-class chat/run objects with scheduled recovery, dedicated sidebar space, and optional ensemble execution where enabled.

• Thread-isolated Worktrees: Selection-required runtime profiles allocate

and persist a per-thread worktree before dispatch, then route the run and Diff Studio review through that effective workspace instead of the base checkout.

• Chat / Code / Work navigation: Use Chat for general conversations,

Code for workspace-scoped threads, workflows, boards, and local servers, and Work for Projects. Projects build cross-workspace folder trees with customizable icons and hues, plus drag-and-drop and add-menu organization. Each project can designate, open, or start a Project Home thread, and keep a metadata-only library of relevant files, folders, and links. Library entries do not grant agent access or inject content into a run.

• Thread Goals: Set a persistent objective with /goal or the

composer goal control. Codex uses native goal state when the installed runtime exposes it; qualified tool-capable providers get a TaskWraith-managed fallback with explicit complete/blocked lifecycle tools.

• Composer Shells: Provider-aware and task-oriented composer variants give

each working mode its own affordances—including the ChatGPT shell—without changing the safety model. See [COMPOSERVARIANTS.md](COMPOSERVARIANTS.md) for the Electron shell gallery.

• Plan Workflow: Plan runs keep the provider in a read-only execution

posture while allowing a product-managed markdown plan file to be written under validated workspace paths. Read-only/Recon runs do not get that artifact-write carve-out.

• Ensemble Threads: Multi-agent shared work sessions with named provider

participants, role/order control, turn-bound or continuous orchestration, optional parallel fan-out, cross-provider handoffs, a shared Blackboard for cross-agent notes and rich polls (composer quick-access popover plus full management in the Notes pane), and TaskWraith MCP tools shared among qualified tool-capable seats under one auditable workspace policy.

• Agent Pool: Save reusable agents in Settings, each with a linked

provider/model/reasoning configuration and running contribution stats (runs, threads, tokens, tool calls, work time), then drag them into ensemble rosters. A welcome-dashboard leaderboard ranks pool agents by contribution.

• Audit Runs: /audit can coordinate provider-backed review passes with

live progress, structured findings, verdicts, and dismissible run banners.

• Local Ollama: Full TaskWraith tool-surface parity where local capability is

available, optional live web search/fetch, per-model context engineering, and session memory across runs — all governed by the same permission roles and policy gates as cloud providers.

• Custom MCP Servers: User-defined MCP servers can be managed, validated,

imported, exported, and attached to compatible provider runtimes with provider-specific JSON/TOML snippets and readiness checks. Cursor JSON import/export remains useful for configuration interchange. Managed Cursor can use both its native tools and TaskWraith's governed tools; provider- or account-owned MCP remains a separate trust boundary.

• Activity Review: Live activity viewport for in-flight tools and thinking,

compact timelines, durations, and raw event inspection.

• AI Close-Out Summaries: Run and ensemble-round close-out cards show

readable prose plus a pass/fail line instead of quoting an agent's last message verbatim. On Macs with Apple Foundation Models available, that prose is generated on-device (badged "via Foundation Models") behind a prompt-injection guard; a deterministic summary is the fallback everywhere else.

• Diff Studio: File-list and diff-detail review for run-scoped changes and

current workspace changes, including previews for newly created text files.

• GitHub PR & CI Awareness: When the workspace has a GitHub remote, an icon

row above the composer shows live PR lifecycle and CI status; hovering opens a popover with fuller detail (including failing-check logs). A per-chat Watch this PR opt-in can post deduplicated status transitions after revalidating the current PR head, while Notify thread remains available for an immediate Blackboard or transcript post.

• Local History and Usage: Local-only chat, run, usage, approval-ledger, and

audit state for repeat work without a hosted backend.

• iOS Companion: TestFlight companion surfaces Demo Mode, Workflows,

first-launch/provider readiness, usage snapshots, approvals, questions, transcript streaming, thread renaming, inline images, remote file/diff inspection, home search and pin/rename/archive, scheduled sending, and transcript export. Source-ahead builds also offer configurable completion banner presets and Live Activities for in-flight runs on the Lock Screen and Dynamic Island, with the separately disclosed coarse APNs state above.

• Release Tooling: Security, dependency, packaging, and signing hooks for

reproducible local release work.

Download installers from the latest GitHub Release (see [Try a packaged build](#try-a-packaged-build)). See [CHANGELOG.md](CHANGELOG.md) for release notes. This checkout may contain repository work newer than the latest tag; the changelog's top source-ahead entry describes those changes only. They are not shipped until a new tag and matching artifacts are published.

Managed Enterprise Boundary

TaskWraith has local safety controls, local audit evidence, redacted export surfaces, and partial managed-policy support. It does not currently claim SSO, SCIM, SIEM integration, WORM or append-only audit export, organization-wide retention, or a complete MDM/enterprise control plane. Treat enterprise-readiness notes as claim boundaries and implementation tracking, not a compliance attestation.

Public Source Boundary

TaskWraith source code is licensed under Apache-2.0. Provider product names are used nominatively to describe interoperability with user-installed tools and accounts. A narrowly scoped set of first-party provider PNG marks is bundled for factual identity labels; provenance and source-specific rights notes live in [design-assets/provider-logos](design-assets/provider-logos/). Those marks remain the property of their respective owners and do not imply endorsement. The repository does not intentionally bundle API credentials, signing material, or proprietary provider fonts.

Users are responsible for installing and authenticating the provider CLIs, SDKs, or accounts they choose to use. TaskWraith does not bypass provider authentication, quotas, rate limits, approval flows, or terms of service.

Built with AI Agents

TaskWraith is developed the way it is meant to be used — with AI coding agents in the loop. Day-to-day work pairs OpenAI Codex and Anthropic Claude: planning, implementation, multi-agent review passes, and large refactors run through the agents. Agent output is reviewed by a human before merge, and release work is gated by dependency checks, typecheck,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: boggspa
• Source: boggspa/TaskWraith
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.