Rig Remote

Rig Remote is a GUI tool for remotely controlling an SDR or hardware transceiver using the RigCTL protocol over TCP/IP. It connects to any receiver that understands RigCTL commands — software-defined radios running gqrx, or hardware rigs driven by a rigctld daemon — and adds frequency scanning, bookmarking, recording control, and rig-sync on top.

---

Features

• Frequency scanning across bookmarks or arbitrary ranges
• Selectable infinite or fixed scan passes
• Pause-on-signal with configurable hold time, or wait until the frequency clears
• Bookmark lockout to skip selected entries during a scan
• On-the-fly scan parameter updates while a scan is running
• Optional scan-activity logging to a file
• Automatic bookmarking with improved handling of strong signals
• Sortable bookmark list in the UI
• Frequency sync between two rigs (useful for panadapter setups)
• Enable/disable recording and streaming from the UI

---

Requirements

Dependency	Version
Python	≥ 3.13
PySide6	≥ 6.6
RigCTL-capable software	e.g. gqrx or rigctld

---

Installation

From PyPI:

pip install rig-remote

Debian / Ubuntu package (.deb):

Download the latest .deb from the GitHub releases page, then install it:

sudo apt install ./rig-remote_<version>_amd64.deb

Using apt install ./ rather than dpkg -i lets apt resolve any missing system library dependencies automatically. The package bundles PySide6 in a private directory (/usr/lib/rig-remote) so no separate PySide6 installation is required; only Python 3.13 or later must be present on the system.

Development setup with uv:

git clone https://github.com/Marzona/rig-remote.git
cd rig-remote
uv sync --group dev

---

Usage

Launch the GUI:

rig_remote

Validate a configuration file without starting the GUI:

config_checker --config <path-to-config>

---

Bookmark file format

Bookmarks are stored in a standard CSV file (rig-bookmarks.csv). See the bookmark file format page on the wiki for the full field specification.

---

Project layout

src/rig_remote/       main application package
src/config_checker/   configuration checker CLI
tests/                unit tests
functional_tests/     integration tests (tests marked `gqrx` need a running gqrx)

---

Quality checks and agent setup

• CI: .github/workflows/ci.yml runs lint, type checks, unit and functional tests, builds the wheel and .deb, and starts both entry points from the installed wheel and from the .deb in a clean container. Releases go through .github/workflows/release.yml: tag on master, Trusted Publishing, and a required approval before PyPI.
• Architecture rules as tests: the decisions and invariants in .claude/architecture.md list what enforces each one; tests/test_architecture.py and tests/test_doc_drift.py fail when code or docs drift.
• AI agent setup: .claude/ holds the project instructions, a release agent that stops at verified artefacts, a read-only review agent, and hooks (tested in tests/test_hooks.py) that block publishing and file changes by those agents.
• Review-agent evals: the evals apply seeded bugs (most of them real bugs this project shipped) and harmless controls, then score what the review agent catches against what CI alone catches.
• Running the checks locally: see .claude/rules/verification.md, or run ./release.sh commit_push.

---

Documentation

• Wiki — overview and architecture notes
• User Manual — step-by-step usage guide

---

Contributing

Bug reports, feature requests, and pull requests are all welcome. Open an issue and it will be triaged as soon as possible. See the mailing list link on the wiki if you want to discuss larger changes before writing code.

Open items are tracked in issues and milestones.

---

License

MIT — see LICENSE.