GrokTask

Host plans and reviews; Grok implements — watch it live, locally.

Codex or Claude Code own analysis, planning, diagnosis, review, and final judgment; GrokTask runs Grok Build via MCP as an implementation executor (code, tests, fix execution). Follow the real Thought → Tool → Reply stream in a native desktop UI.

English · 简体中文

English

What it is

GrokTask is a standalone, cross-platform local task runner. One binary provides CLI, MCP, a local daemon, and a native Tauri desktop UI (menu bar / tray popover and full window).

Key capabilities: host supplies plan/spec + acceptance criteria, then run/start for implementation; continue for relevant healthy follow-ups or review-directed repairs (host may start fresh when safer); async control survives process restarts via the local daemon; every task requires mode: read or mode: write (no defaults, no text inference); native timeline, plan bar, history, and settings.

Prerequisites

• Runtime: Grok CLI / Grok Build installed and authenticated (grok login or official auth). Tray UI needs a desktop session; MCP/CLI work headless.

• Development: Node.js ≥ 20 · pnpm 9.x (packageManager in package.json) · Rust stable (rust-version in src-tauri/Cargo.toml) · Linux: WebKitGTK and related deps (CI).

Build from source

No package-manager install is published yet:

pnpm install --frozen-lockfile
pnpm build
cargo build --manifest-path src-tauri/Cargo.toml --release --features custom-protocol
# full Tauri compile without OS installers:
pnpm tauri build --no-bundle

src-tauri/target/release/GrokTask
# or: src-tauri/target/<triple>/release/GrokTask

Production builds must use --features custom-protocol so assets are embedded. Prefer pnpm tauri build --no-bundle (not pnpm tauri build -- --no-bundle).

Usage

Roles (same binary)

GrokTask --help
GrokTask --version
GrokTask mcp                 # stdio MCP; no Tauri
GrokTask daemon run          # no WebView
GrokTask daemon status
GrokTask doctor
GrokTask app                 # desktop UI / ensure GUI host

Hidden roles: --gui-host, --task-supervisor (not everyday use).

CLI tasks

Mode is always explicit (read or write) — no default.

# Blocking: waits until final / partial / cancelled / failed
GrokTask run --mode read --cwd /absolute/path "Summarize this repo"

# Async
GrokTask start --mode write --cwd /absolute/path --submission-id <uuid> "Apply the fix"
GrokTask status <taskId>
GrokTask wait <taskId> <turnId> [--timeout SECONDS]
GrokTask cancel <taskId> --turn <turnId>

MCP (Codex / Claude)

GrokTask mcp   # server: groktask · tools: run, start, continue, status, wait, cancel

Install from Settings → Integrations, or:

GrokTask agents status
GrokTask agents mode codex mcp     # install / update
GrokTask agents mode claude mcp
GrokTask agents mode codex none    # remove GrokTask entry only
GrokTask agents mode claude none

Editors only touch the GrokTask MCP block; other servers and comments stay when the file is valid.

Desktop UI & doctor

Popover and full window share the task timeline. Tray visibility: off | active | always (login item only for always). Default off.

GrokTask doctor   # paths, Grok, daemon/GUI host, tray, agent integration

Data paths and safety

Default home (override with GROKTASK_HOME):

~/.groktask/   # config.json, history.sqlite3, daemon.*, gui-host.*, daemon.log, gui.log

Do not point automated tests at a real user ~/.groktask without an explicit temp home.

Development and verification

# Frontend
pnpm install --frozen-lockfile
pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build

# Rust
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets --all-features -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --all-features
cargo build --manifest-path src-tauri/Cargo.toml --release --features custom-protocol

# Tauri (no installer packages)
pnpm tauri build --no-bundle

Frontend gates only: pnpm ci:frontend. Acceptance (optional manual Grok smoke): docs/acceptance.md. Real Grok E2E is manual / opt-in, not required for ordinary CI.

Specs: docs/specs/ · Standalone refactor plan: docs/plans/standalone-refactor.md

Release status

CI quality gates run on push/PR. A separate release workflow (workflow_dispatch and version tags) builds unsigned binaries for aarch64-apple-darwin, x86_64-apple-darwin, x86_64-pc-windows-msvc, and x86_64-unknown-linux-gnu.

Artifacts are named with target and version and include SHA-256 checksums. They are not notarized and are not platform installers — no secrets, code signing, or store publishing are wired here. There may be no published GitHub Releases yet; use Actions artifacts or build from source. See .github/workflows/release.yml.

License

MIT — see LICENSE. Design inspiration from open-source ACP clients is conceptual only; this project does not copy GPL code.

Related MCP server: Grok Build Bridge

简体中文

它是什么

