| name | log-inspector |
| description | [paranext-core ONLY] Read and analyze Platform.Bible application logs including Electron (main, renderer, extension-host) and C# data provider logs. Use when debugging test failures, runtime errors, or unexpected behavior. Works whether app is running or stopped. NOT for use in PT9/legacy Paratext codebases. |
| allowed-tools | Bash, Read, Grep |
Log Inspector Skill
Read and analyze Platform.Bible application logs for debugging and troubleshooting.
App Status Awareness
This skill works in BOTH states - app running or stopped.
| App State | Log Analysis Mode | Use Case |
|---|
| Running | Live monitoring (tail -f) | Debug issues as they happen |
| Stopped | Historical analysis (grep, cat) | Investigate past crashes/errors |
Note: You do NOT need to ask the user to start the app for log inspection. Log files persist between sessions.
When to Check App Status
If you need to debug a live issue (reproduce and watch):
RUNNING=$(pgrep -f "electron.*paranext" > /dev/null && echo "yes" || echo "no")
echo "App currently running: $RUNNING"
If live debugging is needed and app is not running, you may ask the user to start it. But for historical log analysis, this is not necessary.
Quick Reference
| Action | Command |
|---|
| Recent errors | grep -i "error|exception" "$LOG_PATH" | tail -20 |
| Watch live | tail -f "$LOG_PATH" |
| Filter by process | grep "\[main\]" "$LOG_PATH" |
| Last 50 lines | tail -50 "$LOG_PATH" |
Log Locations
Electron Logs (main, renderer, extension-host)
LOG_PATH=~/Library/Logs/Electron/main.log
$LOG_PATH="$env:APPDATA\Electron\logs\main.log"
LOG_PATH=~/.config/Electron/logs/main.log
Note: During development on all platforms, electron-log uses the default Electron app name Electron for the log directory. In packaged releases, logs use the packaged app name platform-bible (from release/app/package.json name). The logic is setAppName(globalThis.isPackaged ? APP_NAME : 'Electron') in src/shared/services/logger.service.ts.
C# Data Provider Logs
The .NET data provider has no separate file-log directory. It writes to its own
stdout/stderr (via Console.WriteLine), and the Electron main process captures that output
and forwards it into the unified electron-log main.log file tagged [.net] (see
dotnet.stdout.on('data', ...) in src/main/services/dotnet-data-provider.service.ts).
grep "\.net" ~/.config/Electron/logs/main.log
Viewing Logs
Recent Errors
Find the most recent errors across all processes:
grep -iE "error|exception|fail" ~/Library/Logs/Electron/main.log | tail -30
Watch Live Logs
Monitor logs in real-time while testing:
tail -f ~/Library/Logs/Electron/main.log
tail -f ~/Library/Logs/Electron/main.log | ccze -A
Filter by Process Type
Platform.Bible logs include process tags:
| Tag | Process |
|---|
[main] | Main Electron process |
[rend] | Renderer process |
[exth] | Extension host |
[unkn] | Unknown/other |
grep "\[main\]" ~/Library/Logs/Electron/main.log
grep "\[rend\]" ~/Library/Logs/Electron/main.log
grep "\[exth\]" ~/Library/Logs/Electron/main.log
Filter by Log Level
Log levels: error, warn, info, verbose, debug
grep -E "\[(error|warn)\]" ~/Library/Logs/Electron/main.log
grep "\[debug\]" ~/Library/Logs/Electron/main.log
Search for Specific Patterns
grep -A 10 "Error:" ~/Library/Logs/Electron/main.log
grep "DataProvider" ~/Library/Logs/Electron/main.log
grep "2025-12-31 14:" ~/Library/Logs/Electron/main.log
Log Format
Platform.Bible uses electron-log with this format:
[YYYY-MM-DD HH:MM:SS.mmm] [level] [process] message [at function file.ts:line:col]
Example:
[2025-12-31 14:30:15.123] [error] [main] Failed to connect [at connect network.ts:45:8]
Log Rotation
- Max file size: 3 MB before archiving
- Archive count: 5 total log files (the current
main.log plus up to 4 archived)
- Archive naming:
main.old-1.log, main.old-2.log, ... main.old-4.log (the archiver inserts .old-{n} BEFORE the extension; template {name}.old-{n}{ext} in src/node/utils/log-archiver.util.ts)
To view older logs:
ls -la ~/Library/Logs/Electron/
cat ~/Library/Logs/Electron/main.old-1.log
Debugging Workflows
Test Failure Investigation
-
Clear logs (optional):
echo "" > ~/Library/Logs/Electron/main.log
-
Run the failing test
-
Check for errors:
grep -iE "error|exception" ~/Library/Logs/Electron/main.log
-
Look for stack traces:
grep -A 20 "Error:" ~/Library/Logs/Electron/main.log
Runtime Issue Investigation
-
Start watching logs:
tail -f ~/Library/Logs/Electron/main.log
-
Reproduce the issue in the app
-
Look for errors in the output
-
Search for specific component:
grep "ComponentName" ~/Library/Logs/Electron/main.log
C# Data Provider Issues
When debugging .NET backend:
-
Run data provider in foreground:
npm run start:data
-
Check for .NET exceptions:
Command-Line Log Level Override
When starting the app, override log verbosity:
npm start -- --logLevel=debug
npm start -- --logLevel=warn
See Also
