Thanks for your interest in contributing to openclaw-cursor-cli!
git clone https://github.com/coo-quack/openclaw-cursor-cli.git
cd openclaw-cursor-cli
corepack enable pnpm # provisions the version `packageManager` pins
pnpm installThe install brings in openclaw even though it is only an optional peer
dependency — pnpm resolves those regardless of configuration — so nothing has
to be linked by hand for tsc and the unit tests to find
openclaw/plugin-sdk/*.
Run corepack enable pnpm rather than whatever pnpm happens to be on your
PATH. This repo's pnpm-workspace.yaml carries settings rather than a package
list — the file explains which and why — and pnpm 10 rejects that shape with
ERROR packages field missing or empty. The pinned 11.18.0 accepts it.
Node 22.22.3 or newer (engines.node in package.json), matching the
gateway's own floor — openclaw declares
>=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0, and pnpm test needs that package
installed because test/index.test.ts loads the plugin entry, which imports
openclaw/plugin-sdk/*.
Older Node fails in two separate ways, both worth knowing if you hit them:
- This package ships TypeScript sources rather than compiled JavaScript, so
Node has to strip types itself, which it does without a command-line flag
only from 22.18.0 onwards. Below that,
pnpm testdies before running a single test withERR_UNKNOWN_FILE_EXTENSION. - Passing
--experimental-strip-typesrescues 22.16.x and 22.17.x but not 22.6.x, whose type stripping can't parse TypeScript-only syntax such as the definite assignment assertion (let value!: T) intest/cursor-agent-wrapper.test.ts.
pnpm test # Run tests (node --test)
pnpm run typecheck # Type check with tsc
pnpm run lint # Check with Biome
pnpm run check # typecheck + lint + tests (full CI check)test/integration/ drives a real openclaw against this checkout: the plugin
is loaded from a path, a gateway is started, and a turn is routed through both
backends. It is not part of pnpm run check — it needs binaries a plain clone
does not have.
pnpm run test:integration:docker # build the image and run the suite in it
pnpm run test:integration # run against the openclaw already on PATHPrefer the Docker form. It is what CI runs, so a failure reproduces, and it
keeps openclaw and cursor-agent out of the host. Both are installed on
container start rather than baked into a layer, which costs about 15 seconds
and is what makes the suite an early warning for upstream changes.
Everything is scoped to a temp OPENCLAW_STATE_DIR and a workspace inside it;
nothing reads or writes ~/.openclaw. Two tests need the real cursor-agent
and assert only that its own authentication error comes back — they skip
themselves wherever credentials exist, so they never spend Cursor quota.
Run the container as a non-root user. As root, chmod 000 has no effect and
the permission-denied assertions in the unit suite fail; the image already
does the right thing, so this only matters if you override the entrypoint.
main
├── develop ← integration branch
│ └── feature/* ← new features and non-urgent fixes
└── hotfix/* ← urgent production fixes
feature/your-feature → develop → main (release)
- Branch from
develop:git checkout -b feature/your-feature develop - Open a PR targeting
develop - After review and approval, merge into
develop - When ready to release, open a PR from
develop→main
For urgent fixes that must go directly to production:
- Branch from
main:git checkout -b hotfix/fix-description main - Apply the fix and open a PR targeting
main - After review and approval, merge into
main - A backport PR to
developis created automatically by CI
If the backport PR has conflicts, resolve them manually before merging.
When bumping a version, open a PR from develop → main with:
- Update
versioninpackage.json - Review
README.md— update model/backend behavior notes if needed
After merging into main, release.yml automatically creates a git tag
and a GitHub Release.
- Follow Conventional Commits (
feat:,fix:,docs:,hotfix:, etc.) - All tests must pass (
pnpm test) - Lint must pass (
pnpm run lint) - One approval required to merge
Enforced by Biome. Run pnpm run lint to check and pnpm run fix to auto-format before committing.