Skip to main content

Contribute to Compositor

Use the same repository for implementation, tests and documentation. Repository documentation and comments are written in English.

Set up development​

Install Node.js 22.19.0 or later, Bun and ripgrep, then:

npm ci
npm run start -w @agent-compositor/app

See dependency maintenance for supported tool versions and provider settings to configure your model. Examples and tests use controlled providers where possible; running checks does not require putting real credentials in fixtures.

Choose the verification scope​

npm run typecheck
npm test -- packages/core/test/loop.test.ts
npm run marketplace:validate

Use the affected package tests while iterating. npm run test:ci runs the full TypeScript suite and coverage checks. Test discovery preserves Vitest's default exclusions and excludes the root dist/ output tree: retained evaluation workspaces and source snapshots are evidence, not maintained test files. For terminal behavior, follow the real PTY visual bench. Read evaluation guidance for scripted versus live model evidence and plugin certification for extension release requirements.

The Node 26 CI job also runs npm run visual:opentui-app, npm run visual:opentui-managers, npm run visual:opentui-navigation, npm run visual:opentui-cancellation, npm run visual:opentui-requests and npm run visual:opentui-controllers, the remaining configured-application scenarios in the bench guide, and npm run visual:opentui-wire with Chromium. Native release jobs repeat the application checks against a relocated archive's executable on each declared platform. The public grid API check instead loads that archive's exact renderer module through VISUAL_RENDERER_MODULE. Reports retain terminal captures and executable/module identities. Scenarios use isolated profiles and local fixtures; no live API key or paid request is required.

Update documentation with behavior​

When a change affects usage, configuration, a public contract, installation or operational limits, update the corresponding canonical page in the same change. Use npm run docs:impact -- BASE_REF to identify related pages from your Git diff. Record a concrete explanation in the PR when no documentation change is needed.

npm run gen
npm run docs:gen
npm run docs:check

Commit changed generated references alongside their inputs. The site build rejects broken repository links, document links, anchors and stale reference output. The example check verifies the first-plugin code through the actual app.

Read documentation maintenance for source ownership, previews and the publication workflow. A successful site build checks mechanics; reviewers also assess whether explanations match the changed behavior.

Submit and release​

Keep a focused diff, include the checks actually performed and explain observable behavior and material limits. Use meaningful Conventional Commits: fix for patches, feat for additions, and ! / BREAKING CHANGE: for incompatible changes. Include migration details in breaking commit bodies. Plugin versions, changelogs and matching development catalog metadata are prepared automatically in a release PR after main-branch pushes; do not hand-edit them for routine work. Read the plugin standard for review, preparation state and certification.

The main CI validates application behavior. The documentation workflow builds on pushes and pull requests, and publishes successful main-branch builds to GitHub Pages. Native application and independent plugin releases retain their separate release gates.

For the broader development target, use the 1.0 readiness gates. npm run typecheck also checks the evaluation runner, grading, profile and budget helpers. See evaluation commands before running live models; scripted integration checks and real model-quality evidence serve different purposes.