univer-workspace and the Worktree pattern for agent edits to documents

One runtime for sheets, documents, slides and tables

The pitch is in a single sentence: a deployable knowledge and collaboration workspace built on the Univer Office SDK, bringing Sheets, Docs, Slides, relational tables, canvases and more into one shared runtime, with data and references staying connected across artifacts as the workspace changes.

That last clause is the whole product. Almost every office suite treats a spreadsheet and a presentation as separate file formats in separate applications, and a value in a sheet and a chart in a slide are two objects that agree only by coincidence. One shared runtime means a reference from a document into a cell is a reference, not a copy, and that editing the cell updates the document. For an agent that reads and writes several artifacts in one task, that is the difference between a coherent change and a pile of files that have drifted apart.

The artefact types listed are the interesting part for an evaluator. Sheets and Docs and Slides are the familiar three. Relational tables and canvases are not, and the topic list includes both a board concept and a database concept, which places this closer to a workspace tool than to an office suite. So the shape is closer to a document workspace that happens to have excellent spreadsheet support than to a word processor with tables.

The API is described as the Univer Facade API, and there is a separate Office SDK site and documentation site linked from the README. The relationship to structure is: the SDK is the library, this repository is the deployable application built on it. That distinction matters for the licensing discussion further down, because the two are not covered by the same terms.

Spreadsheet-based mini-apps are the feature that pushes this furthest. The README describes agents generating decision-making dashboards, interactive reports and business dashboards, where metrics, charts and controls on a web page are bound to cells and support data reads, writes and collaborative updates. A metric is a cell, and a chart reads a cell range. That is a coherent extension of the shared-runtime idea into the territory of application development, and it is the part of the product most likely to be either compelling or irrelevant depending on whether you build internal tools.

The Worktree, which is a pull request for documents

The most important design decision in this repository is one line in the architecture section, and it is worth describing precisely because the analogy explains both the design and its limits.

Agents work in isolated Worktrees, verify their changes, and hand the result to a person for review. Humans can continue editing and stay in control of what gets merged. The workflow the README gives is: create a Worktree, the agent edits and verifies an isolated draft, it becomes Ready, a human reviews it in the browser or the agent interface, then it is either merged or reopened, and only then does it reach trunk. Intermediate changes remain isolated from shared content until a person accepts them.

That is a pull request, and the mapping is exact. A Worktree is a branch, an isolated draft is a branch's contents, Ready is a pull request that has passed its checks, Merge is the merge, and Reopen is sending it back for more work. The reason to build it this way rather than letting an agent write directly to a shared document is not caution about damage. It is that document editing is not append-only. Merging two people who both rewrote the same paragraph is a semantic problem with no automatic answer, and if an agent and a person both edit the same document the same collision occurs. The Worktree makes that collision happen in a place where a person can look at it.

The reviewing surface is a real part of the design rather than an afterthought. The browser and the agent interface both offer review, which means the human decision happens where the document is visible, with the diff in front of them, and the agent interface adds a conversation beside it so the reasoning behind a change is available at the moment of acceptance.

Two limits follow from the analogy and are worth stating before you rely on it. A merge still needs a conflict story for concurrent edits to the same Worktree, and the README does not describe one. And a person reviewing every agent change is a per-change cost, so the economics only work if agents propose well-scoped changes rather than large ones. Neither is a reason not to use the pattern, and both are reasons to watch how it behaves on the first few real tasks.

Three entry points, one server, and what the server actually owns

The architecture diagram is small enough to hold in your head, and the shape is what tells you how the pieces relate.

There are three entry points. The Workspace Browser is the direct editing and collaboration surface, used to edit documents, organise Spaces and review changes. The Workspace Agent is a local conversation and review interface, which the README describes as a desktop application built on DSH, the DeepSeek Harness, sitting beside your documents. The Workspace CLI gives agents a structured way to load, understand, edit, validate and render the same content from a terminal.

All three connect to one Workspace Server, and the server's responsibilities are stated precisely. It resolves authoritative identity and permissions, owns the workspace product workflows, and composes the Univer Collaboration SDK. Below the server are three data stores in the diagram: product data, collaboration data, and blob and asset bytes.

The three-store split is a real architectural decision and it maps to three different access patterns. Product data is the structured content, which is queried and versioned. Collaboration data is presence, cursors and the real-time channel, which is high-frequency and short-lived. Blob data is file bytes, which is large and served differently. Collapsing them into one store would mean either a document edit writing through a blob interface or a cursor update taking a document lock, and neither is a good trade.

The consequence for a self-hoster is that identity is server-side and authoritative. The browser and the agent both authenticate to the server rather than to each other, and the README lists the integration options as password, GitHub, Discord or application OAuth login, with access control described as role-aware and node-aware, including anonymous viewing. Node-aware access control is the part that has no equivalent in a conventional document store, and it is a consequence of artifacts referencing each other: if a document embeds a cell from a private sheet, permission on the document cannot be evaluated without walking the reference.

The agent has a boundary worth noting. It is a local application, so its file references point to the machine it runs on, while workspace documents stay on the connected service. The agent can read your local repository and it can edit the server's documents, and the two are different stores with different trust models. A prompt that mixes both is the interesting case and the risky one.

Node 24, pnpm 11, and two ports that explain the dev setup

The requirements are Node.js 24 or newer and pnpm 11, and the manifest pins both more tightly than the prose does: engines requiring Node 24 or above, and pnpm 11.24.0 as the package manager. A Node floor of 24 is a deliberate choice rather than an accident, and it constrains which deployment environments you can use.

