How to Read a Robotics Repo When You're New

Read a robotics repo by finding what actually runs and what it sends, not by touring the folder tree or trusting the README. A robot is a few processes exchanging messages, so startup files and message definitions show the shape faster than source files do. That flips for a library rather than a robot, where the tests are the documentation, whether the repo is ROS 2 or HORUS. The rest of this post is for someone who has cloned a robotics repo and cannot tell where the robot actually begins.

You cloned it because a video showed a machine doing the thing you want to build. Then you opened the folder and the confidence drained out of you. There are directories named after concepts you have never met, three build systems, a launch directory, a config directory full of files that reference other files, and a README whose quick-start instructions stop working at step four.

So you do the thing everyone does. You open the file with the most promising name and read it top to bottom. It calls into six other files. You follow one, which is an interface with no implementation nearby. You come back. You search the codebase for the word that describes what you actually care about and get four hundred results, most of them in generated code. An hour later you have read a lot and could not describe, out loud, what happens when the robot is switched on.

What makes it worse is the suspicion that everyone else can do this. Someone in the issue tracker is discussing a specific function as though it were obvious where that function lives and when it runs. You start to wonder whether reading unfamiliar code is a skill you missed, or whether robotics repos are simply shaped differently from the code you already know how to read.

How should you read a robotics repo when you are new?

Start from what runs, not from what exists. A robotics repo is not one program you can read top to bottom; it is a set of separate processes started together, and the folder tree deliberately hides that fact because folders are organised for the maintainers, not for you. So find the startup description first — a launch file, a script, a service definition, or whatever the project uses to bring the system up — and list the processes it starts. Then find the message definitions, which tell you what those processes say to each other. Between those two you have the actual architecture, usually within your first sitting, and you have it in a form you can draw on paper. Only then open source files, and open only the ones on the path you care about. The reason this order works is that in a system of communicating parts, the interesting behaviour lives between the files rather than inside them, and reading file by file is reading the one place the behaviour is not.

What is actually inside a robotics repo?

Most robotics repos contain the same six kinds of thing wearing different names. There is driver code that talks to hardware and turns readings into numbers. There is a description of the machine itself — its joints, links and sensor positions — usually in its own file format. There are the processes that do the thinking: perception, planning, control. There are message definitions, the shapes of data that get passed around. There is configuration, which is where the numbers that make the robot work live, and which is where most of the real tuning is hiding. And there is startup material that decides which of the above runs, in what order, with which configuration. Notice how much of that is not code in the sense you are used to. A large part of a robot's behaviour is expressed in configuration and startup files rather than in functions, which is exactly why reading the source alone leaves newcomers with no idea what the robot does. If the word processes here is doing unfamiliar work, what a robot node is and why everything uses that word explains the vocabulary.

What are your options for finding a way in?

Your options depend far more on which kind of repo you have opened than on your reading technique, and identifying the kind takes a minute. An application repo is a whole robot and wants to be read from its startup files. A driver or library repo is one component and wants to be read from its tests and its public interface. A research repo is an argument in code, so the paper is the entry point and the code is evidence. A vendor SDK is documentation with examples attached, and reading it linearly is usually a mistake. The stack shapes the layout too: a ROS 2 repo is a workspace of packages with launch files and separate message packages, and learning that layout once makes hundreds of public repos legible, while a HORUS repo, being an open-source real-time middleware for Rust, Python and C++, tends to place processes in all three languages side by side over the same shared-memory ring buffers, so the message definitions are the shared vocabulary you read first. Use the table to work out which situation you are in.

What should you do if you are coming from web or application code?

Stop looking for the call stack, because in a robot there is not one. The instinct trained by application code is to find the entry point and follow calls down until you understand the whole path, and that instinct works beautifully in a program that is one process. A robot is several processes that never call each other; they publish messages and read messages, so the connection between the camera code and the wheels is a name in a configuration file, not a function call anywhere. Once you accept that, the search strategy changes usefully: instead of searching for a function name, search for a message or topic name and see who writes it and who reads it. That single search reconstructs the wiring diagram. The second adjustment is time. Application code runs when someone asks; robot code runs on a rhythm, over and over, whether or not anything changed. A function that looks pointless in isolation often exists because it must produce something every cycle even when there is nothing new to say.

