Skip to content

Improved README with architecture, setup, and contribution guidelines #194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shubham1905s wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Improved README with architecture, setup, and contribution guidelines #194

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 167 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,155 +1,223 @@
# OpenWork

OpenWork is an **extensible, open-source “Claude Work” style system for knowledge workers**.
<div align="center">

It’s built on top of opencode and lets you turn your opencode workflows into usable experiences for non-technical users.

<img width="1292" height="932" alt="Screenshot 2026-01-13 at 7 19 02 PM" src="https://github.com/user-attachments/assets/7a1b8662-19a0-4327-87c9-c0295a0d54f1" />

**An extensible, open-source desktop application for agentic workflows**

Openwork is desgined around the idea that you can easily ship your
Built on top of OpenCode, OpenWork transforms complex CLI workflows into intuitive, guided experiences for knowledge workers.

It’s a native desktop app that runs **OpenCode** under the hood, but presents it as a clean, guided workflow:
- pick a workspace
- start a run
- watch progress + plan updates
- approve permissions when needed
- reuse what works (templates + skills)
<img width="1292" height="932" alt="OpenWork Main Interface" src="https://github.com/user-attachments/assets/7a1b8662-19a0-4327-87c9-c0295a0d54f1" />

The goal: make “agentic work” feel like a product, not a terminal.
[Download Latest Release](https://github.com/different-ai/openwork/releases) · [Report Issues](https://github.com/different-ai/openwork/issues) · [Request Feature](https://github.com/different-ai/openwork/issues/new?template=feature_request.md)

</div>

## Quick start
Download the dmg here https://github.com/different-ai/openwork/releases (or install from source below)
---

## Why
## Overview

Current CLI and GUIs for opencode are anchored around developers. That means a focus on file diffs, tool names, and hard to extend capabilities without relying on exposing some form of cli.
OpenWork is designed to bridge the gap between powerful agentic systems and user-friendly interfaces. It wraps OpenCode's capabilities in a clean, desktop application that makes automated workflows accessible to non-technical users while maintaining full extensibility for developers.

OpenWork is designed to be:
- **Extensible**: skill and opencode plugins are installable modules.
- **Auditable**: show what happened, when, and why.
- **Permissioned**: access to privileged flows.
- **Local/Remote**: OpenWork works locally as well as can connect to remote servers.
### Key Features

## What’s Included
- **Native Desktop Experience** - Built with Tauri for performance and security
- **Extensible Architecture** - Plugin system via OpenCode skills and packages
- **Real-time Progress Tracking** - Live streaming of execution plans and results
- **Permission Management** - Granular control over system access
- **Template System** - Save and reuse common workflows
- **Local & Remote Support** - Work locally or connect to remote OpenCode servers

- **Host mode**: runs opencode locally on your computer
- **Client mode**: connect to an existing OpenCode server by URL.
- **Sessions**: create/select sessions and send prompts.
- **Live streaming**: SSE `/event` subscription for realtime updates.
- **Execution plan**: render OpenCode todos as a timeline.
- **Permissions**: surface permission requests and reply (allow once / always / deny).
- **Templates**: save and re-run common workflows (stored locally).
- **Skills manager**:
- list installed `.opencode/skill` folders
- install from OpenPackage (`opkg install ...`)
- import a local skill folder into `.opencode/skill/<skill-name>`

---

## Skill Manager
<img width="1292" height="932" alt="image" src="https://github.com/user-attachments/assets/b500c1c6-a218-42ce-8a11-52787f5642b6" />
## Quick Start

### Prerequisites

## Works on local computer or servers
<img width="1292" height="932" alt="Screenshot 2026-01-13 at 7 05 16 PM" src="https://github.com/user-attachments/assets/9c864390-de69-48f2-82c1-93b328dd60c3" />
Before contributing to OpenWork, ensure you have the following installed:

- **Node.js** (≥ 18.0.0) with [pnpm](https://pnpm.io/) package manager
- **Rust toolchain** - Install via [rustup](https://rustup.rs/):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
- **Tauri CLI**:
```bash
cargo install tauri-cli
```
- **OpenCode CLI** (available on PATH):
```bash
opencode --version
```

## Quick Start
### Installation & Development

### Requirements
1. **Clone the repository**
```bash
git clone https://github.com/different-ai/openwork.git
cd openwork
```

- Node.js + `pnpm`
- Rust toolchain (for Tauri): install via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
- Tauri CLI: `cargo install tauri-cli`
- OpenCode CLI installed and available on PATH: `opencode`
2. **Install dependencies**
```bash
pnpm install
```

### Install
3. **Start development server**
```bash
# Full desktop app (recommended)
pnpm dev

# Web UI only
pnpm dev:ui
```

```bash
pnpm install
```
The application will be available in `packages/app` (UI) and `packages/desktop` (desktop shell).

OpenWork now lives in `packages/app` (UI) and `packages/desktop` (desktop shell).
---

### Run (Desktop)
## Architecture

```bash
pnpm dev
```
OpenWork follows a modular architecture with clear separation of concerns:

### Run (Web UI only)
### Desktop Application Interface

```bash
pnpm dev:ui
<img width="1292" height="932" alt="OpenWork Desktop Interface" src="https://github.com/user-attachments/assets/b500c1c6-a218-42ce-8a11-52787f5642b6" />

```
openwork/
├── packages/
│ ├── app/ # React-based web UI
│ └── desktop/ # Tauri desktop shell
└── docs/ # Documentation and PRDs
```

## Architecture (high-level)
### Core Components

- In **Host mode**, OpenWork spawns:
- `opencode serve --hostname 127.0.0.1 --port <free-port>`
- with your selected project folder as the process working directory.
- The UI uses `@opencode-ai/sdk/v2/client` to:
- connect to the server
- list/create sessions
- send prompts
- subscribe to SSE events
- read todos and permission requests
- **Host Mode**: Spawns OpenCode server locally with configurable workspace
- **Client Mode**: Connects to remote OpenCode instances via URL
- **Session Management**: Create, manage, and persist OpenCode sessions
- **Real-time Updates**: SSE-based `/event` streaming for live progress
- **Execution Timeline**: Visual representation of OpenCode todo progress
- **Skills Manager**: Install and manage OpenCode skills from `.opencode/skill`

## Folder Picker
### Integration Architecture

The folder picker uses the Tauri dialog plugin.
Capability permissions are defined in:
- `packages/desktop/src-tauri/capabilities/default.json`
The desktop application communicates with OpenCode via the `@opencode-ai/sdk/v2/client`, providing:

## OpenPackage Notes
### Local and Remote Mode Support

If `opkg` is not installed globally, OpenWork falls back to:
<img width="1292" height="932" alt="OpenWork Local and Remote Modes" src="https://github.com/user-attachments/assets/9c864390-de69-48f2-82c1-93b328dd60c3" />
- Session lifecycle management
- Real-time event subscription
- Permission request handling
- Template persistence

```bash
pnpm dlx opkg install <package>
```
---

## Development Workflow

### Available Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start desktop app in development mode |
| `pnpm dev:ui` | Start web UI only |
| `pnpm typecheck` | Run TypeScript type checking |
| `pnpm build` | Build all packages for production |
| `pnpm build:ui` | Build web UI only |
| `pnpm test:e2e` | Run end-to-end tests |

### Code Quality Standards

Before submitting a PR, ensure:
- `pnpm typecheck` passes without errors
- `pnpm test:e2e` completes successfully
- Code follows existing conventions (see existing components)
- No breaking changes without proper documentation

---

## Contributing

We welcome contributions! Please follow these guidelines:

### Before Contributing

## OpenCode Plugins
1. **Read the project philosophy** in `AGENTS.md` and `MOTIVATIONS-PHILOSOPHY.md`
2. **Understand the codebase** by reviewing existing components and patterns
3. **Set up your environment** using the prerequisites above

Plugins are the **native** way to extend OpenCode. OpenWork now manages them from the Skills tab by
reading and writing `opencode.json`.
### Making Changes

- **Project scope**: `<workspace>/opencode.json`
- **Global scope**: `~/.config/opencode/opencode.json` (or `$XDG_CONFIG_HOME/opencode/opencode.json`)
1. **Create a feature branch** from `main`
2. **Implement your changes** following existing conventions
3. **Add tests** if applicable
4. **Run quality checks**:
```bash
pnpm typecheck
pnpm test:e2e
```
5. **Submit a pull request** with clear description of changes

You can still edit `opencode.json` manually; OpenWork uses the same format as the OpenCode CLI:
### Adding New Features

For significant features, create a PRD (Product Requirements Document) in `packages/app/pr/<feature-name>.md` following the conventions in `.opencode/skill/prd-conventions/SKILL.md`.

### Plugin Development

OpenWork supports OpenCode plugins for extensibility:

**Project Scope:** `<workspace>/opencode.json`
**Global Scope:** `~/.config/opencode/opencode.json`

Example plugin configuration:
```json
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-wakatime"]
}
```

## Useful Commands
---

```bash
pnpm dev
pnpm dev:ui
pnpm typecheck
pnpm build
pnpm build:ui
pnpm test:e2e
```
## Security Considerations

- OpenWork binds to `127.0.0.1` by default in host mode
- Model reasoning traces and sensitive tool metadata are hidden from the UI by default
- Capability permissions are defined in `packages/desktop/src-tauri/capabilities/default.json`
- File picker uses Tauri dialog plugin with proper sandboxing

---

## Additional Resources

- [OpenCode Documentation](https://opencode.ai/docs)
- [Tauri Documentation](https://tauri.app/)
- [OpenPackage Registry](https://opkg.sh/)
- [Skill Development Guide](https://opencode.ai/skills)

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## Acknowledgments

## Security Notes
- Built on top of [OpenCode](https://opencode.ai/)
- Powered by [Tauri](https://tauri.app/) for the desktop experience
- UI built with [React](https://reactjs.org/) and modern web technologies

- OpenWork hides model reasoning and sensitive tool metadata by default.
- Host mode binds to `127.0.0.1` by default.
---

## Contributing
<div align="center">

- Review `AGENTS.md` and `MOTIVATIONS-PHILOSOPHY.md` to understand the product goals before making changes.
- Ensure Node.js, `pnpm`, the Rust toolchain, and `opencode` are installed before working inside the repo.
- Run `pnpm install` once per checkout, then verify your change with `pnpm typecheck` plus `pnpm test:e2e` (or the targeted subset of scripts) before opening a PR.
- Add new PRDs to `packages/app/pr/<name>.md` following the `.opencode/skill/prd-conventions/SKILL.md` conventions described in `AGENTS.md`.
**Made with ❤️ by the OpenWork community**

## License
[Support us](https://github.com/sponsors/different-ai) · [Follow on Twitter](https://twitter.com/differentai) · [Join Discord](https://discord.gg/openwork)

MIT — see `LICENSE`.
</div>