From e71faf0685949a014feeef83c47facb2d9f4fcbf Mon Sep 17 00:00:00 2001 From: Shubham Mirashi <136989957+Shubham1905s@users.noreply.github.com> Date: Thu, 22 Jan 2026 22:28:29 +0530 Subject: [PATCH] docs: improve README with architecture, setup, and contribution details --- README.md | 266 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 167 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index 9ede0f16..d75df97a 100644 --- a/README.md +++ b/README.md @@ -1,125 +1,178 @@ # OpenWork -OpenWork is an **extensible, open-source “Claude Work” style system for knowledge workers**. +
-It’s built on top of opencode and lets you turn your opencode workflows into usable experiences for non-technical users. -Screenshot 2026-01-13 at 7 19 02 PM +**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) +OpenWork Main Interface -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) +
-## 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 Manager -image +## Quick Start +### Prerequisites -## Works on local computer or servers -Screenshot 2026-01-13 at 7 05 16 PM +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 +OpenWork Desktop Interface + +``` +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 ` - - 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: +OpenWork Local and Remote Modes +- Session lifecycle management +- Real-time event subscription +- Permission request handling +- Template persistence -```bash -pnpm dlx opkg install -``` +--- + +## 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**: `/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/.md` following the conventions in `.opencode/skill/prd-conventions/SKILL.md`. + +### Plugin Development + +OpenWork supports OpenCode plugins for extensibility: + +**Project Scope:** `/opencode.json` +**Global Scope:** `~/.config/opencode/opencode.json` + +Example plugin configuration: ```json { "$schema": "https://opencode.ai/config.json", @@ -127,29 +180,44 @@ You can still edit `opencode.json` manually; OpenWork uses the same format as th } ``` -## 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 +
-- 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/.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`. +
\ No newline at end of file