The quick start is four commands in two terminals, and the detail that matters is the two ports.

pnpm install
cp apps/workspace/.env.example apps/workspace/.env

The environment file is a copy of a checked-in example, which is the right default for a service that owns document storage and permissions. Then the server and the browser development server start separately:

pnpm workspace:dev:server
pnpm workspace:dev:web

You open the browser at 127.0.0.1 on port 5173, and Vite supplies hot module replacement and proxies both API and WebSocket traffic through to the server on port 3020. So in development the two processes are genuinely separate, and the proxy is what makes that invisible to the user.

That arrangement exists because collaboration needs a WebSocket channel and a hot-reloading bundler does not want to proxy one, and it is the standard reason an Electron-free application server splits this way. The production path is different, and the README describes it: the server can serve the latest built browser from port 3020 when a build output directory exists, so a deployment is one process and one port. Its product API documentation is then available at a documentation path and an OpenAPI specification path on the same port.

The repository also has a Makefile with a single image push target, which builds from a Dockerfile in the workspace application directory and pushes to an Alibaba Cloud container registry under a namespace and repository name with a configurable tag. That tells you the project's own deployment target is a Chinese cloud registry, which is consistent with a company publishing a Chinese-language README alongside the English one.

The rest of the monorepo is conventional and competent. There is an apps directory for the applications, a packages directory, a skills directory, an observability directory, a patches directory for patched dependencies, and a tsconfig base file. The build, typecheck and test scripts all delegate recursively across the workspace, and there is a separate update script for the Univer SDK dependencies with its own test.

Apache-2.0 in the repository, a separate licence variable in the image

The licence situation needs two sentences rather than one, and the second is in the Makefile.

The repository states Apache-2.0, in the badge, in the manifest and in the licence file. That covers the code in this repository.

The image push target, however, passes a build argument named for an Univer workspace browser licence, sourced from an environment variable of the same purpose, and bakes it into the image. That is the entire content of the relevant Makefile line: a Docker build with a licence build argument, an application Dockerfile, a registry, a namespace and a tag.

What that means is that the Univer SDK is not under this repository's licence. A viewer licence being injected at image build time is the shape of a commercially licensed dependency, and a self-hoster therefore has two sets of terms to reconcile, not one. The repository does not explain the SDK's terms in the README excerpt, and the SDK has its own site separate from the application.

This is worth resolving before you build anything, because the answer determines whether the Apache-2.0 grant on this repository is the licence of your deployed product or whether it is the licence of part of it. The honest position is that the README does not settle the question and the SDK's own terms are the place to look. This is a description of what the files show rather than legal advice.

There is a second, softer observation in the same area. The topics include local-first, and the architecture puts a server between the client and everything, with the server owning identity, permissions and three data stores. Those are not contradictory, since local-first and self-hosted are different claims, and a workspace that needs a server to resolve permissions and compose real-time collaboration is a server application by any reasonable reading. Anyone choosing this because they want offline-first editing should check whether the deployment story actually delivers that, because the diagram in the README does not suggest it does.

An agent surface that is entirely release candidates

The release list explains more about the project's state than the README's confident tone suggests.

All three recent tags are for the agent, all are version 0.1.0, and all are release candidates. The first was 0.1.0-rc.1 in September 2026, the second rc.3 later the same day, and the third rc.4 two days after that, with the last push to the repository hours after the newest tag. The repository is not archived and the last push was on 2026-09-28.

So the pattern is a pre-1.0 agent shipping rapid release candidates while the surrounding workspace is stable enough to have a quick start that works. Nothing in the README says this is the intent, and the release titles, which read as workspace agent versions, are the only evidence. It is a reasonable way to ship an agent surface, where the interface you are iterating on is the conversation and the review, and a version number that moves tells you the interface will too. It also means an adopter who pins a version is pinning something that will be replaced within weeks.

The two related repositories are the DSH runtime the agent is built on, and the Univer SDK the whole thing renders with. The manifest has a dedicated script for updating SDK dependencies and a test for that script, which tells you the SDK version is a moving part the project manages actively rather than a pinned dependency it updates rarely. That is the right arrangement for an SDK that ships frequently, and it is also the arrangement where an SDK change can alter behaviour in your deployment without a change to this repository.

The agent is described as being able to inspect data, render screenshots and PDFs, run layout checks, and discover version-matched skills and APIs offline. That last capability is interesting and slightly paradoxical in a project whose agent can read local files: an agent that renders a document also needs to know what the document should look like, and a local skill library is how it checks. Rendering a document and then visually verifying the render is a loop that does not need a human, which is the strongest argument for the agent surface existing at all.

For an evaluator, the practical reading is that the workspace and the CLI are the stable part and the agent is where to expect breakage. Testing the merge workflow through the CLI first, and treating the agent as an addition once the merge path is understood, is the lower-risk order.

Editorial conclusion

Adopt univer-workspace if you need a self-hostable office suite where documents, sheets and presentations live in one runtime with cross-artifact references intact, and if you want agents editing those documents without a person losing control of trunk. Do not adopt it expecting a stable agent surface, since every recent tag is a 0.1.0 release candidate, and settle the SDK licensing before you build a deployment, because the repository is Apache-2.0 while the container build takes a separate licence variable for the Univer SDK. Verify first by starting the server and browser, creating a Worktree from the CLI, and confirming that changes stay invisible to other users until you merge.

Frequently asked questions

Official sources

1. dream-num/univer-workspace on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases