English · 简体中文
Official website · Quick start · Capabilities · Roadmap
Source Alpha · Apache-2.0 · Apple Silicon macOS · Node 22.19+
Not another chat window — an Agent console you can see into and keep in check.
What runs today. The workbench, controlled code editing, permissions, the Event Log, Checkpoints, Runtime Session rebuild, and Context Compaction are all working. The project has been exercised with real models across long tasks and recovery scenarios.
What doesn't, yet. The line above the fold is the product goal, not a finished claim. Broad compatibility across mainstream models has not been certified, the full long-task public test is still gated, and long-term memory, an in-house Loop, and the plugin ecosystem remain later work. This release is source-only and runs on Apple Silicon Macs. It is not recommended for production.
You need an Apple Silicon (arm64) Mac running macOS, Node.js 22.19.0 or newer, pnpm 11.0.0 or newer (the repository pins 11.7.0), Git, and whatever toolchain the project you point it at needs.
Start from a clean checkout of the Tag or Commit named in the Release:
pnpm install --frozen-lockfile
pnpm buildRun the Server and Runtime Worker in one terminal:
pnpm --filter @mindshell/server startRun the Web UI in a second:
pnpm --filter @mindshell/web devThen open http://127.0.0.1:5173.
The Alpha is distributed as source on GitHub. Anyone who finds the repository and wants to take part can — no invitation, no application, no allowlist.
The MindShell Server, the Runtime Worker, the Dot Workbench Web UI, ordinary Project Binding v1, a Provider you configure yourself, and — against a local project — reading, controlled editing, Permission, verification, Checkpoints, and continuing a task in the same Window.
This is not a Beta and not a stable release. There is no packaged macOS app this round. Intel Macs, Windows, Linux, Glass UI, Web Fetch/Search, the product MCP entry point, Recall/long-term memory, and ordinary Project Authority v2 are all outside its scope.
Point it at a small Git repository you can restore. Read each permission request before approving it, and keep your own version-control backup.
For a first run and for reproducible issue reports, we currently suggest DeepSeek official deepseek-v4-flash. That is test guidance, not a model allowlist — other Providers and models are worth trying, but they have not all had the same compatibility coverage.
Stop the candidate and record the Window ID if you hit any of these: an approval that only takes effect after a refresh, a final reply that only appears after a refresh, a finished task still showing as running, recovery repeating a side effect that had already settled, or a Window that cannot continue.
Setup isolation, cold restart, diagnostics, and safe issue reporting are covered in the Source Alpha participation and release guide.
Contact and feedback: Mindshell@126.com
A complete Web-first interface: windows, tasks, steps, permissions, and processes managed on one screen. Not a shell around a command line, but a console designed for long-term use.
Everything you see is rebuilt from the record underneath. Refresh the page, move to another machine, come back from a crash — you get the same thing.
Status: EARLY ALPHA
It finds relevant code through a bounded repository map and text or symbol candidates, then binds each structured edit to file state it has just read. Before committing it checks again; if the file moved underneath it, the edit stops rather than overwriting it.
Controlled edits keep the evidence needed to undo them, but only while the file has not drifted again. Changes made through the shell are recorded coarsely and carry no promise of one-click undo.
Status: EARLY ALPHA
R0–R4 risk tiers, a kernel-level Hardline, three approval modes. Let it run — the boundary is still the one you set.
Some things, once allowed, would make everything this system tells you afterwards worthless. They sit beyond the Hardline, where there is not even a “just this once”. Pro mode means fewer prompts, not fewer boundaries.
Status: EARLY ALPHA
The Event Log is the single source of truth. Tool calls, permission decisions, process state, and checkpoints are recorded natively, so a refresh restores from facts.
It never reads the wording of an answer to decide whether a step actually happened. Each step is recorded separately, and replaying the same record rebuilds the same screen.
Status: EARLY ALPHA
Long-term memory stays small, high-confidence, and traceable to source; Skills are indexed on demand with a fixed origin and version.
This is a direction, not a shipped feature. The Memory Working-Set and Skill foundations have implementations and offline gates behind them, but Recall/long-term memory is not enabled in this Alpha. How to judge a recall as useful, wrong, or merely irrelevant — and what to do with recalled material afterwards — is still being worked out.
Status: ROADMAP
Task Lease, Checkpoints, Runtime Session rebuild, and Context Compaction form a working foundation. Recovery reconciles events, files, permissions, and processes before continuing on a fresh session and lease. The complete long-task public test remains gated.
Recovery never replays a side effect whose outcome is unknown, and never hands authority back to the old executor. File drift, a pending permission, or unknown state pauses the task; only a clean reconciliation creates a new Runtime Session and leaseEpoch. A Checkpoint preserves the facts needed to recover, not a snapshot of your workspace, and Context Compaction turns older events into a traceable summary while keeping the recent tail exact.
Status: EARLY ALPHA
flowchart TD
UI["Dot Workbench"] --> API["Server / Local API"]
API --> PROJECTION["Projection"]
API --> STORE[("Event Store")]
PROJECTION --> STORE
STORE --> WORKER["Runtime Worker"]
WORKER --> KERNEL["Kernel / Tool Runner"]
KERNEL --> PROVIDER["Provider API"]
KERNEL --> PROJECT["Local Project"]
KERNEL --> PERMISSION["Permission / Guard"]
KERNEL --> CHECKPOINT["Checkpoint / Recovery"]
The Event Store is the account-scoped single writer for durable facts, sequence, Task lease, Checkpoint pointer, and the Projection outbox. Providers, Pi, Skills, plugins, and UI adapters get no direct authority over files, processes, networks, secrets, Permission, leases, or Event Store internals.
Pi Agent's lightweight Loop is an internal component that can be swapped out. MindShell owns Provider Transport, Turn, Context, Tool, Event, and recovery, so replacing the Loop later — or building our own — does not mean tearing down the facts and the safety foundation.
MindShell first settles whether an Agent can be trusted, controlled, and kept working over the long run; only then does it widen what the Agent can do. The road starts at traceable facts and runs through the long-task public test, memory, an in-house Loop, and a plugin ecosystem toward a customisable Agent platform for accountable work.
What follows is a direction, not a feature list. The status under each heading is what counts.
Foundation in place
MindShell treats the Event Log as the single source of truth inside an account. Model requests, tool calls, permission decisions, process-state transitions, file changes, checkpoints, errors, and recovery actions each become a replayable fact rather than something inferred afterwards from the wording of an answer.
That is what lets the interface be rebuilt and recovery proceed without relying on the model's account of events, and it keeps one set of identity, causality, and execution boundaries in place as the system grows.
Current mainline
The work now is moving long tasks from “they run” to “they stay accurate, bounded, and recoverable once the history grows”: paginated, rebuildable Task, Turn, and message views; removing unbounded Event reads; and closing the working-set boundaries around large Task handoff, Project authority, and recovery.
Current macOS evidence covers real Providers, multi-file programming, 60+ Turns, and crash recovery. The equivalent Windows gates for process handling, paths, credentials, and the browser are not complete, and this Source Alpha makes no cross-platform claim.
Next phase
MindShell's memory is not meant to push the whole history back into the context. The raw conversation archive stays the source of truth, and recall brings back a small amount of relevant, high-confidence material only when it is needed.
Progressive Recall is meant to load the lightweight index first, then a Memory Card, and only then the original excerpt. Ranking, retiring recall that turns out wrong or irrelevant, and the later handling of recalled material are all still being designed. Thin evidence must never let a new memory quietly become fact.
The value of memory is not in remembering everything, but in recalling what matters accurately.
After the memory system
MindShell runs Pi Agent's lightweight Loop today, but it is an internal component that can be swapped out. Providers, context, tools, permissions, Events, Checkpoints, recovery, and product state are held by MindShell itself, so replacing the Loop later does not mean tearing down the kernel.
Once the memory system and the current long-task and cross-platform gates close, MindShell plans to start on its own Loop. The aim is not to repeat the model-tool-model cycle, but to look for one that natively handles long-range planning, parallel work, recovery, reflection, verification, and tasks that cross domains.
The Loop can be replaced. The facts and safety boundaries are not replaced with it.
Planned · Ecosystem
MindShell plans one governed system for plugins, Skills, and MCP capabilities. Each capability records its origin, version, scope, and permission boundary, and keeps going through the same Tool Runner, Permission, Guard, and Event Log.
The default context carries only a lightweight capability index; when a task needs one, the matching plugin, Skill body, and resources load progressively. A long task pins the versions it uses, so recovery does not silently upgrade them.
Capability can extend. Permission cannot spread.
Planned · Platform
MindShell plans to extend the Event-first kernel into an Agent platform that can be tailored to a team, project, or business process. Each Agent may have its own tools, rules, permissions, Providers, and workflow while sharing the same boundaries for facts, identity, and execution.
The Event Log is more than a runtime log; it is the ledger for the chain of responsibility. Projections can be rebuilt, and crash recovery starts from durable Events, Checkpoints, the Task Lease, and reconciliation with the live workspace. Unknown state pauses for human handling.
The Agent can be customised. Its chain of responsibility cannot be customised away.
Planned · Vertical Loop proof
MindShell plans to use a closed-source derivative for automated editing and content packaging to test the replaceable-Loop architecture in another field. It would keep MindShell's Event-first kernel, memory, permission and tool governance, Checkpoints, and crash recovery, and replace only the Loop closest to task reasoning and execution.
That Loop would be specialised for the relationships among source materials, script and timeline state, multi-stage edits, media tools, review feedback, and convergence across versions.
The foundation stays general; the Loop and product become specialised.
Once the in-house Loop, the memory system, and the plugin system close the circle, MindShell plans to look into Multi-Agent/DAG execution, long-range planning with dynamic re-planning, cross-domain tool collaboration, automatic verification, and a broader entry point for personal work.
Coding stays the strictest and most useful place to prove reliability, but it is not meant to be the endpoint. The longer-term goal is an open Agent system that can carry complex work for individuals and teams.
MindShell is licensed under the Apache License 2.0. Third-party notices are listed in THIRD_PARTY_NOTICES.md and NOTICE.