Skip to content
Troy

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
  1. Launch arguments
  2. Environment variables
  3. The app
  4. Build and test scripts
  5. Action scripts
  6. npm scripts
  7. Running
  8. Checks
  9. Packaging
  10. Action scripts
  11. The read script (main only)
  12. The stress test

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 over src and test.
  • npm run typecheck: tsc --noEmit, which also checks the JavaScript through checkJs.
  • npm run build: compile TypeScript to dist/.
  • 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 in release/, 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: delete release/. Every packaging script runs this first.
  • npm run icons: regenerate the app icons from the mark. Needs rsvg-convert, and iconutil on macOS. The output is committed.

Action scripts

  • npm run detect: node scripts/detect.mjs
  • npm 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 http or https tab in Playwright’s list, which may not be the tab in front.
  • --url is an exact string match and never navigates.
  • --json and --out need --url as well. Without --url the script takes the first argument as the address, so node scripts/read.mjs --json fails with “no open tab matches –json”.
  • --fetch-mode=reap requires --url and runs python3 -m curl_reap.cli get <address>. With --json it wraps the output as { "url", "source": "reap", "markdown" }.
  • Exit codes: 0 on success, 2 when no tab matches or --url is 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.