OWOpenWorkBuddy
DEVELOPER GUIDE · READ, CHANGE, VERIFY

Build a capability that fits the existing system.

A practical route through the repository, Agent runtime, tools, connectors, UI, test gates and release process. The source tree and detailed architecture notes remain the final reference.

1. Set up a local checkout

Use a supported Node.js version from package.json, then install the lockfile's exact dependencies.

git clone https://github.com/CatCatUncle/openworkbuddy.git
cd openworkbuddy
npm ci
npm start

Open the local address printed by the server. Keep personal configuration, API keys, task data and generated files outside commits. First-run details are in Install and launch.

2. Follow the architecture

server.js and application entry points wire services together. The Agent loop is in src/agent/; tools, model adapters, domain services, safety, storage and platform code live under src/.

  • src/agent/: Agent loop, tool dispatch and permission gates.
  • src/tools/: tool implementations grouped by responsibility.
  • src/core/: models, billing, safety, memory, extensions and automation.
  • src/domains/: account, content, media, library and other product domains.
  • src/server/routes/, src/cli/, src/im/, src/desktop/: application-specific entry points.
  • public/: HTML, styles and ordered classic scripts for the web UI.

Dependencies should flow down the documented layers. Keep sibling applications independent; put shared behavior in a lower-level module or inject it. Read Code architecture before moving modules.

3. Add or change an Agent tool

  1. Find the tool definition and dispatch path in src/agent/tools.js, then locate the implementation under src/tools/.
  2. Keep the schema narrow: define required fields, bounds, allowed paths and clear error behavior.
  3. Route file and command changes through existing permission and approval gates.
  4. Return useful results to both the model and UI. Keep secrets and unrelated file contents out of logs.
  5. Add focused positive and negative cases under test/, including inputs the tool must reject.

For HTTP endpoints, validate at the boundary and check ownership before reading or writing user data.

4. Add a Skill or connector preset

A Skill is a directory under skills/<name>/ with a skill.md file and frontmatter for its name and description. Keep the steps concrete, scoped and safe to repeat. Store helper templates and scripts beside it.

Connector presets live in src/core/ext/mcp-catalog.js. Commit placeholders and field names, never working credentials. Include environment variables, documentation URL, category and whether it needs a local command or remote URL. Cover missing commands, empty secrets, disabled connectors and malformed configuration.

See Skills, connectors and plugins for the full reference.

5. Change the front end

The main page is public/index.html. Its scripts are split into ordered files under public/js/ and share a classic-script global scope. Preserve load order and avoid inline event handlers.

  • Add visible text to public/js/i18n.js and verify Chinese and English modes.
  • Use existing design tokens, semantic controls, keyboard focus and accessible names.
  • Escape user input at the rendering boundary; render untrusted text through text nodes.
  • For multi-user features, verify server authorization as well as the UI.

6. Verify behavior and safety

Run the smallest relevant suite while iterating, then the release gate before publishing.

node test/all.js --only e2e
npm test

The full command includes architecture, permissions, localization, packaging and end-to-end checks. Some desktop and packaging suites take several minutes and require platform dependencies.

  • Never commit API keys, access tokens, local config, session exports, customer data or build artifacts.
  • Test rejected paths and permission boundaries along with the successful flow.
  • Use temporary test homes and fake credentials; do not connect tests to a personal account.
  • Update both changelogs when user-visible behavior changes.

Read Security baseline and Coding conventions.

7. Contribute and prepare a release

Keep a change focused, document its user-visible behavior and add a regression test. Before contributing, review the final diff for local paths and credentials.

Releases are tag-driven. Update the package version and changelog, run the full tests, then push a matching vX.Y.Z tag. The workflow checks the version, tests before building and uploads platform artifacts.

Contribution guideRepository workflow and review expectationsRelease guideTags, installers and publishing checksOpen an issueReport a reproducible bug or propose a changeRepository ★Read the source and star the project

Task, connector and review internals

For module boundaries, OAuth callback ownership, per-block rollback conflicts, browser recording privacy, team billing and focused test commands, read the task and connector development reference.

English UI checks call I18N.untranslated on visible controls and fail on missing translations. Mark user-authored text explicitly so it is preserved.