What should you do if you cannot run the repo because you have no hardware?

Look for the simulation entry point first, because most serious robotics repos have one and it is frequently undocumented. Projects that test anything at all must be able to run without the machine attached, so there is usually a launch file, a flag or a fake driver that feeds recorded or synthetic data in place of a sensor. Finding that turns a repo you can only read into a repo you can watch. Second best is recorded data: many projects ship or link a recording of a real session, and replaying one through the system shows you the message flow with actual values in it, which is worth more than a week of reading. If neither exists, the tests are your substitute, since they run without hardware by necessity and they show the authors' own idea of correct input. What you cannot learn without hardware is which parts quietly fail, which settings are actually used in the field, and where the timing is tight. Note those as open questions rather than pretending you have answered them.

What should you do if you have one evening before a meeting about this code?

Answer three questions and refuse to read anything that does not serve them. First, what processes run when this system starts, which comes from the startup files and takes minutes rather than hours. Second, what data flows between them, which comes from message definitions and a search for who publishes and subscribes to each name. Third, where is the code that does the thing the meeting is about, which you find by searching for the message that thing produces and working backwards. That gives you a diagram, a vocabulary and one file you have actually read closely, and it is a far stronger position than having skimmed thirty files. The temptation under time pressure is to read the README carefully and the code lightly, which produces confidence without understanding and shows up immediately in a meeting. Bring your diagram and one honest question about a part you could not follow. Experienced people read that as competence, because tracing a system to its first genuinely confusing point is exactly what reading code is.

What should you do if the repo is in a language you do not write?

Read it anyway, because the structural questions are language-independent and they are most of what you need. What processes exist, what messages they exchange, what configuration they take, and in what order things start are all answerable in a language you have never written, since they live in filenames, manifests, startup descriptions and message definitions rather than in syntax. Robotics makes this more common than most fields, because a single project routinely contains a driver in C++, a behaviour layer in Python and increasingly a component in Rust, and nobody is fluent in all of it. What genuinely needs the language is the innermost detail: how a specific calculation is done, why a value is clamped, what a particular type guarantees. Defer those. When you must read them, read the tests for that component first, because a test shows the intended input and expected output without requiring you to follow the implementation. The honest limit is that you should not change code in a language you do not write without someone reviewing it who does.

What does it look like when you are reading a repo the wrong way?

You have many files open and cannot say what happens when the robot starts. That is the diagnostic symptom, and it is worth checking hourly. Other signs come in a recognisable set: you have been reading for a long time and every new file introduces two more; you are deep in a utilities directory learning helper functions nobody asked you about; you can describe the class hierarchy but not the data flow; you keep searching for a word from the README and finding it only in comments. The common cause is reading breadth-first from the folder tree, which is the same as trying to understand a city by reading a list of street names. The corrective is uncomfortable but it works: close everything, open the startup description, and write down the process names on paper before opening another source file. If you cannot find a startup description at all, that is information too, usually meaning the repo is a library rather than a robot, and libraries are read from their tests instead.

What do people try first, and why does that stop working?

People first read the README and then the file with the most important-sounding name, and it stops working at exactly the point the project gets interesting. The README is written by someone who already understands the system, so it describes intent rather than structure, and it ages badly because nothing breaks when a README goes stale. The important-sounding file is usually either an interface with no behaviour or a coordinator that delegates everything, so reading it teaches you names without teaching you what happens. The next attempt is normally full-text search, which works until the term you searched for is a message name that appears in generated code, configuration, and three unrelated components, and now you have results instead of understanding. What survives contact with a real project is the run-and-observe loop: start the system in simulation, watch which messages actually flow, and read only the code that produces the ones you care about. Reading is cheap and misleading; running is slower to set up and tells you the truth.

What do you give up by reading a repo this way?

You give up completeness, and that is the point rather than a cost. Reading from startup files and messages outwards means large parts of the repository stay unread, including code that may matter later: error handling paths, alternative configurations, the component that only runs on the real hardware, the compatibility layer for the older sensor. You will meet those the first time one of them surprises you, and you will meet them with a map, which is a better position than meeting them exhausted on day one. You also give up the pleasure of feeling thorough, which is a real loss for careful people and worth naming honestly. The genuine risk in this approach is mistaking the running configuration for the only configuration, since a robot often behaves differently in simulation, on the bench and in the field, and reading one path teaches you one of the three. Ask which settings are used in production before assuming what you traced is what ships. That question also tells you a lot about the project's habits.

