📢 News

• We release our paper on OpenReview: SimPBL: A Multi-Agent Framework for Project-Based Learning, where comprehensive evaluation observes a 14% improvement in learner examination score.
• OpenMAIC-Project is under active development as the desktop entry point for the OpenMAIC project-based learning platform.
• The current client packages the local FastAPI endpoint, Electron renderer, workspace tools, and multi-agent collaboration interface into one desktop application.

✨ Why OpenMAIC-Project?

• Turn an open-ended project brief into an executable learning workspace.
• Coordinate multiple AI collaborators around roles, issues, documents, and project files.
• Keep tool execution local through the desktop client and sandboxed project containers.
• Support project-based learning with chat, code, browser, file, and terminal workflows in one app.

👋 Introduction

Let project ideas become workspaces, and let collaboration become learning.

OpenMAIC-Project is an Electron desktop application for AI-assisted project-based learning. It connects a local reasoning endpoint, project planner, Docker sandbox, multi-agent workspace, file explorer, code editor, terminal, and browser into a single learning environment.

Unlike one-way content generation tools, OpenMAIC-Project focuses on the full project lifecycle: users start from a natural-language brief, the planner designs roles and issues, and the workspace lets specialized collaborators help build, review, and iterate on project artifacts.

⭐ Key Highlights

• Project planner - Convert a project idea into structured roles, milestones, issues, and documents.
• Multi-agent workspace - Create one session per collaborator role, with isolated tmux sessions in the shared project sandbox.
• Local tool execution - MCP tools and workspace operations run through the client or Docker sandbox, not inside the LLM endpoint.
• Integrated development surface - Chat, code viewer/editor, file tree, terminal, browser, and project info are available in one desktop shell.
• Setup wizard - Check local infrastructure, configure integrations, and set up LLM providers before entering the main app.
• Packaged endpoint - Development runs the vendored endpoint from source; packaged builds include a PyInstaller endpoint binary.

🎯 Positioning

OpenMAIC-Project is designed for educational and research scenarios where students and teachers need more than generated text:

• How can a project brief become a concrete learning plan?
• How can AI collaborators divide work while preserving user control?
• How can local files, terminals, browsers, and sandboxed execution become part of the learning loop?

OpenMAIC-Project is therefore:

A desktop project-based learning client that turns AI planning and multi-agent collaboration into an executable local workspace.

🚀 Quick Start

✅ Prerequisites

• Node.js and npm
• Docker
• uv
• Python 3.13 or later
• Git

The setup wizard also checks the required infrastructure and can guide installation for missing tools.

1. 📦 Clone the Repository

git clone https://github.com/THU-MAIC/OpenMAIC-Project.git
cd OpenMAIC-Project

2. 🔧 Install Dependencies

npm install

The local endpoint is vendored in endpoint/ and is started automatically in development with:

uv run python main.py --port 18765

You normally do not need to run that command manually; the Electron main process starts the endpoint when the app launches.

3. 🧑‍💻 Start Development Mode

npm start

This launches Electron Forge with Vite and starts the local endpoint on port 18765.

4. 🛠️ Package the App

npm run package

To build distributable installers:

npm run make

For packaged builds, the endpoint binary is produced from the vendored endpoint/ source and copied into the app resources.

🧰 Development Commands

Command	Description
npm start	Launch the Electron + Vite development app
npm run package	Package the app for the current platform
npm run make	Build distributable installers
npm run build:endpoint	Build the local endpoint binary
npm run lint	Placeholder command; no linting is currently configured

🌟 Features

🧭 Use Cases

📊 Project Dashboard Resume active projects, inspect generated project cards, and jump back into learning workspaces.	📝 Project Planning Turn a natural-language brief into roles, issues, documents, milestones, and starter files.
🔍 Project Review Inspect the generated learning plan, milestones, micro-tasks, and AI teammate roles before continuing into the workspace.	🎓 Guided Learning Workspace Browse references, read project files, and work with the instructor and micro-task panel inside the learning workspace.

Scenario	What OpenMAIC-Project Provides
Project ideation	Turn a natural-language brief into project roles, issues, and documents
Guided learning	Let learners work with specialized collaborators instead of a single generic assistant
Implementation work	Edit files, inspect generated artifacts, run terminal commands, and browse references
Review and iteration	Continue planner conversations, approve design gates, and refine project outputs
Local experimentation	Run project work in Docker-backed sandboxes while keeping the desktop client in control

💡 Advantages

