MateClaw

English

中文

English

中文

Appearance

v2.0.0 ​

Stable · 2026-07-26 · Previous stable v1.8.0

The big things in this release ​

By the end of 1.x, MateClaw could get one digital employee to finish a whole job — lock a goal, run long tasks, deliver end to end. 2.0.0 answers the next question: how does a crew of employees work together?

The answer isn't "open more chat sessions" — it's full project machinery: Agent Teams. You create a team, assign a lead and members; tell the lead a goal and it breaks the goal into tasks on a shared task board; the dispatch engine hands tasks to members in parallel, dependencies orchestrate themselves, prerequisite results hand off automatically, and settled results are announced back to the lead for synthesis. You watch the whole thing — live board, task timelines, deliverable downloads, and you can jump into any member's child conversation to watch it execute word by word.

In one sentence: v2.0.0 is the release where MateClaw goes from "one person who gets things done" to "a team that collaborates".

The big things:

  • Agent teams and a shared task board. Teams / roles (lead · member · reviewer) / an eight-status kanban / blockedBy dependency orchestration / member-level parallel dispatch / settled results waking the lead. The Teams page shows everything: event-driven board, activity banner, task timelines, deliverables, approval gates, manual task creation.
  • An execution chain hardened for long tasks. Execution leases + runtime heartbeats eliminate double execution; cancel actually interrupts a running member session; requireApproval parks sensitive tasks at in_review for a human; failed / stale tasks retry.
  • Plans become the board. A Plan-Execute lead hands its whole plan over to the board — steps map to tasks, dependency chains become blockedBy, whatever can parallelize does; once everything settles, a deterministic resume gate routes to plan summary. A lead that can plan turns planning into orchestration.
  • Workspace isolation fully sealed. Channel conversation ids encode the channel, so two workspaces' chats can no longer merge into one conversation; same-named skills coexist across workspaces with install, storage and runtime resolution all workspace-scoped.
  • Long tasks in IM no longer look frozen. Magic commands on every channel (/new /clear /status /stop /model /help); WeCom's event-driven progress bubble — thinking state, live tool trace and elapsed time roll in place, morphing into the final answer; the sync IM path delivers per-stage narration as standalone messages.
  • Rewind and regenerate gain server-side semantics. "Rewind to here" genuinely truncates and recomputes aggregates; regenerate reuses the original question with no duplicate rows — identical behavior across admin console, WebChat and API.
  • Auto-approval misses are explainable. Audit rows record the auto-approval outcome and miss reason codes (most common: severity ceiling too low), with one-click grant creation from the audit page; forms use scope-typed pickers and reject dead configurations at creation.
  • LLM error recovery becomes policy. "Server overloaded" and "my key is rate-limited" get opposite treatments; Retry-After feeds backoff; evicted providers readmit on a TTL; jittered backoff prevents retry storms.

Plus: in-browser attachment preview (pdf / docx / xlsx / html / text in a glass-styled layer, pptx via server-side conversion fallback), single-source SKILL.md with console bundle-file management, the optional Mem0 plugin memory provider, the knowledge graph's relation schema whitelist, a configurable default workspace storage root, per-entry removal for the desktop local-tools whitelist, and custom-provider model discovery (modelsPath).

That's the list.

1. Agent Teams: one lead, a crew of employees, one board ​

Sub-agent delegation (delegateToAgent) is "one person temporarily calls a helper": synchronous, one-to-one, black-box. Real complex delivery looks like a project: break down tasks, declare dependencies, run in parallel, gate on approvals, archive deliverables, see who's doing what. 2.0.0 brings the whole machine:

  • Teams and roles: a group of employees plus one board; roles are lead / member / reviewer; one employee can join multiple teams.
  • The board: eight statuses (pending / in_progress / in_review / completed / failed / cancelled / blocked / stale), with the state machine guarded by conditional database updates — under concurrency the first successful writer wins.
  • The team_tasks tool: the lead creates tasks (with blockedBy and requireApproval), members report progress / submit results / attach deliverables, all actions role-gated. The roster is injected into member prompts, and the lead gets a live board snapshot every turn — long conversations can't drift into duplicate task creation.
  • The dispatch loop: a resident sweep plus immediate triggers after actions; each task runs in its own child conversation through the full agent graph, one task per member at a time; when prerequisites complete, the downstream dispatch envelope automatically carries their results and deliverables; settled tasks announce to the lead in debounced batches.

Data lands in five new tables (the mate_agent_team family, migrations V172–V174); the admin API lives under /api/v1/teams, and every validation failure returns a readable error.

See Agent Teams.

