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
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, andrenderer/pages).src/read/(main): the read pipeline. Plain JavaScript with JSDoc types, so Electron andnodeload it with no build step.src/agent/(main): the agent tool layer, model loop and key store.src/cdp/: theCdpport 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 underdocs/superpowers/, and on main the September 2026 bugs and enhancements spec underdocs/spec/.build/: app icons, generated bynpm run iconsand 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.
-
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 neverandCSC_IDENTITY_AUTO_DISCOVERY=false(no certificate lookup), runs the smoke test against the packaged app, and uploads the.dmgand.exefiles. 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. - macOS Apple silicon:
-
Publish on Ubuntu: downloads all installers and runs
gh release create <tag>with the titleTroy <tag>, generated notes and a note about unsigned builds. If the release already exists, it uploads the files with--clobberinstead.
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.