RetrySight Lite
License: Apache-2.0
Local-first console for coding-agent retries, tokens, cost estimates, and agentic metrics. Free, Apache-2.0, and everything stays on your machine.
Coding agents retry more than you'd think: edit loops, failed tests, rejected diffs, context compaction. Vendor dashboards show total tokens, not how many were spent on retries. Lite reads the logs your agents already write and shows you.
Install
macOS / Linux:
curl -fsSL https://app.retrysight.com/install.sh | bash
Windows (PowerShell):
irm https://app.retrysight.com/install.ps1 | iex
Or download the .dmg, .tar.gz, or .zip from retrysight.com/lite. No Node.js or Docker needed.
Open the app, then use Cursor, Claude Code, or Codex as usual. Sessions and retries appear as the collectors read the local logs. The local API (REST, GraphQL, and MCP) listens on 127.0.0.1:18081, loopback only.
What's in it
Recommended UI: native Flutter desktop app in [app/](app/) (macOS, Windows, Linux).
One Node.js backend process:
- In-process collectors (Cursor, Claude Code, Warp/Oz, Windsurf, Cline, Aider, Continue, GitHub Copilot → SQLite)
- Loopback REST / GraphQL / MCP for tooling
- Terminal TUI (blessed) — legacy; use the Flutter app instead
No separate agent service. No Docker required.
Build from source
Flutter desktop (recommended)
git clone https://github.com/arkaprava/retrysight-lite.git
cd retrysight-lite
cd manager && npm install && npm run build
cd ../app && flutter pub get && flutter run -d macos # or windows / linux
On first launch the app auto-detects ../manager, reads the admin token from secure storage (or manager/data/admin-token), and starts the headless backend if needed.
See [app/README.md](app/README.md) for build and configuration details.
Dev from source (API only)
npm install
npm run install:app
npm run dev:api # headless API + collectors (used by Flutter app)
API defaults to 127.0.0.1:18081. Data and secrets live under manager/data/ in development.
Dev from source (terminal TUI — legacy)
cd manager && npm install
npm run dev # TUI + API + collectors
| Key | Action |
|---|
1–3 | Dashboard / Tasks / MCP |
f | Cycle filter field |
[ ] | Change filter value |
Enter | Task timeline |
r | Refresh |
q | Quit |
Packaging (maintainers)
Build artifacts land in release/.
Self-contained desktop app (Flutter + embedded backend, no Node for users):
npm install && npm run install:app
npm run dist:app:all # macOS + Linux on this Mac (Docker)
npm run manifest && npm run stage:cdn # refresh manifest + cdn-staging/
One-line install for users (after uploading release/cdn-staging/ — see docs/DOWNLOADS.md):
curl -fsSL https://app.retrysight.com/install.sh | bash
Output: release/app-<target>/ and release/retrysight-lite-app-<target>.tar.gz (or .zip on Windows).
| Build host | macOS app | Linux app | Windows app |
|---|
| macOS | native | Docker | GitHub Actions |
| Linux | — | native | GitHub Actions |
| Windows | — | — | native |
GitHub Actions (all platforms, after pushing .github/workflows/release-desktop.yml):
gh workflow run release-desktop.yml -f target=all
gh workflow run release-desktop.yml -f target=linux-x64
gh workflow run release-desktop.yml -f target=win-x64
Download artifacts from the Actions run page.
Backend-only headless service:
npm install
npm run install:app
npm run dist:mac:arm64 # or: dist:mac / dist:linux / dist:win / dist:all
| Platform | Self-contained app | Backend-only | Install |
|---|
| macOS Apple Silicon | release/app-macos-arm64/ + .tar.gz | release/macos-arm64/ + .tar.gz | ./install-macos.sh (LaunchAgent) |
| macOS Intel | release/app-macos-x64/ + .tar.gz | release/macos-x64/ + .tar.gz | ./install-macos.sh |
| Linux x64 | release/app-linux-x64/ + .tar.gz | release/linux-x64/ + .tar.gz | ./install-linux.sh (systemd user unit) |
| Windows x64 | release/app-win-x64/ + .zip | release/win-x64/ + .zip | .\install-windows.ps1 (Scheduled Task) |
Defaults after install:
- API on 127.0.0.1:18081
- Data + secrets under the install prefix (
~/Library/Application Support/RetrySightLite on macOS, ~/.local/share/RetrySightLite on Linux, %LOCALAPPDATA%\RetrySightLite on Windows)
admin-token and agent-api-key auto-generated on first run
Security defaults
| Setting | Default |
|---|
| Bind host | 127.0.0.1 (set RETRYSIGHT_HOST=0.0.0.0 for LAN — intentional only) |
| Host-header guard | When bound to loopback, non-127.0.0.1/localhost Host headers are rejected (403) — blocks DNS rebinding |
| Admin APIs | Authorization: Bearer $RETRYSIGHT_ADMIN_TOKEN or X-RetrySight-Admin-Token |
| Public | GET /api/v1/health only; all other REST and GraphQL endpoints (incl. collectors) require admin |
| Ingest (optional remote) | X-Agent-Api-Key (scrypt-hashed; verified via key_prefix lookup) |
| CORS | Disabled (loopback browser origins only for web dev) |
| GraphQL introspection | Off (RETRYSIGHT_GRAPHQL_DEV=1 to enable) |
| Secrets | Auto-generated into data dir if unset / weak (min length enforced) |
| Data-at-rest permissions | Data dirs 0700, SQLite DB/WAL and collector buffer files 0600 (owner-only) |
| Token storage (Flutter app) | Admin token in OS secure storage (Keychain / DPAPI / libsecret), never plaintext prefs |
| TLS | Optional — RETRYSIGHT_TLS_CERT + RETRYSIGHT_TLS_KEY |
| Rate limiting | On by default (20 req/min GraphQL, 60/min ingest, 100/min admin) |
| Data retention | RETRYSIGHT_RETENTION_DAYS (0 = never delete) |
| API key expiry | expires_at column supported (set programmatically) |
# Dashboard (admin)
curl -H "Authorization: Bearer $(cat manager/data/admin-token)" \
http://127.0.0.1:18081/api/v1/dashboard
# Optional HTTP ingest (remote collectors)
curl -H "X-Agent-Api-Key: $(cat manager/data/agent-api-key)" \
-H 'content-type: application/json' \
-d '{"name":"x","developerEmail":"x@local","hostname":"h"}' \
http://127.0.0.1:18081/api/v1/ingest/heartbeat
Report security issues privately — see [SECURITY.md](SECURITY.md).
MCP
Set RETRYSIGHT_URL and RETRYSIGHT_TOKEN (same value as admin token):
{
"mcpServers": {
"retrysight-lite": {
"command": "npm",
"args": ["run", "mcp", "--prefix", "/ABS/PATH/retrysight-lite/manager"],
"env": {
"RETRYSIGHT_URL": "http://127.0.0.1:18081",
"RETRYSIGHT_TOKEN": "<contents of data/admin-token>"
}
}
}
}
The Flutter app MCP screen generates this JSON from your live config.
Environment
| Variable | Default | Notes |
|---|
RETRYSIGHT_HOST | 127.0.0.1 | Loopback; use 0.0.0.0 for LAN |
RETRYSIGHT_PORT | 18081 | |
RETRYSIGHT_PUBLIC_URL | http://127.0.0.1:18081 | External URL for CORS |
RETRYSIGHT_ADMIN_TOKEN | auto | Protects GraphQL + non-ingest REST |
AGENT_API_KEY | auto | Optional HTTP ingest |
RETRYSIGHT_COLLECTORS | on | In-process IDE log collectors |
RETRYSIGHT_CURSOR / RETRYSIGHT_CLAUDE / RETRYSIGHT_WARP / RETRYSIGHT_WINDSURF / RETRYSIGHT_CLINE / RETRYSIGHT_AIDER / RETRYSIGHT_CONTINUE / RETRYSIGHT_COPILOT | on | Per-tool collector toggles |
RETRYSIGHT_*_PATHS | tool defaults | Override collector watch paths (colon/semicolon-separated) |
RETRYSIGHT_POLL_MS | 5000 | Collector poll interval |
RETRYSIGHT_FLUSH_MS | 10000 | Collector flush interval |
RETRYSIGHT_HEADLESS | unset | 1 = API only (no TUI) |
RETRYSIGHT_DATA_DIR | manager/data | DB + secrets |
RETRYSIGHT_COLLECTOR_DIR | ~/.retrysight-lite | Offsets / local agent id |
RETRYSIGHT_TLS_CERT | unset | Path to TLS cert (enables HTTPS) |
RETRYSIGHT_TLS_KEY | unset | Path to TLS key |
RETRYSIGHT_RETENTION_DAYS | 0 | Auto-delete data older than N days |
RETRYSIGHT_RETENTION_INTERVAL_MS | |
Note: The SQLite database (retrysight-lite.db) is not encrypted at rest. To protect data at rest, use full-disk encryption (FileVault on macOS, LUKS on Linux, BitLocker on Windows) or place the data dir on an encrypted volume. The DB/WAL and collector buffer files are chmod'd owner-only (0600) and their directories 0700 on creation.
Legacy environment names
If you upgraded from an earlier private build, RETRYSITELITE_* environment variables and X-RetrySiteLite-Admin-Token are still accepted by the backend for compatibility. Prefer the RETRYSIGHT_* names for new installs.
Secret-scan guard
To prevent committing live tokens, run the scanner and install the pre-commit hook:
./scripts/scan-secrets.sh --all
./scripts/install-git-hooks.sh
Development
# Backend unit/smoke tests
cd manager && npm run build && npm run smoke
# Flutter tests
cd app && flutter analyze && flutter test
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
Packaging scripts
Backend-only (headless service):
npm run dist # current platform binary + archive → release/
npm run dist:mac # macos-arm64 + macos-x64
npm run dist:linux # linux-x64
npm run dist:win # win-x64
npm run dist:all # all of the above
Self-contained Flutter desktop apps (see Install):
npm run dist:app # current platform
npm run dist:app:all # all targets buildable on this host
Uses esbuild + [@yao-pkg/pkg](https://github.com/yao-pkg/pkg) (Node 22). npm run dist:app embeds the pkg binary inside the Flutter desktop bundle so end users do not need Node. Cross-platform builds use Docker (Linux from macOS) or GitHub Actions (Windows). A release/portable-* folder is also produced for running with a system Node 22.5+ install.
Project layout
retrysight-lite/
├── app/ # Flutter native desktop GUI (recommended)
├── manager/ # Backend: collectors, API, GraphQL, MCP, legacy TUI
├── scripts/ # dist + OS installers + seed
├── release/ # build output (gitignored)
└── package.json # root dist / install scripts
License
Licensed under the Apache License, Version 2.0. Third-party notices are in [NOTICE](NOTICE).
