Skip to content

Your always-on AI coworkers that move between text, calls, and Slack.

TypeScript

docs: introduce OpenDots and its first-release scope

Jerel John Velarde53890b295cf0
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4442e5e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+.opendots/
+artifacts/
+playwright-report/
+test-results/
+docs/superpowers/
+RESEARCH.md
+.DS_Store
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..06af72b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,17 @@
+# Contributing to OpenDots
+
+OpenDots is in early development. Prefer focused changes that improve the first complete research workflow: task creation, page reading, results, scheduling, and user control.
+
+For bugs, include the app mode, Node version, steps to reproduce, expected behavior, and actual behavior. Remove credentials and private page content from logs or screenshots.
+
+For features, describe the user workflow before proposing an implementation. Clearly separate functioning integrations from sample fixtures and planned work. Do not add controls that appear to connect a service when no adapter exists.
+
+Before opening a pull request:
+
+- Add regression coverage for changes to durable jobs, permissions, cancellation, or API behavior.
+- Run the repository's formatter, lint, typecheck, tests, and production build.
+- Exercise changed UI behavior and check narrow-screen layouts and keyboard access.
+- Update setup instructions if configuration or dependencies change.
+- Keep credentials, local databases, generated test reports, and internal planning notes out of commits.
+
+Project code is MIT licensed. Preserve applicable notices for any third-party code or assets you contribute.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..0c8d9a2
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenDots contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f2856d3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,102 @@
+<div align="center">
+
+# OpenDots
+
+### A little dot. A lot off your plate.
+
+**An open-source work agent inspired by OpenAI Dots.**
+
+Give your dot an ongoing responsibility. Follow its work, inspect its sources, and come back to the result.
+
+[Get started](#get-started) · [Features](#features) · [How it works](#how-it-works) · [Roadmap](#roadmap) · [Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+OpenDots brings a persistent agent, its workspace, and its activity into one interface. An original blue companion keeps you oriented while tasks run; conversations, research results, memories, and schedules stay available between visits.
+
+The first release focuses on **ongoing research**: give your dot a page to investigate, review a sourced result, and schedule it to check again. The server keeps working when you close the browser.
+
+> **Early development.** This repository is being built and verified. The feature list below defines the first-release scope; it is not yet a claim of a published, validated release. OpenDots is an independent project, not an OpenAI product or a complete reproduction of Dots.
+
+## Why OpenDots?
+
+- **Work that continues.** Tasks and schedules live on the server, beyond an open chat window.
+- **Work you can inspect.** See task activity, source pages, results, and failures.
+- **A companion you control.** Choose its name, manage its memories, and pause its work.
+- **An application you can change.** Inspect the source, run your own deployment, and extend the adapters.
+
+The architecture draws on [OpenMuse](https://github.com/CopilotKit/OpenMuse): durable tasks, a separate browser worker, visible activity, and rich results. OpenDots gives those patterns a focused research workflow and its own interface.
+
+## Features
+
+| Surface | First-release scope |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| Companion | Original blue character, editable name, visible activity and pause state, reduced-motion support |
+| Conversation | Submit research tasks and inspect their persisted progress and results |
+| Activity | In-progress, scheduled, and completed work, with visible failures and retry controls |
+| Research | Read a supplied public URL and synthesize a result with source links |
+| Agent browser | Separate read-only browser service with page capture and bounded navigation |
+| Schedules | Recurring checks that run while the application server is running |
+| Memory | Inspect and manage saved context; control whether research uses it |
+| Controls | Pause the agent, cancel tasks, and enforce supported research permissions on the server |
+| Sample mode | Clearly labeled fictional sources for trying the workflow without a model key |
+
+### Two explicit modes
+
+**Sample mode** lets you explore task creation, activity, persistence, scheduling, and controls without paid services. Its research content is fictional and labeled as such.
+
+**Live mode** uses the separate browser service and a configured OpenAI-compatible model endpoint. The initial live workflow requires a public URL; general web search is not included. Provider and browser failures appear as failed tasks, not sample results.
+
+## Get started
+
+Setup instructions will be finalized after the initial implementation passes its acceptance checks. The planned development environment is **Node.js 24**, **npm**, and a modern browser. Sample mode will not require a model key or Docker.
+
+The live browser service will have a Docker Compose configuration. Live model usage is billed by your configured provider. Recurring work requires the application server to remain running; closing its browser tab is supported, shutting down the server is not continuous execution.
+
+## How it works
+
+```mermaid
+flowchart LR
+ UI[React web app] --> API[Node API]
+ API --> DB[(SQLite)]
+ Worker[Persistent task worker] --> DB
+ Worker --> Policy[Execution-time controls]
+ Policy --> Browser[Separate browser service]
+ Policy --> Model[Configured model provider]
+ Worker --> Results[Results and task events]
+ Results --> DB
+```
+
+The database stores task state, schedules, messages, and settings. The worker claims due work, records progress, and persists results. The UI reads that state, so a page refresh does not restart the work. Browser access and model credentials stay behind the server boundary.
+
+OpenDots is initially a **single-owner application**. Local development binds to loopback. Public deployments require authentication, HTTPS, and an isolated browser service. See [Security](SECURITY.md) for the deployment boundary and reporting process.
+
+## Roadmap
+
+The first milestone is a verified research workflow with durable scheduling and an inspectable browser. Further milestones are:
+
+- Search-provider integrations for research without a supplied URL.
+- Slack and other messaging channels.
+- Connected-app adapters with explicit permission scopes.
+- File attachments and additional artifact viewers.
+- Voice and optional desktop integration.
+- Additional model-provider adapters and deployment options.
+
+These are planned capabilities, not working integrations in the first release. OpenDots does not currently offer local-computer control, arbitrary shell execution, payments, or autonomous outbound messaging.
+
+## Contributing
+
+Issues and pull requests are welcome. Start with [Contributing](CONTRIBUTING.md), explain the workflow you want to improve, and include a reproducible example for bugs. Report security issues through the process in [SECURITY.md](SECURITY.md).
+
+## Acknowledgments
+
+- [OpenAI Dots](https://help.openai.com/en/articles/20001530-getting-started-with-your-dot) provides the product inspiration.
+- [CopilotKit OpenMuse](https://github.com/CopilotKit/OpenMuse) provides the architectural reference.
+
+OpenDots has its own branding and character. References to other products describe inspiration and do not imply affiliation or endorsement.
+
+## License
+
+[MIT](LICENSE).
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..5f90767
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,20 @@
+# Security
+
+OpenDots is an early single-owner application. It is not a multi-tenant hosting platform or a security-audited autonomous agent.
+
+## Intended boundary
+
+- Run local development on loopback.
+- Protect remote deployments with authentication and HTTPS.
+- Keep the browser service isolated from the application host and private networks. Do not expose its port publicly.
+- Keep model keys and browser credentials on the server. Never commit `.env` files or local databases.
+- Treat page text, uploaded content, and model output as untrusted data, not authorization to change permissions.
+- The initial research workflow is read-only. Adding external writes requires a separate authorization and review design.
+
+Recurring work requires an available server. A sample run is not evidence that a live provider or deployment is safe or configured correctly. Review results before using them for important decisions.
+
+## Reporting
+
+Use the repository's private vulnerability reporting feature when available. If it is unavailable, open an issue asking for a private reporting channel without including exploit details, credentials, private URLs, or personal data.
+
+Do not post sensitive reproduction data in a public issue. This project does not currently promise a response-time SLA or offer a bug bounty.