Guide

Hyrax, end to end

One repository, from first profile to merged pull request. Every step, what it produces, and what it costs in attention.

Why the whole loop matters

Teams adopting AI coding tools report the speed. They do not report the same gain further down the line. In a survey of 1,149 professional developers, positive impact fell away sharply between shipping faster and shipping better.

The gap between 89% and 25% is the problem this workflow addresses. Two more figures from the same study explain why it persists.

Distrust is near universal. Checking is not. The difference is cost: a pass that returns forty comments is more expensive to read than the risk of shipping. Closing that gap means cutting the cost of checking, not raising the volume of it.

The loop, step by step

Hyrax is a hosted service. There is no CLI to install and nothing to self-host. Everything below happens in the web app and in GitHub.

1. Connect the repository

   Sign in with Google or an email code, which creates a workspace. Then install the Hyrax GitHub App on the repositories to be covered. That grants read access, and write access for submitting pull requests.

   ResultA workspace with repositories linked. Public repositories can also be added by URL for audit, profile and review, though a fix needs the App installed on the upstream organization.

2. Profile the architecture

   Discovery reads the repository and builds a structured profile of how it actually works. It runs automatically on the first repository connected. An audit cannot run until discovery has finished, because every later step reads this profile first.

   Nothing is committed into the repository. The profile lives in the workspace.

   ResultA domain summary, the engineering principles the team follows that are not visible in the code, naming and layout conventions, a definition of done covering tests and CI gates, a Mermaid architecture diagram, reusable units of know-how, and short how-to guides for common tasks in that repository.

3. Audit the codebase

   The repository is cloned at a specific commit into isolated throwaway compute, analysed there, and the working copy is deleted when the job ends. Raw source is not retained.

   Inside the run, fast deterministic pattern matching is combined with reasoning agents that read the code the way a careful reviewer would, across security, correctness, maintainability, performance, architecture and operations. Two depths are available on every plan: Standard as the everyday default, and Full for the complete catalog.

   ResultPrioritised findings, each naming the exact file and line range, plus a smaller number of higher-level architectural suggestions. Re-runs merge onto existing results rather than duplicating them, so a finding total is cumulative across runs and triage decisions are preserved.

4. Triage what came back

   Every observation carries a stable reference such as HYRAX-42, a priority from P0 to P3, one of six categories, and the file locations it touches. Filter and sort by impact rather than reading top to bottom.

   Dismissal is part of the workflow, not a failure of it. False positive, Won't fix and Out of scope stay closed and do not resurface. Stale, No longer found and Other can reappear if the issue is found again. Anything closed can be made active again.

   ResultA shortlist worth acting on, and a record of what was rejected and why. Standing guidance can be written once in free-form notes at workspace or repository level, which shapes findings before they are produced. A line such as "SOC 2 only, skip GDPR and HIPAA checks" is cheaper than dismissing the same false positive every month.

5. Turn a finding into a pull request

   Each fix is scoped to one observation, which keeps the resulting diff small, reviewable and traceable back to what prompted it. Four things happen in order.

   • The change is written. The finding, the relevant files and the surrounding code are read first.
   • The repository's own tests and build run. Not a generic check. Where the commands cannot be detected, they are set once in the repository's fix settings.
   • The diff is reviewed. Does this resolve the problem, is it correct, does it introduce anything new. If not, another pass is taken.
   • A pull request is submitted. A branch, a diff and a description, on GitHub.

   The two failure paths differ deliberately. A change that fails tests still reaches a pull request by default, carrying a hyrax:verification-failed label and a warning, so the decision stays with a human. A change the diff review rejects outright is abandoned instead, no pull request is submitted, and the finding stays active. Both are adjustable per repository.

   ResultA pull request titled [HYRAX-42] fix(…): … on a hyrax/fix-… branch, easy to filter and trace. A finding closes as fixed only when that pull request merges. Closing it unmerged returns the finding to the active list. Where Linear is connected, a ticket is filed alongside and linked in both directions.

6. Review every incoming pull request

   Review is on by default for every repository connected, and can be turned off per repository. Each pull request gets a single review comment, updated in place as new commits arrive rather than accumulating, plus a Hyrax Review check run that can optionally be required for merge.

   ResultOne comment per pull request instead of a thread that grows with every push, and an optional merge gate. Where CI fails on a Hyrax pull request, the failure is picked back up and the change revised, up to a limit, then left for a human.

7. Serve the context to the coding agents already in use

   Point Claude Code, Cursor, Copilot or any MCP-capable agent at the Hyrax MCP server and it reads the discovered context and the active findings live, at the moment it needs them.

   What the agent needs to know	What it reads
   What is this repository, and how is it built	Stack profile, domain summary and engineering principles, or the whole profile in one call
   What is the canonical way to do this here	The repository's conventions and patterns, optionally narrowed to one area
   What should I know before editing this file	The conventions and know-how that apply to that path
   How is a common task done in this repository	The how-to guides, by title or in full
   What has already been flagged here	Active findings and suggestions, including those touching a given file

   ResultAgents that read the current architecture instead of inferring it, and never from a copy that went stale the moment it was written. Re-running discovery is enough to refresh what every connected agent sees. There is no second step.

Keeping it current between audits

Revalidate re-checks existing observations against the latest commit and updates their status without generating new findings. It is a fast, low-cost correctness pass for confirming that work shipped.

What keeps the loop moving without anyone polling pages

• Todo is derived from the current state of the workspace: a repository with no first audit, a stale audit or profile, unaddressed critical findings, fix pull requests sitting too long. Items clear themselves as the condition resolves.
• Notifications are a record of events: an audit finished, a job failed, a fix pull request submitted or merged, billing notices.
• Spend is visible while working. Every job shows its cost on the Activity page, with credit remaining in the top bar. A per-job budget cap, a self-set overage limit and velocity limits keep one run or a busy month from surprising anyone.

Where this sits alongside existing tools

This workflow complements scanners and pull request reviewers rather than replacing them. Static analysis remains widely adopted, and its perceived value is rising rather than falling: 70% of developers in the same survey use static analysis, 57% already apply it to AI-assisted code, and expected value climbs from 60% today to 68% over the next two years.

The difference is the unit of work. A scanner returns a finding. A reviewer returns a comment. This loop returns a merged pull request, verified against the repository's own tests, with the architecture that justified it readable by every agent on the team.