deskmeter/docs/PORT_DETECTION_README.md

Port Auto-Detection

Both the task window and GNOME extension now automatically detect which port dmweb is running on.

How It Works

Automatic Detection

Both apps try ports in this order:

1. 10001 - Worktree instance (tried first)
2. 10000 - Default instance (fallback)

The first port that responds successfully is used.

Task Window (task_window.py)

Auto-detection (recommended):

./task_window.py
# OR
python3 task_window.py

Output will show:

Found dmweb API on port 10001
API URL: http://localhost:10001/api/current_task

Manual port specification:

# Specify custom port as argument
python3 task_window.py 10001
python3 task_window.py 10000
python3 task_window.py 9999

Environment variable:

# Set port via environment variable
DESKMETER_PORT=10001 python3 task_window.py

Priority order: Command line arg > Environment variable > Auto-detection

GNOME Extension

The extension automatically tries ports 10001 and 10000 when it starts.

You'll see "detecting..." in the panel while it searches, then it will show:

• The task name when port is found
• "offline" if no port responds

Testing

Test with curl

# Check which ports are running
curl http://localhost:10000/api/current_task  # default
curl http://localhost:10001/api/current_task  # worktree

Test task window

# Auto-detect (will find port 10001 first)
python3 task_window.py

# Force specific port
python3 task_window.py 10000

Watch the console output to see which port was detected/used.

Configuration

Changing Port Priority

Edit task_window.py line 16:

DEFAULT_PORTS = [10001, 10000]  # Try in this order

Edit gnome-extension/deskmeter-indicator@local/extension.js line 11:

const DEFAULT_PORTS = [10001, 10000];  // Try in this order

Adding More Ports

# In task_window.py
DEFAULT_PORTS = [10001, 10000, 9999, 8080]

// In extension.js
const DEFAULT_PORTS = [10001, 10000, 9999, 8080];

Troubleshooting

Window shows "offline - dmweb not running"

# Check if any dmweb is running
ps aux | grep dmweb

# Check what ports are listening
ss -tlnp | grep -E "(10000|10001)"

# Test ports manually
curl http://localhost:10000/api/current_task
curl http://localhost:10001/api/current_task

Extension shows "detecting..." forever

The extension couldn't connect to any port. Check:

# View extension logs
journalctl --user -u org.gnome.Shell@wayland.service -f | grep deskmeter

Common issues:

• dmweb not running
• Firewall blocking localhost connections
• Wrong API endpoint (make sure /api/current_task exists)

Force specific port for extension

Edit ~/.local/share/gnome-shell/extensions/deskmeter-indicator@local/extension.js line 11:

// Only try one port
const DEFAULT_PORTS = [10001];

Then log out and back in to reload the extension.

Summary

✅ Task window: Auto-detects ports 10001, 10000 (can override with arg or env var) ✅ GNOME extension: Auto-detects ports 10001, 10000 ✅ Worktree-first: Both try port 10001 before 10000 ✅ Configurable: Easy to change port list or add more ports