Skip to main content

Discovery & AI agent context

AI coding tools guess at your conventions, invent file paths, and rediscover the same architecture every session. Discovery fixes that: Hyrax profiles your repository and serves that knowledge live to any AI agent you connect, so the agent starts pre-loaded with your real architecture and conventions.

One workflow does the work. Discovery profiles the repo and stores the context in your workspace — it runs automatically the first time you connect a repo. Your AI tools read it over the MCP server; nothing is committed into your repository.

What discovery produces​

Discovery builds a structured profile of your repository, stored in your workspace:

  • Domain summary — what the project does, in plain terms.
  • Engineering principles — design rules the team follows that aren't obvious from the code.
  • Conventions — naming, file layout, idioms, recurring patterns.
  • Definition of done — tests, lint, the CI gates a change has to clear.
  • Architecture diagram — a Mermaid diagram of how the system is laid out.
  • Reusable skills — repeatable units of know-how an agent can apply to common changes.
  • How-to guides — short walkthroughs for the most common tasks in the repo.

Every audit and fix gets sharper because Hyrax reads this context first — and so do your own AI tools, once they're connected.

When to re-run it​

Discovery reflects what was true when it ran. Re-run it after a significant architecture or dependency change — a new service, a restructured layout, a framework upgrade — and periodically (for example quarterly) to catch the slow drift of conventions. Because your agents read the context live, a re-run is all it takes: there is no second step to get the fresh version in front of them.

How your AI tools use it​

Connect Claude Code, Cursor, Copilot, or any MCP-capable agent to the Hyrax MCP server and it can ask for exactly the context it needs, at the moment it needs it:

Question the agent hasWhat it reads
"What is this repo, and how is it built?"The stack profile, domain summary, and engineering principles — or the whole discovery bundle in one call.
"What's the canonical way to do this here?"The repo's conventions and patterns, optionally narrowed to an area.
"What should I know before editing this file?"The conventions and skills that apply to that path.
"How do I do a common task in this repo?"The how-to guides, by title or in full.
"What has Hyrax already flagged here?"The open findings and suggestions, including the ones touching a given file.

Every answer comes from the current state of your workspace, so an agent never works from a copy that went stale the moment it was written. An agent that knows your architecture writes code that fits the first time — fewer "we don't do it that way" rounds. The MCP server page has the connection details and the full tool list.

Your own guidance​

Hyrax doesn't only learn about your code by reading it — you can tell it things directly. There are two places to write free-form notes:

  • Workspace-wide — Settings → Agent Overrides → Freeform Notes. Context that applies to every repo: your deployment model, compliance scope, infrastructure conventions.
  • Per-repo — each repository's Settings → Agent Overrides → Freeform Notes. Repo-specific nuance: known-safe patterns that shouldn't be flagged, what's deliberately out of scope, anything that should shape how Hyrax reads that repo.

Both are plain prose — no special format. Hyrax weaves them into its prompts for audits, fixes, and discovery, with repo notes layered on top of workspace notes. A line like "SOC2 only — skip GDPR/HIPAA checks" steers findings before they're produced — better than dismissing the same false positive every month. Available on every plan.

  • MCP server — connecting your agents, and every tool they can call.
  • Workflows — Discovery and every other workflow.
  • Quickstart — discovery runs automatically the first time you connect a repo.