Skip to content
Troy

Troy / Project

Development and releases

How to work on Troy: set up a checkout, run the checks that run on every push, package the app, and how a version tag becomes a GitHub release.

On this page
  1. Set up
  2. Checks
  3. Repository layout
  4. Packaging
  5. How a release is made
  6. Updating the Homebrew cask
  7. Contributing

Troy’s working rule is that a change is real when a test drives the real application and shows it working. Most of this page follows from that: the tests launch Electron rather than mock it, they run on all three platforms, and a release is smoke-tested after packaging because some failures only exist inside the packaged app.

Set up

git clone https://github.com/velofy/troy.git
cd troy
npm install
npm run browser

Continuous integration (CI) uses Node.js 22. npm install may not download Electron’s binary or Playwright’s Chromium on its own, depending on your npm settings. CI fetches both explicitly, and you can do the same:

node node_modules/electron/install.js
npx playwright install chromium

Checks

These are the checks CI runs on every push to main or a build/** branch and every pull request to main, on macOS, Windows and Linux:

npm ci
npm run lint
npm run typecheck
npm test

On Linux, CI runs the tests under xvfb-run, because an Electron window needs a display.

Before a release, two more checks matter:

npm run smoke    # start the packaged app and prove it opens and navigates
npm run stress   # the 60fps gate

The tests drive the real application rather than mocking it. Several test files launch real Electron windows, so they run one at a time, with a 30 second test timeout and a 60 second hook timeout. Running them in parallel once made two files download the same Electron binary into the same path at once and corrupt it.

Main has 226 tests in 16 files (v0.1.5 had 127). scripts/read.mjs and the Apple Vision optical character recognition (OCR) engine have no tests yet.

Repository layout

  • src/browser/: the Electron app (main process, preloads, and renderer/ pages).
  • src/read/ (main): the read pipeline. Plain JavaScript with JSDoc types, so Electron and node load it with no build step.
  • src/agent/ (main): the agent tool layer, model loop and key store.
  • src/cdp/: the Cdp port and its Playwright implementation.
  • scripts/: action scripts, packaging hooks, smoke and stress tests, icon generation.
  • skills/ and .claude-plugin/: the Claude Code plugin.
  • targets/: host allowlists for the action scripts.
  • test/: Vitest suites, fixtures and a fixture server.
  • docs/: the product requirements document (PRD), the design document, the original spec and plan under docs/superpowers/, and on main the September 2026 bugs and enhancements spec under docs/spec/.
  • build/: app icons, generated by npm run icons and committed.

Packaging

npm run dist:mac
npm run dist:win

Output goes to release/, which each packaging script clears first. On macOS, scripts/after-pack.cjs ad-hoc signs the bundle and verifies the signature, and fails the build if verification fails. When a real Developer ID identity is configured, electron-builder signs with it and the hook steps aside.

How a release is made

Releases come from .github/workflows/release.yml. It runs on a pushed tag matching v*, or by hand from the Actions tab with a tag input.

  1. Build, one job per artifact:

    • macOS Apple silicon: electron-builder --mac --arm64
    • macOS Intel: electron-builder --mac --x64, on an Apple silicon runner with Rosetta installed first
    • Windows: electron-builder --win --x64

    Each job runs npm ci, builds with --publish never and CSC_IDENTITY_AUTO_DISCOVERY=false (no certificate lookup), runs the smoke test against the packaged app, and uploads the .dmg and .exe files. The smoke test exists because a build that will not open a window is worse than no release, and the packaged app is the only place to catch it.

  2. Publish on Ubuntu: downloads all installers and runs gh release create <tag> with the title Troy <tag>, generated notes and a note about unsigned builds. If the release already exists, it uploads the files with --clobber instead.

A release therefore contains Troy-mac-arm64.dmg, Troy-mac-x64.dmg, Troy-windows-setup-x64.exe and Troy-windows-portable-x64.exe. No Linux build is published, nothing is published to npm (the package is private), and the Homebrew cask is not updated by the workflow.

The version shown in the app comes from version in package.json, so bump it before tagging. On main it still says 0.1.5, even though main carries unreleased changes (see the Changelog). CHANGELOG.md does not list them yet.

Updating the Homebrew cask

The cask is Casks/troy.rb in velofy/homebrew-tap. After a release, set its version and the two sha256 values (Apple silicon and Intel disk images) to match the new files. It downloads from https://github.com/velofy/troy/releases/download/v<version>/.

Contributing

Open issues and pull requests at github.com/velofy/troy. A change is accepted when a test drives the real application and shows it working, which is one of the project’s stated principles. Keep the three-platform CI green.

Troy is MIT licensed.