SharedState — Workspace Platform

Task execution “Shared tasks move forward over time, regardless of which human or agent continues the work.”
Workspace overview “A persistent workspace gives humans and agents one shared source of truth.”
Activity + Resident Agent “Every change is attributable, while the Resident Agent interprets what changed and why it matters.”
Decisions + Resident Agent “Confirmed decisions stay authoritative; the Resident Agent highlights gaps, conflicts, and pending direction.”
Import preview “A specialist Import Agent turns a public repository into a structured, reviewable workspace.”

Inspiration AI agents are becoming increasingly capable, but most collaboration still happens inside isolated conversations. That works for short tasks, but long-running projects need something more durable. The original idea started as a personal workspace where an AI agent could retrieve technical notes, project context, and decisions. Over time, the bigger problem became obvious: the real issue was not giving one agent more memory. It was giving humans and multiple agents a shared place where project state could persist independently of any single conversation. SharedState was built around that idea. Instead of treating chat history as the source of truth, the project stores tasks, decisions, knowledge, activity, proposals, and project context as structured workspace state. Agents can come and go, while the project remains. Agents come and go. Your workspace remembers.

What it does SharedState is a self-hosted workspace platform where humans and AI agents collaborate on the same persistent project state. Humans use the visual interface to review work, manage projects, and authorize important decisions. External AI agents connect through WebMCP and can directly discover workspaces, inspect structured context, read open work and activity, create and update tasks, add knowledge, and propose decisions without having to operate the interface through clicks. A persistent Resident Agent acts as a read-only continuity layer. It interprets the same workspace differently depending on what the user is looking at:

Tasks → priorities, blockers, dependencies, next work
Decisions → confirmed direction, proposals, conflicts, missing decisions
Knowledge → key facts, gaps, contradictions, open questions
Activity → what changed and why it matters These analyses are persisted, so simply navigating the interface does not repeatedly call the model. SharedState also includes a specialist Import Agent for bootstrapping existing public GitHub projects. Rather than ingesting an entire repository blindly, it progressively explores only the evidence it needs—README files, metadata, issues, documentation, configuration, and selected source files. The result is an evidence-backed preview containing suggested tasks, knowledge, decision proposals, open questions, risks, and provenance. A human reviews that preview before anything becomes authoritative workspace state. The core principle is simple: External agents act. Humans authorize. Resident agents interpret. Specialist agents bootstrap.

How we built it The frontend is built with React, Vite, and TypeScript, with a Node.js and Express backend. SQLite stores the durable workspace state, including:

workspaces
tasks
confirmed decisions
decision proposals
typed knowledge
activity history
agent runs
Resident Agent analyses
repository import previews and provenance WebMCP is implemented directly in the browser using document.modelContext.registerTool(...). The application currently exposes semantic workspace operations such as:
listing and inspecting workspaces
reading open work and activity
creating and updating tasks
adding typed knowledge
proposing decisions for human review
analyzing public repositories for import
retrieving structured import previews The important design choice was to expose domain operations rather than UI actions. An AI agent should not need to understand where a button is located; it should be able to ask the application directly for the operation it needs. The Resident Agent and Import Agent use the OpenAI Agents SDK, but have deliberately different responsibilities. The Resident Agent is read-only and focused on continuity. The Import Agent is temporary and focused on evidence gathering and project bootstrapping. Repository exploration is explicitly bounded by limits on model calls, files, issues, bytes, tokens, and estimated cost. For deployment, the application is packaged with Docker Compose. The React frontend and Express backend run together, while SQLite is persisted through a host-mounted data directory. The public deployment can sit behind Cloudflare Tunnel while the application itself only needs to expose HTTP internally. Challenges we ran into One of the biggest challenges was deciding what should actually be persistent. At first, it was tempting to make the agent conversation itself the memory layer. That quickly becomes difficult to reason about: context grows indefinitely, agents can disagree, and different agents do not naturally share conversation history. The solution was to make the structured workspace the source of truth instead. Another challenge was authority. AI agents should be able to contribute useful work without silently turning recommendations into project decisions. SharedState therefore separates decision proposals from confirmed decisions. An external agent can propose a direction, but human approval is what makes it authoritative. We also had to separate different kinds of agents clearly. The external WebMCP agent, Resident Agent, and Import Agent all interact with the same project, but they should not behave as one giant general-purpose agent. Each has a narrowly defined role and authority boundary. Repository importing created another challenge: how to understand a real project without sending the entire repository to a model. The importer uses progressive exploration instead. It maintains a compact understanding of the project, identifies the most valuable unresolved question, and reads another source only when that evidence is expected to answer something specific. Finally, WebMCP compatibility itself required some debugging. The site tools were correctly registered and visible, but tool invocation depended on the active model/runtime. This made it important to distinguish between tools being exposed by the site and actually being callable by the active agent session. Accomplishments that we're proud of The part we are most proud of is that two different agents can collaborate without ever speaking to each other. An external agent can modify the workspace through WebMCP. A human can review and approve its proposal. Later, the Resident Agent can immediately understand the consequences because it reads the same shared state—not the previous agent's conversation. That creates a very different collaboration model: No shared conversation. Shared state.

We are also proud that WebMCP is not being used as a thin wrapper around buttons. The application exposes a meaningful semantic surface for reading and changing real project state. Another major milestone was making the repository importer evidence-driven and human-reviewed. It can take an existing public project, selectively inspect relevant evidence, and transform that into a structured workspace without pretending that inferred information is confirmed fact. The distinction between facts, hypotheses, questions, proposals, and confirmed decisions is something we consider central to making agent collaboration trustworthy. Finally, SharedState is not tied to the included example projects. Users can create their own workspaces or bootstrap existing projects from GitHub, and those workspaces immediately become available to compatible external agents. What we learned The biggest lesson was that persistent AI collaboration is less about giving an agent infinite memory and more about designing good shared state. Long-term collaboration needs:

structured context
provenance
clear authority
reviewable changes
explicit uncertainty
durable history We also learned that the workspace should be more important than the agent. Models, conversations, and even agent implementations can change. If the important state remains structured and durable, a different agent can continue the work later. WebMCP reinforced this idea. A website can become more than something an agent visually operates. It can expose meaningful capabilities directly and let the agent participate in the application's domain model. The repository importer also highlighted that more context is not always better. A bounded agent that knows what it still needs to understand can often be more useful than sending an entire codebase into one huge context window. What's next for SharedState — Workspace Platform The next step is to turn SharedState from a strong single-user workspace into a broader coordination layer for long-running human-agent projects. Planned directions include:
richer workspace hierarchies and nested projects
permissions and multi-user collaboration
private repository support
controlled re-import and project refresh workflows
file and artifact support
integrations with external project systems
versioning and rollback of workspace state
richer provenance and evidence inspection
specialist research, coding, and QA agents
configurable authority policies for different agent roles Longer term, the goal is for SharedState to become a stable coordination layer that sits between humans, tools, repositories, and many different AI agents. The agents themselves may change. The project state should not.