2. An execution chain designed for tasks that run for tens of minutes ​

  • Lease + heartbeat: dispatch takes a 60-minute execution lease, renewed automatically during the run; only genuinely lost tasks (process crash) expire to stale for safe re-dispatch — no more "re-dispatched while still running, two instances overwriting each other".
  • Cancel means interrupt: member child conversations register with the stream tracker; a cancel stops the run at the next node boundary — no more burning tokens to natural completion.
  • Approval gates: requireApproval tasks park at in_review for approve / reject on the Teams page.
  • Deliverables: members attach their docx / pptx / xlsx / pdf output to the task; the detail page offers downloads and announcements carry attachments — links no longer drown in truncated text.
  • Run visibility: every task links to the member child conversation's full transcript; opened mid-run it's a live typewriter. Lifecycle events land in mate_team_task_event and render as a timeline.
  • No polling: a team-level SSE event channel drives live board refresh and the activity banner; columns page their rows and headers show database-side true totals.

3. Plan-Execute goes team-native: plans hand over to the board ​

A Plan-Execute lead used to delegate step by step, serially, with the board none the wiser. Now the plan produced by the planning node is handed over to the board wholesale: steps map to tasks, step dependencies become blockedBy (a strictly-serial plan now parallelizes wherever it can), the plan parks (delegated) and the lead's turn ends normally; once every task settles, the announce wake-up passes a parked-plan resume gate that deterministically routes to the plan summary node, rebuilding context from task results and deliverables — the same "park in DB, resume in a fresh turn" shape the tool-approval flow already proved, with no checkpoint machinery.

4. Workspace isolation fully sealed ​

Two isolation defects with the same root cause — "the entity is workspace-scoped, but some key's generation forgot the workspace dimension" — fixed together:

  • Channel conversations no longer bleed: conversation id generation encodes the channel identity (migration V171 widens the id column). Same-type channels in different workspaces keep separate conversation rows even for the same external user.
  • Skills isolate at all three layers: install dedup and name uniqueness filter by workspace; disk directories encode the workspaceId so same-named skills own separate directories; runtime load / file reads / script runs / auto-redirect resolve only within "this conversation's workspace + builtin + global virtual" — one workspace's employee can neither read nor execute another's same-named skill.

5. Channels: long tasks visible, commands registered once for every channel ​

  • Magic commands: /new /clear /status /stop /model /help, intercepted by a unified dispatcher before the LLM — Chinese/English aliases, whole-message exact match, zero tokens. /model switches this conversation's model by name.
  • The WeCom progress bubble: the static "🤔 Thinking..." becomes event-driven — thinking state, live tool trace, per-stage rolling narration and elapsed time refresh in place; the first real content chunk reuses the same stream slot and the bubble morphs into the answer. The message-filter switches now genuinely control "should process messages be sent" instead of merely stripping inline tags.
  • Per-stage narration on sync IM: synchronous channels (WeCom, WeChat) deliver each stage narration as a standalone message; web SSE and the sync IM path share one per-turn stream accumulator, so execution metadata matches exactly on both sides.
  • Streaming reply hardening: keepalive, forced finish and context invalidation each in their place; generated files are actually delivered through the WeChat channel.

6. Rewind and regenerate: server-side semantics ​

  • Rewind to here: truncate back to a message — later messages are genuinely deleted and conversation aggregates recomputed; refresh or open from another client and you see the rewound state.
  • Regenerate: delete the trailing assistant answer and reuse the original user message — no more duplicate question per click, no more old answers resurrecting on refresh.
  • One semantics across the admin console, the WebChat widget and the API; conversations with an in-flight stream refuse to rewind first.

7. Auto-approval: hits visible, misses explainable ​

The most maddening pre-2.0 chain — a grant configured by intuition, tool calls still going to review, zero explanation anywhere — is now transparent:

  • Miss reasons get codes: grant exists but severity ceiling too low (the most common trap), no candidate grant, workspace mismatch, CRITICAL forced human review…
  • Outcomes land on audit rows (migration V170): auto-approved calls no longer show a misleading "needs approval", reviewed calls show why, and rows carry the real pending-approval id.
  • One-click grant creation from the audit page, pre-filled with tool, scope, and suggested ceiling.
  • Anti-footgun forms: scope-typed pickers, semantic ceiling hints, and cross-workspace dead configurations rejected at creation.

CRITICAL always goes to a human; safety-floor blocks stay non-negotiable.

8. LLM error recovery: classification is policy ​

  • Every error type carries its recovery attributes; the retry loop consumes policy instead of if-chains.
  • New OVERLOADED class: server overload (503/529) backs off on the same provider; a 429 on your own key rotates fast — previously conflated with opposite policies.
  • Retry-After / ratelimit-reset feed backoff duration and health cooldown — no more blind backoff.
  • Hard-evicted providers get TTL readmission, with provider-stated recovery times taking precedence — swap a key or top up the account and the system heals without a restart.
  • Randomized-jitter backoff prevents concurrent-session retry storms.

9. In-browser attachment preview ​

No more "download → find the file → open a local app" for a Word report the agent wrote: pdf / docx / xlsx / html / markdown / text / code open in a glass-styled preview layer, uploaded and AI-generated alike. PDF / Word / Excel render purely in the browser with nothing leaving your machine; pptx and legacy binary Office fall back to server-side PDF conversion, degrading gracefully to download when the converter is absent; HTML renders in a sandboxed iframe (scripts run; the opaque origin can't read your login state).

10. Skills: a single source of truth, fully managed from the console ​

  • Three-way SKILL.md reconcile: runtime (workspace file) and console (DB column) no longer fork — file edits ingest, DB edits materialize, conflicts resolve DB-wins with a .bak. What you see in the console is what the employee executes.
  • Bundle file management: scripts/, references/ and templates/ (newly a first-class bucket) are viewable, editable and deletable from the console; writes take effect immediately. Built-in skill files stay read-only.
  • Gate hardening: the pre-install preflight now genuinely probes dependency endpoint reachability; built-in skill scripts self-heal from the classpath when lost; zip entry names and content decode independently, ending CJK mojibake.

11. Memory: the optional Mem0 plugin provider ​

mateclaw-plugin-mem0 plugs Mem0 in as a fifth, plugin-based memory provider — the four internal providers are untouched; nothing is replaced. Semantic recall via prefetch, per-turn async sync (per-owner, ownerKey passed through as user_id), and failures on either side are swallowed by the plugin while the platform carries on. It's an optional community contribution: you self-host the Mem0 service; the local-first, zero-external-dependency default is unchanged. See Memory.

12. Also in this release ​

  • Knowledge graph relation schema — each KB may declare a closed subjectType → predicate → objectType triple whitelist; extraction keeps only matching relations and their entities (#509).
  • Wiki details — the system-prompt KB page listing is budgeted to the model window; global starter-pack templates are read-only; concurrent raw-material uploads stabilized with PostgreSQL-compatible ids.
  • Workspace storage — the default workspace storage root joins the settings page; desktop local-tools whitelist entries are individually removable (#512).
  • Models — custom providers discover models by protocol with a configurable modelsPath; each (provider, model) pair stays unique in the preference chain.
  • Frontend — lazy routes stay resilient under heavy agent runs (#515); ESLint 9 flat config; tool-call segments dedupe by toolCallId; the channel binding picker sees agents created after page mount.
  • Fixes — skill readers are excluded from tool-result spill so SKILL.md reaches the model intact; wiki_disabled agents no longer receive wiki prompt injection; datasource connection tests re-encrypt the password and discover PostgreSQL views; shell/SQL scripts pinned to LF.

Upgrade notes ​

Configuration is fully compatible. Your employees / skills / wiki / channels / cron jobs / workflows / triggers / goals all carry over. Flyway adds five migrations (V170–V174: the audit-row auto-approval outcome column, the widened conversation id column, the three team foundation tables, team_tasks tool registration, the task event timeline table), one per dialect, with existing databases auto-baselining.

If you're already running v1.8.0 in production:

  • Teams are opt-in. Create no team and nothing changes; delegateToAgent is untouched and the two coexist.
  • The channel conversation id format change affects only newly generated conversations; history gets a best-effort migration with a legacy fallback — nothing is lost on upgrade.
  • Same-named skills unlock: skills that previously failed to install with "already exists" across workspaces now install — make sure "one copy per workspace" is what you want.
  • Audit rows gain an outcome column — old rows aren't backfilled; it applies from the first post-upgrade call.
  • Magic commands intercept before the LLM: a message starting with a command (the slash form may carry arguments, e.g. /model qwen-max) no longer reaches the LLM; bare aliases match only as the entire message, so prose merely containing /stop is unaffected.

What this release means for you ​

If you have a job one employee can't finish — build a team: the lead decomposes, members run in parallel, dependencies orchestrate themselves, results synthesize automatically, and you watch the board or drop tasks on it yourself.

If you run long tasks over IM — the progress bubble narrates thinking and tool calls, /stop halts on demand, /model switches models on the spot; no more staring at a frozen "thinking…".

If regenerate ever burned you — history stays clean: rewind truly deletes, regenerate never duplicates, and every refresh agrees.

If you've configured an auto-approval grant that never fired — the audit row now tells you why, with a one-click shortcut to fix the grant.

If your provider misbehaves sometimes — overload-aware backoff, rate-limit-window awareness, TTL readmission; top up the account and it heals itself, no restart.

If you run multiple workspaces — channel conversations and skills are now sealed at every layer; bleed-through and cross-workspace execution are gone.

One last thing. ​

1.0 made it talk. 1.x made it work — lock a goal, run long tasks, deliver a whole job end to end.

2.0 makes it lead a team.

Decompose, dispatch, parallelize, approve, deliver, review — every mechanism a team needs, nothing missing; one board, fully transparent.

From "one person who gets things done" to "a team that collaborates".