Contributing to Clickyy

August 13, 2026 · View on GitHub

Thanks for helping improve Clickyy — bug reports, feature ideas, docs fixes, and pull requests are all welcome.

Prerequisites

  • Node.js ≥ 20 — via Homebrew (brew install node) or nvm.
  • macOS 12+ — Clickyy is macOS-only. The full app needs a Mac, but the headless test suite can run anywhere Node runs.
  • Xcode Command Line Tools — for Git and the release tooling (xcode-select --install).

Development workflow

git clone https://github.com/jayamitkatariya/clickyyy.git
cd clickyyy
npm install

npm run dev        # run in development with hot reload
npm run typecheck  # TypeScript check
npm test           # headless agent-loop / command-safety tests
npm run build      # compile main + preload + renderer
npm run dist       # build a local, unsigned .dmg/.zip in release/

Tests

The test suite lives in scratch/ and runs headlessly — no signed app, screen recording, or macOS GUI interaction needed:

npm test

This runs scratch/agent-loop.test.mjs and scratch/run-command.test.mjs. They bundle real source files with esbuild and stub electron/electron-store, so they can exercise the agent state machine and command-safety guards in plain Node.

If you touch agent planning/execution or terminal-safety behaviour, add a test that covers the change. The existing harness is the pattern to follow.

Code layout

src/
├── main/            # Electron main process: app bootstrap, IPC, agent loop
│   ├── providers/   # MiMo / OpenAI / Anthropic providers
│   └── workspace/   # .clickyy/ project-memory detection + storage
├── preload/         # contextBridge IPC (typed, narrow surface)
├── renderer/        # React overlay UI
└── shared/          # types + pure command-safety helpers shared across processes

Guidelines

  • Keep the typed IPC boundary intact: the renderer talks to window.clickyy only through src/shared/api.ts and src/preload/index.ts.
  • Keep API keys in the main process. The renderer should only ever see "configured yes/no", never key material.
  • Prefer small, focused changes. Don't refactor unrelated code in the same PR.
  • Run npm run typecheck, npm test, and npm run build before opening a PR.

License

Clickyy is MIT licensed. By contributing you agree to release your contribution under the same terms.