Use an AI Assistant to Build a GRX Application

You do not need to be a programmer to start using the GRX API. An AI assistant such as Claude, Codex, or ChatGPT can create a small application for your receiver and explain how to run it on your computer. The most reliable way to do this is to give the assistant the GRX AGENTS.md context file and ask it to read that file before describing what you want to build.

Before You Start

You need:

  • A computer running Windows, macOS, or Linux.

  • The IP address of the GRX receiver. It must be reachable from your computer.

  • An AI assistant. Either a coding agent that works in a folder on your computer (for example Claude Code, Codex, Cursor, or GitHub Copilot), or a chat assistant that accepts a file upload or pasted text (for example the Claude or ChatGPT website).

  • Permission to install software on your computer if the assistant tells you that Python, Java, or another tool is needed.

The generated application connects to the receiver over your local network. It does not need this documentation source repository.

Files to Download

Download this archive before starting a new chat:

Download GRX_LLM_Starter_Files.zip

Create a new, empty folder for your application (for example grx-app) and extract the archive into it. This folder becomes your project folder. It then contains:

  • AGENTS.md – the context file for the assistant. It contains the complete API definitions, connection details, setup instructions, examples, GRX-specific behaviour, and instructions for running your application on the receiver itself. It also contains instructions for the assistant on how to guide you.

  • All six required .proto files (Common.proto, Receiverd.proto, Monitord.proto, Spectrumd.proto, Samplestreamingd.proto, TunableChanneld.proto). The assistant uses these to generate the code that talks to the receiver.

Give the Assistant the Context File

How you hand AGENTS.md to the assistant depends on the kind of assistant:

  • Coding agent (Claude Code, Codex, Cursor, GitHub Copilot, and similar): Open or start the agent in your project folder. AGENTS.md is a widely used convention and many agents read it automatically when they start in a folder. Not all of them do, so the first message below asks the assistant to read it explicitly.

  • Chat assistant (Claude or ChatGPT website, and similar): Attach AGENTS.md to the chat. If the assistant does not accept file uploads, paste its complete contents into the first message. You will copy the generated files into your project folder yourself.

1. Give the Assistant This First Message

Paste the following prompt as your first message and replace the words in capital letters. If you use a chat assistant, attach AGENTS.md to this message.

Start by reading the file AGENTS.md completely. It is in my project folder
(or attached to this message). Follow the instructions for the AI assistant
in that file and use only the API definitions it contains.

I am new to programming and want to create a GRX application.
My computer uses WINDOWS, MACOS, or LINUX.
My project folder is FULL_PATH_TO_YOUR_PROJECT_FOLDER. It contains
AGENTS.md and the six GRX .proto files.
My GRX receiver address is YOUR_GRX_IP.
I want the application to DO WHAT YOU NEED.

Please choose the simplest suitable language (prefer Python unless there is
a reason not to). Guide me one step at a time. Before each command, say
exactly where to run it and what it does. Include installation steps for all
required tools and dependencies for my operating system. Create complete,
copy-and-paste-ready files, then give me the exact command to run them.
Do not assume that I have this documentation repository.

For example, replace DO WHAT YOU NEED with “show the aircraft currently tracked by my receiver” or “save a spectrum waterfall image every minute.”

A good first answer confirms that the assistant has read AGENTS.md, for example by naming the five GRX services and their ports, and then asks for any information that is still missing. If the assistant instead starts guessing API names or asks you for the API definitions, it has not read the file; point it to AGENTS.md again before continuing.

2. Follow the Instructions One Step at a Time

The assistant should first check which tools are already installed, then show you how to install anything missing. It should work inside your project folder, use the .proto files that are already there, generate the gRPC client files, and create your application next to them.

Do not run a command you do not understand. Ask the assistant to explain it in plain language. If a command reports an error, copy the complete error message into the same chat and ask for the next step. Do not delete or change files unless the assistant tells you their exact names and locations.

3. Run and Extend Your Application

When the setup is complete, the assistant gives you a single command that starts your application. Run it from the folder the assistant tells you and compare the output with what the assistant said to expect. If nothing appears, check that the receiver address is correct and that your computer can reach the receiver on your network (for example by opening http://YOUR_GRX_IP/ in a browser).

Once the first version works, stay in the same chat and describe the next change you want, one at a time – for example “also write the results to a CSV file” or “only show aircraft above 10,000 feet”. The assistant still has AGENTS.md and your existing files as context.

If the application should later run permanently on the receiver itself (for example for continuous data collection from remotely deployed receivers), tell the assistant. AGENTS.md describes how to install the application on the GRX and start it automatically at boot. This requires SSH access to the receiver and some Linux knowledge; develop and test the application on your computer first.

Helpful Follow-up Prompts

Use one of these when needed:

I am on WINDOWS, MACOS, or LINUX. Check the steps you gave me for this
operating system and show only the next command I should run.

I received this error after running the command you gave me:

PASTE THE COMPLETE ERROR HERE

Explain the cause in plain language and give me one safe fix at a time.

Before we continue, give me a checklist of the files that should exist, where
they are located, and the one command that starts my GRX application.

Check the RPC names, message fields, and port numbers you used against
AGENTS.md and correct anything that does not match.

Choosing a Language

For a first application, ask the assistant to use Python. It usually has the simplest setup and is well suited to short scripts, data collection, and automation. Java and C++ are also supported when you already use them or need them for an existing application. The context file tells the assistant how to prepare each option.

Safety and Troubleshooting

  • Use your receiver’s actual address only on a trusted network.

  • The GRX API uses unencrypted local-network connections. Do not expose its API ports directly to the public internet.

  • Keep the assistant in your own project folder, rather than modifying another application on your computer.

  • Keep AGENTS.md in the project folder throughout the conversation. If you use a chat assistant and start a new chat, attach the file again and repeat the first message.

  • If the assistant invents an API name, a message field, or a port, ask it to check AGENTS.md before continuing.

  • If the assistant asks you to download the .proto files, tell it that they are already in your project folder next to AGENTS.md.

The Python, Java, and C++ guides remain available if you prefer to follow the manual setup instructions yourself.