# 📢 News
- We release our paper on OpenReview: [SimPBL: A Multi-Agent Framework for Project-Based Learning](https://openreview.net/forum?id=OSOtsRi55D), 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.
<img src="assets/readme/openmaic-pro-demo.gif" width="100%" alt="OpenMAIC-Project demo video"/>
## ⭐ 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
```bash
git clone https://github.com/THU-MAIC/OpenMAIC-Project.git
cd OpenMAIC-Project
```
## 2. 🔧 Install Dependencies
```bash
npm install
```
The local endpoint is vendored in `endpoint/` and is started automatically in development with:
```bash
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
```bash
npm start
```
This launches Electron Forge with Vite and starts the local endpoint on port `18765`.
## 4. 🛠️ Package the App
```bash
npm run package
```
To build distributable installers:
```bash
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
<table>
<tr>
<td width="50%" valign="top">
**📊 Project Dashboard**
Resume active projects, inspect generated project cards, and jump back into learning workspaces.
<img src="assets/readme/dashboard.png" width="100%" alt="OpenMAIC-Project dashboard screenshot"/>
</td>
<td width="50%" valign="top">
**📝 Project Planning**
Turn a natural-language brief into roles, issues, documents, milestones, and starter files.
<img src="assets/readme/planner.png" width="100%" alt="OpenMAIC-Project planner screenshot"/>
</td>
</tr>
<tr>
<td width="50%" valign="top">
**🔍 Project Review**
Inspect the generated learning plan, milestones, micro-tasks, and AI teammate roles before continuing into the workspace.
<img src="assets/readme/review.png" width="100%" alt="OpenMAIC-Project project review screenshot"/>
</td>
<td width="50%" valign="top">
**🎓 Guided Learning Workspace**
Browse references, read project files, and work with the instructor and micro-task panel inside the learning workspace.
<img src="assets/readme/learning-workspace.png" width="100%" alt="OpenMAIC-Project guided learning workspace screenshot"/>
</td>
</tr>
</table>
| 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
```bash
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:
```text
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:
```text
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:
```text
endpoint/ -> uv run python main.py --port 18765
```
Packaged builds use a PyInstaller binary:
```text
resources/bin/openmaic-pro-local-endpoint-{platform}-{arch}
```
At runtime the app copies the packaged endpoint into:
```text
~/.openmaicpro/bin/
```
Project files are stored under:
```text
~/.openmaicpro/project/{projectId}/files/
```
Planner and sandbox workspace files are stored under:
```text
~/.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:
```bibtex
@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.