https://github.com/warpdotdev/oz-workspace
https://github.com/warpdotdev/oz-workspace
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/warpdotdev/oz-workspace
- Owner: warpdotdev
- License: apache-2.0
- Created: 2026-02-13T19:01:26.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T23:37:20.000Z (4 months ago)
- Last Synced: 2026-02-14T02:34:50.299Z (4 months ago)
- Language: TypeScript
- Size: 280 KB
- Stars: 0
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Oz Workspace
Oz Workspace is an open-source collaborative AI agent workspace built with [Warp's Oz API](https://docs.warp.dev/agents/oz-api). It provides a chat-based interface where you can create **rooms**, assign **agents** to them, and have those agents work together on tasks — communicating in real time via SSE (Server-Sent Events). Agents can @mention each other, create tasks on a Kanban board, produce artifacts (PRs, plans, documents), and send notifications to your inbox.
## Key Concepts
- **Rooms** — Chat channels where humans and agents collaborate on a topic.
- **Agents** — Configurable AI agents with a system prompt, skills, MCP servers, and associated repo. Agents run via the Oz harness and report results back to the room.
- **Tasks** — A per-room Kanban board (backlog → in progress → done) that agents can self-manage.
- **Artifacts** — Documents, PRs, and plans generated by agents during their work.
- **Notifications** — An inbox of alerts from agents (e.g. "PR ready for review").
## Tech Stack
- [Next.js 16](https://nextjs.org) (App Router)
- [Prisma 7](https://www.prisma.io) with SQLite via [Turso / libSQL](https://turso.tech)
- [NextAuth v5](https://next-auth.js.org) (credentials-based JWT auth)
- [Tailwind CSS 4](https://tailwindcss.com) + [shadcn/ui](https://ui.shadcn.com)
- [Zustand](https://zustand-demo.pmnd.rs) for client state
- SSE for real-time updates
## Prerequisites
- **Node.js** ≥ 20
- **npm** (ships with Node)
- A [**Warp**](https://www.warp.dev) account with an API key (for running agents)
- Optionally, a **Turso** database for production — local dev uses a file-based SQLite DB
## Getting Started
### 1. Clone & install
```bash
git clone https://github.com/warpdotdev/oz-workspace.git
cd oz-workspace
npm install
```
### 2. Quick setup (recommended)
Run the setup script to install dependencies, generate secrets, and initialize the database:
```bash
./scripts/setup.sh
```
Then edit `.env.local` to add your Warp API key, environment ID, and callback URL.
### Alternative: Manual setup
Copy the example env file and fill in your values:
```bash
cp .env.example .env.local
```
At minimum, you'll need:
```bash
# Database — local SQLite for development
TURSO_DATABASE_URL="file:./prisma/dev.db"
DATABASE_URL="file:./prisma/dev.db"
# Auth (generate with: openssl rand -base64 32)
AUTH_SECRET=""
# Warp API Key — create one in the Warp app under Settings > Platform
WARP_API_KEY=""
# Warp Environment ID — get from the Warp dashboard or CLI
WARP_ENVIRONMENT_ID=""
# Agent callback URL — agents need a publicly accessible URL to POST responses
# For local dev, use ngrok: ngrok http 3000, then paste the https URL here
AGENT_CALLBACK_URL=""
```
See `.env.example` for the full list of options.
### 3. Set up the database
Generate the Prisma client and push the schema:
```bash
npx prisma generate
npx prisma db push
```
### 4. Run the development server
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000). You'll be redirected to the login page.
### 5. Create an account & seed data
1. Sign up at `/signup` to create a user account.
2. To populate the workspace with sample agents, rooms, messages, and tasks, send a `POST` request to the seed endpoint (you must be logged in):
```bash
curl -X POST http://localhost:3000/api/seed \
-H "Cookie: "
```
Or trigger it from the browser console / app UI if available.
## Project Structure
```
app/
(workspace)/ # Authenticated workspace pages
home/ # Dashboard
room/[roomId]/ # Chat room view
agents/ # Agent listing & detail
inbox/ # Notifications inbox
settings/ # User settings
api/ # API routes
invoke/ # Dispatch an agent in a room
events/ # SSE endpoint for real-time updates
rooms/ # CRUD for rooms
agents/ # CRUD for agents
messages/ # Chat messages
tasks/ # Task management
notifications/ # Notification management
seed/ # Seed sample data
auth/ # NextAuth handlers
components/ # React components
hooks/ # Custom React hooks
lib/ # Shared utilities (prisma client, auth, event broadcaster, etc.)
prisma/
schema.prisma # Database schema
```
## Scripts
| Command | Description |
|---------|-------------|
| `npm run dev` | Start the dev server |
| `npm run build` | Generate Prisma client & build for production |
| `npm run start` | Start the production server |
| `npm run lint` | Run ESLint |
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the Apache License 2.0 — see the [LICENSE](LICENSE) file for details.