Dimension	Traditional AI Chat / Static Courseware	OpenMAIC-Project
Project structure	Often manual or implicit	Planner generates roles, issues, milestones, and documents
Collaboration	Usually one assistant thread	Multiple role-based collaborator sessions
Execution	External tools must be managed separately	File tree, Monaco editor, xterm terminal, browser, and sandbox are integrated
Local control	Tool execution may be remote or opaque	Tool execution happens through the client or sandbox, not inside the endpoint
Learning workflow	Focuses on final answers	Supports planning, building, reviewing, and iterating
Packaging	Often web-only	Desktop app with bundled local endpoint for packaged builds

🗂️ Project Structure

OpenMAIC-Project/
├── endpoint/                 # Vendored FastAPI local endpoint
│   ├── main.py               # Endpoint entry point
│   ├── pyproject.toml        # Python project metadata
│   └── build.spec            # PyInstaller build spec
│
├── resources/
│   ├── bin/                  # Packaged endpoint binaries, when present
│   └── icons/                # App icons
│
├── src/
│   ├── main/                 # Electron main process and IPC handlers
│   ├── preload/              # Preload bridge exposed as window.api
│   └── renderer/             # React application
│       ├── components/       # Shared UI components
│       ├── hooks/            # Endpoint, PTY, and workspace hooks
│       ├── pages/            # Setup, dashboard, planner, and workspace pages
│       ├── styles/           # Tailwind and theme styles
│       └── types/            # Renderer and IPC types
│
├── assets/                   # README images and static project assets
├── forge.config.js           # Electron Forge configuration
├── vite.main.config.ts       # Vite config for Electron main process
├── vite.preload.config.ts    # Vite config for preload
├── vite.renderer.config.ts   # Vite config for React renderer
└── package.json

🧩 Core Architecture

OpenMAIC-Project uses an Electron desktop architecture with a local FastAPI endpoint and a React renderer.

Layer	Responsibility
Renderer	React UI for setup, dashboard, project planning, workspace chat, code, browser, and info tabs
Preload bridge	Typed window.api interface for IPC access from the renderer
Main process	Endpoint lifecycle, HTTP proxying, SSE streaming proxy, filesystem access, PTY management, and system integration
Local endpoint	LLM reasoning, setup/config APIs, project planner APIs, and workspace session APIs
Docker sandbox	Per-project execution environment shared by planner and workspace collaborators

The main data flow is:

User brief
  -> Project planner
  -> Design confirmation
  -> Role-based workspace sessions
  -> Files, terminal, browser, and project artifacts
  -> Review and iteration

🔌 Endpoint API Surface

Namespace	Purpose
/setup/*	Check infrastructure, integrations, and model configuration
/project/planner/*	Create and continue project design conversations
/workspace/*	Create, connect, chat with, and manage multi-agent workspace sessions

📡 Streaming

Server-sent events are proxied through the Electron main process to avoid renderer CORS issues:

Renderer -> preload window.api -> ipcMain -> local endpoint -> SSE parser -> renderer events

The planner and workspace use different event contracts. Planner streams include project design events such as confirm_design and design_completed; workspace streams include session events such as token, tool_start, tool_end, ask_user, and file_access_request.

📦 Build and Packaging

Development mode starts the endpoint from source:

endpoint/ -> uv run python main.py --port 18765

Packaged builds use a PyInstaller binary:

resources/bin/openmaic-pro-local-endpoint-{platform}-{arch}

At runtime the app copies the packaged endpoint into:

~/.openmaicpro/bin/

Project files are stored under:

~/.openmaicpro/project/{projectId}/files/

Planner and sandbox workspace files are stored under:

~/.openmaicpro/planner/{projectId}/

🤝 Contributing

Contributions are welcome. Useful contribution areas include:

• Setup flow reliability
• Workspace session UX
• Endpoint integration
• File explorer and editor behavior
• Packaging and notarization
• Documentation and examples

Before opening a pull request:

1. Run the app locally with npm start.
2. Verify the setup wizard and endpoint startup path.
3. Check changed workspace flows against the endpoint and renderer contracts.
4. Keep UI changes consistent with the existing Tailwind, Material Design 3, and OpenMAIC-Project logo conventions.

📚 Citation

If OpenMAIC-Project or SimPBL is helpful to your research or project, please consider citing:

@misc{zhangli2026simpbl,
  title={SimPBL: A Multi-Agent Framework for Project-Based Learning},
  author={Zhang-Li, Daniel and Lim, Joy Jia Yin and Liu, Binglin and Tu, Shangqing and Yao, Zijun and Peng, Hao and Yu, Jifan and Li, Haoxuan and Hao, Zhanxin and He, Ye and Li, Zekun and Wang, Jiangyi and Hou, Lei and Xu, Bin and Cong, Xin and Liu, Zhiyuan and Liu, Huiqin and Zhang, Yu and Li, Juanzi},
  year={2026},
  note={ACL ARR 2026 January Submission},
  url={https://openreview.net/forum?id=OSOtsRi55D}
}

📄 License

This project is licensed under the MIT License.