GrokTask 是一个独立、跨平台的本地任务运行器。同一个二进制提供 CLI、MCP、本地 daemon，以及原生 Tauri 桌面界面（菜单栏 / 托盘浮层与完整窗口）。

关键能力： 主机给出 plan/spec 与验收标准后用 run/start 委派实现；continue 用于相关健康 follow-up 或按审查意见修复（上下文不健康时可新开）；异步控制经本地 daemon 跨进程重启仍可用；每次任务必须 mode: read 或 mode: write（无默认值、不从文案推断）；原生时间线、计划条、历史与设置。

前置条件

• 运行时： 已安装并认证的 Grok CLI / Grok Build（grok login 或官方流程）。托盘 UI 需要桌面会话；MCP/CLI 可无 GUI。

• 开发环境： Node.js ≥ 20 · pnpm 9.x（package.json 的 packageManager） · Rust stable（src-tauri/Cargo.toml 的 rust-version） · Linux 需 WebKitGTK 等（见 CI）。

从源码构建

目前尚无包管理器上的正式安装发布：

pnpm install --frozen-lockfile
pnpm build
cargo build --manifest-path src-tauri/Cargo.toml --release --features custom-protocol
# 完整 Tauri 编译且不打系统安装包：
pnpm tauri build --no-bundle

src-tauri/target/release/GrokTask
# 或：src-tauri/target/<triple>/release/GrokTask

生产构建必须启用 --features custom-protocol。请用 pnpm tauri build --no-bundle（不要用 pnpm tauri build -- --no-bundle）。

使用说明

同一二进制的多种角色

GrokTask --help
GrokTask --version
GrokTask mcp                 # stdio MCP；不启动 Tauri
GrokTask daemon run          # 无 WebView
GrokTask daemon status
GrokTask doctor
GrokTask app                 # 桌面 UI / 确保 GUI host

内部隐藏角色：--gui-host、--task-supervisor（日常无需使用）。

CLI 任务

模式始终显式（read 或 write），没有默认值。

# 阻塞：直到 final / partial / cancelled / failed
GrokTask run --mode read --cwd /absolute/path "Summarize this repo"

# 异步
GrokTask start --mode write --cwd /absolute/path --submission-id <uuid> "Apply the fix"
GrokTask status <taskId>
GrokTask wait <taskId> <turnId> [--timeout SECONDS]
GrokTask cancel <taskId> --turn <turnId>

MCP（Codex / Claude）

GrokTask mcp   # 服务名：groktask · 工具：run, start, continue, status, wait, cancel

通过 设置 → Integrations 或 CLI：

GrokTask agents status
GrokTask agents mode codex mcp     # 安装 / 更新
GrokTask agents mode claude mcp
GrokTask agents mode codex none    # 仅移除 GrokTask 条目
GrokTask agents mode claude none

配置编辑器只改动 GrokTask MCP 块；文件合法时保留其他 server 与注释。

桌面 UI 与 Doctor

浮层与完整窗口共享任务时间线。托盘可见性：off | active | always（仅 always 使用登录项）。默认 off。

GrokTask doctor   # 路径、Grok、daemon/GUI host、托盘、Agent 集成

数据路径与安全

默认数据目录（可用 GROKTASK_HOME 覆盖）：

~/.groktask/   # config.json, history.sqlite3, daemon.*, gui-host.*, daemon.log, gui.log

自动化测试请勿在未使用临时目录时指向真实用户的 ~/.groktask。

开发与验证

# 前端
pnpm install --frozen-lockfile
pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build

# Rust
cargo fmt --manifest-path src-tauri/Cargo.toml --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets --all-features -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --all-features
cargo build --manifest-path src-tauri/Cargo.toml --release --features custom-protocol

# Tauri（不生成安装包）
pnpm tauri build --no-bundle

仅前端门禁：pnpm ci:frontend。验收（可选手动 Grok 冒烟）：docs/acceptance.md。真实 Grok E2E 为手动 / 可选，普通 CI 不要求。

规格：docs/specs/ · 独立化重构计划：docs/plans/standalone-refactor.md

发布状态

CI 在 push/PR 上跑质量门禁。独立的 release 工作流（workflow_dispatch 与版本 tag）为 aarch64-apple-darwin、x86_64-apple-darwin、x86_64-pc-windows-msvc、x86_64-unknown-linux-gnu 构建未签名二进制。

产物按 target 与版本 命名，附带 SHA-256 校验。产物未公证，也尚未打包为各平台安装器——本仓库未接入 secrets、代码签名或应用商店发布。目前可能尚无已发布的 GitHub Release；请使用 Actions 产物或从源码构建。详见 .github/workflows/release.yml。

许可证

MIT — 见 LICENSE。对开源 ACP 客户端的设计借鉴仅为概念层面；本项目不复制 GPL 代码。

Star History