Troy / Reference
Command line and environment
Reference for Troy's launch flags, environment variables and the npm scripts in the repository, confirmed against the source code.
On this page
Troy has no troy command-line tool. The app takes a small set of launch arguments, the repository has npm scripts for development, and on main node scripts/read.mjs reads a page from a running Troy.
Launch arguments are deliberately few. The only setting that changes what Troy will allow is the agent port (--cdp-port or TROY_CDP_PORT), and Troy does not remember it between launches, so an open debugging port is always something chosen for that launch.
Launch arguments
| Argument | Effect |
|---|---|
--cdp-port=<port> |
Open the agent port on 127.0.0.1 |
http://... or https://... |
Open this address in the first tab |
--cdp-port takes an integer from 1 to 65535. Any other value is ignored and no port is opened, without an error. It must be written with =; the next argument is not read as its value. When set, Troy also allows Chrome DevTools Protocol (CDP) connections from the http://127.0.0.1 origin and writes agent-endpoint.json into its profile.
Only the first argument that starts with http:// or https:// is used as a starting address.
On macOS, pass arguments to an installed app through open:
open -a Troy --args --cdp-port=9333 https://example.com/
From a source checkout, put them after --:
npm run browser -- --cdp-port=9333 https://example.com/
Troy’s own tests also launch it with Chromium’s --user-data-dir=<dir> to run against a throwaway profile.
Environment variables
The app
| Variable | Effect |
|---|---|
TROY_CDP_PORT |
Port to open when --cdp-port is absent |
TROY_TEST |
1 exposes a snapshot hook for the test suite |
TROY_TEST=1 adds a __troy.snapshot() function in the main process that reports the active tab, panel state, and each tab’s address, visibility and bounds. It exists for the tests; do not set it in normal use.
TROY_ENDPOINT_FILE is not read by Troy itself. It only tells scripts/read.mjs where to look, see below.
Build and test scripts
| Variable | Used by | Effect |
|---|---|---|
TROY_SMOKE_TIMEOUT |
npm run smoke |
Launch timeout in ms, default 240000 |
CSC_IDENTITY_AUTO_DISCOVERY |
electron-builder | false skips looking for a signing certificate |
Action scripts
| Variable | Default |
|---|---|
APPLY_FILL_CDP |
http://127.0.0.1:9222 |
APPLY_FILL_BROWSER |
/Applications/Helium.app/Contents/MacOS/Helium |
APPLY_FILL_PROFILE |
$HOME/.apply-fill/helium |
See Action scripts.
npm scripts
Run from a clone of the repository after npm install.
Running
npm run browser: start Troy from the source tree with Electron.
Checks
npm test: the Vitest suite. v0.1.5 has 127 tests, 36 of them driving a real Electron process. Main has 226 tests in 16 files, adding the read pipeline, history and the agent tool layer. Test files run one at a time.npm run lint: ESLint oversrcandtest.npm run typecheck:tsc --noEmit, which also checks the JavaScript throughcheckJs.npm run build: compile TypeScript todist/.npm run smoke: start the packaged app and check it opens a window, loads the new tab page and navigates. Takes an optional path to the executable.npm run stress: the 60fps gate. See below.
Packaging
npm run pack: unpacked app inrelease/, no installer.npm run dist:mac: macOS disk image (DMG).npm run dist:win: Windows installer and portable executable (EXE).npm run dist: both.npm run clean: deleterelease/. Every packaging script runs this first.npm run icons: regenerate the app icons from the mark. Needsrsvg-convert, andiconutilon macOS. The output is committed.
Action scripts
npm run detect:node scripts/detect.mjsnpm run fill:node scripts/fill.mjs
scripts/read.mjs has no npm script. Run it with node.
The read script (main only)
node scripts/read.mjs
node scripts/read.mjs --url <address> [--json] [--out <file>]
node scripts/read.mjs --fetch-mode=reap --url <address> [--json] [--out <file>]
Attaches to the running Troy through agent-endpoint.json, runs the read pipeline on one tab, prints the result and detaches.
| Option | Effect |
|---|---|
--url <address> |
Read the open tab at exactly this address |
--json |
Print the full document, not Markdown |
--out <file> |
Write to a file instead of printing |
--fetch-mode=reap |
Fetch with curl_reap, no browser |
- With no arguments, it reads the last
httporhttpstab in Playwright’s list, which may not be the tab in front. --urlis an exact string match and never navigates.--jsonand--outneed--urlas well. Without--urlthe script takes the first argument as the address, sonode scripts/read.mjs --jsonfails with “no open tab matches –json”.--fetch-mode=reaprequires--urland runspython3 -m curl_reap.cli get <address>. With--jsonit wraps the output as{ "url", "source": "reap", "markdown" }.- Exit codes: 0 on success, 2 when no tab matches or
--urlis missing for reap mode, 1 on any other error.
| Variable | Default |
|---|---|
TROY_ENDPOINT_FILE |
agent-endpoint.json in the macOS or Windows profile |
The default path is built for macOS and Windows only. On Linux, set TROY_ENDPOINT_FILE="$HOME/.config/Troy/agent-endpoint.json". See How Troy reads a page.
The stress test
node scripts/stress.mjs [--tabs 12] [--seconds 6]
Opens the given number of tabs, each running an animation and a stream of requests, then switches tabs, types into the address bar and reloads while counting frames in the chrome. It measures the chrome, not the pages, because the chrome is the surface a person touches.
It fails if the median frame works out to under 59 frames per second (fps), the 60fps target less a margin; if the 95th percentile frame is longer than 1.6 frames at 60fps (about 26.7 ms); or if any frame takes longer than 100 ms. Defaults are 12 tabs for 6 seconds. It also prints the main process’s memory use, and on main its private memory where Electron reports it.
The design document records one measurement on a 120Hz Apple silicon machine with 16 busy tabs: median frame 8.30 ms, p95 9.20 ms, worst 9.40 ms, zero stalls.