TaskWraith

TaskWraith is a local-first desktop workbench for running and reviewing AI coding agents against developer workspaces. It provides a macOS-focused Electron UI for provider CLIs and SDK-backed workflows while keeping execution, history, and workspace state on the user's machine.

iOS companion status: TaskWraith for iPhone/iPad is pending TestFlight/App Store review. Until then, the iOS companion is provisionally available from this repository for testers who can sign and provision the app with their own Apple Developer team.

Welcome & provider setup	Ensemble Mode	A live Ensemble run
Pop-Out Chat Windows	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, Gemini, Kimi, Grok, Cursor, and local Ollama (curated Qwen, Gemma, and GPT-OSS presets). Provider names describe compatible integrations only — CLIs and accounts stay user-installed.
• Thread Goals: Set a persistent objective with /goal <objective> or the composer goal control. Codex uses native goal state when the installed runtime exposes it; every provider gets a TaskWraith-managed fallback with explicit complete/blocked lifecycle tools.
• Ensemble Mode: Multi-provider single-thread chats with up to six named participants, turn-bound or continuous orchestration, optional parallel fan-out, and TaskWraith MCP tools shared across providers.
• Audit Runs: /audit can coordinate provider-backed review passes with live progress, structured findings, verdicts, and dismissible run banners.
• Local Ollama: Tiered workspace tools (read-only through provider parity), optional live web search/fetch, per-model context engineering, and session memory across runs — all policy-gated like cloud providers.
• Activity Review: Live activity viewport for in-flight tools and thinking, compact timelines, durations, and raw event inspection.
• Diff Studio: File-list and diff-detail review for run-scoped changes and current workspace changes, including previews for newly created text files.
• Local History and Usage: Local-only chat, run, usage, approval-ledger, and audit state for repeat work without a hosted backend.
• Release Tooling: Security, dependency, packaging, and signing hooks for reproducible local release work.

Current release: v1.5.7 — see CHANGELOG.md for release notes.

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. The repository does not intentionally bundle provider logos, trademarks, 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 and are reviewed and merged by a human. Commits carry Co-Authored-By trailers for the agents that contributed.

Development Setup

1. Install Node.js 20 or newer.
2. Install any provider CLI you intend to use separately.
3. Run npm ci.
4. Run npm run dev.

Use npm ci for clean installs so npm follows the committed lockfile exactly. Run npm run security:deps before release work or after dependency changes.

Discord Context

Discord Context is a read-only composer attachment for solo and ensemble chats. It reads a recent snapshot from channels your bot can access, labels it as untrusted context, and does not post back to Discord.

Configure it with a Discord bot token and at least one server ID. The bot needs permission to view the channel and read message history. For local development you can put the variables in .env; for a packaged macOS app launched from Finder, use one of the runtime config files below and restart TaskWraith:

mkdir -p "$HOME/.config/taskwraith"
cat > "$HOME/.config/taskwraith/discord-context.env" <<'EOF'
TASKWRAITH_DISCORD_BOT_TOKEN=your-bot-token
TASKWRAITH_DISCORD_GUILD_IDS=123456789012345678
EOF

TASKWRAITH_DISCORD_GUILD_IDS accepts a comma-separated list. The singular TASKWRAITH_DISCORD_GUILD_ID alias also works for one server.

Useful Commands

npm run security:deps
npm run typecheck
npm run test
npm run test:swift:bridge   # macOS only — see note below
npm run build

npm run test:swift:bridge runs the native macOS bridge daemon's Swift test suite in swift/TaskWraithBridge. The bridge gates native macOS actions (Screen Watch, creative-app, and editor helpers), so its tests run automatically in two places: the macOS legs of CI, and the build:mac / build:mac:notarized release recipes (as a pre-flight gate, so a release build fails fast on a bridge regression). It requires macOS with the Xcode Swift toolchain and is not part of the cross-platform npm run ci.

Project Layout

• src/main: Electron main process, provider orchestration, persistence, and workspace safety services.
• src/preload: Narrow IPC bridge exposed to the renderer.
• src/renderer: React UI, provider review surfaces, settings, and visual system.
• swift: macOS bridge daemon sources used by local release builds.
• scripts: Build, security, validation, signing, and packaging utilities.

See CHANGELOG.md for release history, and ARCHITECTURE.md, SAFETY.md, SECURITY.md, and TERMS_NOTES.md for more detail.