When is ROS 2 the better choice?

ROS 2 is the better choice when the repos you want to read and reuse are ROS 2 repos, which is most of the public robotics code that exists. Learning one workspace layout, one launch file format and one message convention makes an enormous body of drivers, planners and tools legible at once, and that transfer is the single biggest reason a newcomer should consider starting there rather than anywhere lighter. ROS 2 also wins outright when your robot must map a space and navigate it, when you need to record a session and replay it to work out what happened, when the system spans a robot and a workstation or several machines, and when you are joining a team that already speaks it. HORUS is not the answer in those situations, and choosing it there means giving up the packages and the shared vocabulary that made the ecosystem worth entering. There is a fair test: if what you want already exists as a maintained ROS 2 package, reading that package is more valuable than evaluating alternatives.

Do you need to understand every file before you change one?

No, and here is why: a robotics system is composed of parts that communicate through defined messages, so the blast radius of a change is bounded by what that component publishes, not by the size of the repository. If you are modifying the process that produces one message, the code that can possibly be affected is the code that reads that message, and you can find all of it with a search. That is a bounded, checkable list, and it is usually short. What you do need to understand completely is the component you are touching and the contract it advertises: what it promises to publish, how often, and what it does when its input is missing. Breaking the contract quietly is the failure mode that hurts, because the system keeps running and something downstream behaves oddly a layer away. Before changing anything, it is also worth checking whether the project is alive enough to accept your change — how to tell a healthy open-source robotics project from a dead one covers what to look for.

Does an AI assistant remove the need to read the repo yourself?

Partly, but not the way you think. An assistant is genuinely good at the mechanical half of this work: summarising a directory, listing which files publish a given message, explaining an unfamiliar language's syntax, and answering what does this function do without you losing your place. Used that way it removes hours of tedium and is worth having open. What it does not give you is the thing you were actually after, which is a mental model you can reason with when something goes wrong at eleven at night. An explanation you read is not the same as a structure you have built, and the difference shows the moment the robot does something the explanation did not cover. There is also a specific hazard with robotics repos: an assistant reads the code, and a large part of a robot's behaviour is in configuration, startup order and hardware, so a confident summary can be structurally correct and practically wrong. Use it to accelerate the map, then verify the map by running the system.

How do you decide where to start in an unfamiliar repo?

Decide by naming what you want from the repo, because the entry point is different for each want. If you want to run it, start with the startup files and get it running in simulation before reading anything. If you want to borrow one component, start with that component's tests and its public interface and ignore the rest of the project entirely. If you want to evaluate the project before depending on it, start with the issue tracker and the recent commits, because those tell you about the maintainers, and maintainers matter more than architecture for anything you will rely on. If you want to contribute, start with a small open issue and let it drag you through whatever parts of the code it touches, which is the fastest structured tour anyone has found. The tie-break when it stays close: prefer whichever route gets something running soonest, because a running system answers questions you did not know to ask. If the reason you cannot run it is physical rather than software, whether you need to learn electronics to do robotics software sorts out which half of that problem is yours.

Decide by what you actually want from the code:

• If you want to run the robot -> startup files first, because they name every process and setting that matters.
• If you want one algorithm -> that component's tests and interface, because the rest of the repo is not your problem.
• If you are evaluating the project -> issues and recent commits, because maintainers outlast architecture.
• If you are contributing -> one small issue, because it drags you through the right files in the right order.
• If you have no hardware -> the simulation entry point or recorded data, because watching beats reading.

When the reading turns into a decision about what to build on, weigh the candidates on the five axes of the HORUS Fit Framework — ecosystem size, setup effort, team size fit, deployment target, and licence — and take the one that loses on the fewest, with no scoring involved. If the repos you keep admiring run Python, C++ and Rust together on a single machine and pass messages between them without a serialisation step, star HORUS on GitHub so it is in your list when you start building.