Hound audits code by building adaptive knowledge graphs, one project at a time

The graph is the audit's memory

Hound is described as a language-agnostic AI auditor that autonomously builds and refines adaptive knowledge graphs for deep, iterative code reasoning. The subtitle in the README puts the use case more plainly: autonomous agents for code security auditing.

The central idea is that the agent does not simply read files and report. It constructs an explicit representation of the system and reasons over that. The feature list calls this graph-driven analysis, with flexible, agent-designed graphs that can model any aspect of a system, and it gives the examples: architecture, access control, value flows, mathematics.

That flexibility is the differentiator. A graph is not a call graph and not an import graph. The agent decides what an aspect of the system means for the investigation, and the graph records it. The next layer is relational graph views, described as supporting cross-aspect reasoning and precise retrieval of the code snippets that back each subsystem investigated. So the graph is not only an index, it is the thing that lets the agent jump between two different views of the same code and connect them.

The belief and hypothesis system is the third piece. Observations, assumptions and hypotheses evolve with confidence scores, which the README says enables long-horizon reasoning and cumulative audits. A cumulative audit is the interesting property: the conclusions of one pass are inputs to the next, which is what you need for a security review where the interesting bug is three steps from the first thing that looked wrong.

There is a paper on arXiv at 2510.09633v1 and a walkthrough linked from the README.

Scout models explore, strategist models reason

The dynamic model switching feature is a cost decision, and it is described concretely: lightweight scout models handle exploration, heavyweight strategist models provide deep reasoning, mirroring expert workflows while keeping costs efficient.

The separation maps onto how an auditor actually works. Broad coverage means touching a lot of code cheaply, identifying which parts matter and what the trust boundaries are. Only after that does it pay to spend a frontier model on a narrow question about one function.

The strategic audit planning feature is the other half: it balances broad code coverage with focused investigation of the most promising aspects, ensuring both depth and efficiency. Together, the two features describe a budget policy rather than a single model configuration, and that is what makes the tool usable at all on a paid API, since the alternative is a frontier model over the whole repository.

The project is maintained by trungkien1992 according to the Maintenance section, and the README asks for bug reports as issues and code changes as pull requests with a clear description and relevant tests where applicable.

One caveat the README states plainly and that should shape your expectations: audit quality scales with time and model capability. Use longer runs and advanced models for more complete results. There is no fixed budget that produces a fixed level of coverage, which is both the honest framing and a practical problem for anyone trying to schedule this work.

The CLI is organised as projects, graphs and analysis

The complete audit workflow is a sequence of CLI commands, and the vocabulary is worth learning before running anything.

Step one is creating a project, which organises your audits and stores all the analysis data.

# Create a project from local code
./hound.py project create myaudit /path/to/code

# List all projects
./hound.py project ls

# View project details and coverage
./hound.py project info myaudit

Step two is building knowledge graphs, which are described as aspect-oriented and as the foundation for all subsequent analysis. The recommended path is the auto mode, which generates a default set of graphs, up to five, and refines them.

# Auto-generate a default set of graphs (up to 5) and refine
# Strongly recommended: pass a whitelist of files (comma-separated)
./hound.py graph build myaudit --auto \
  --files "src/A.sol,src/B.sol,src/utils/Lib.sol"

# View generated graphs
./hound.py graph ls myaudit

The alternative is manual guidance, where you initialise the baseline SystemArchitecture graph and then add specific graphs with your own description.

# 1) Initialize the baseline SystemArchitecture graph
./hound.py graph build myaudit --init \
  --files "src/A.sol,src/B.sol,src/utils/Lib.sol"

# 2) Add a specific graph with your own description (exactly one graph)
./hound.py graph custom myaudit \
  "Call graph focusing on function call relationships across modules" \
  --iterations 2 \
  --files "src/A.sol,src/B.sol,src/utils/Lib.sol"

The operational notes clarify the interaction between the two. Auto always includes the SystemArchitecture graph as the first graph, so there is no need to run init in addition to auto. If init is used and a SystemArchitecture graph already exists, initialisation is skipped, and to get a clean re-init you remove the existing graphs first. When running auto with graphs already present, Hound asks for confirmation.

The whitelist flag deserves attention. The README strongly recommends passing a comma separated list of files, which is how you keep the audit inside the codebase size the tool is built for.

Codebase size is the stated boundary

The README has a paragraph with a heading of its own on codebase size considerations, and it is the most decision-relevant sentence in the document.

While Hound can analyze any codebase, it is optimized for small-to-medium sized projects like typical smart contract applications. Large enterprise codebases may exceed context limits and require selective analysis of specific subsystems.

That is a real constraint rather than a hedge, and it follows from the architecture. The agent holds a knowledge graph of the system in context, and a graph of a large enterprise codebase does not fit. The mitigation the project offers is the same mechanism that causes the problem: you select the subsystem and let the graph cover that.

The consequence for practice is that you should be deciding up front what you are auditing. Pointing Hound at a whole repository and hoping it narrows down is the wrong way round. The example paths in the workflow commands are Solidity files, src/A.sol and src/B.sol and src/utils/Lib.sol, which is consistent with the stated optimisation target.

For an enterprise codebase, the realistic use is per subsystem: the payments service, the auth path, the parser. Each gets its own project and its own set of graphs, and the findings are read per subsystem rather than as one global verdict.

The whitelist flag, the aspect-oriented graphs and the selective analysis note are all the same idea viewed from different angles. Hound is a tool for focused audits.

Providers, keys and the Vertex AI routing

The configuration section sets up an OpenAI API key and an optional base URL through environment variables.

export OPENAI_API_KEY=your_key_here
# Optional: override the base URL (defaults to https://api.openai.com)
export OPENAI_BASE_URL=https://api.openai.com

The README badges also list Gemini, Anthropic and OpenAI compatibility, and the dependency list confirms the breadth: openai, google-generativeai, google-genai, anthropic and xai-sdk, plus litellm in requirements.txt. So multiple providers are a real feature rather than a badge, and litellm is presumably what sits underneath to route between them.

The Gemini path has a specific mode worth understanding. Vertex AI mode is enabled separately from AI Studio, and credentials come from Application Default Credentials or a service account, with the README noting that GOOGLE_API_KEY is not used in Vertex AI mode.

# Enable Vertex AI routing for Gemini
export GOOGLE_USE_VERTEX_AI=1

# Provide project and region (region examples: us-central1, europe-west1, asia-northeast1, etc.)
export VERTEX_PROJECT_ID=my-gcp-project
export VERTEX_LOCATION=us-central1

The endpoint is then constructed as a regional Vertex AI URL, for example https://us-central1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/us-central1. Authentication is either gcloud auth application-default login or a service account key file pointed at by GOOGLE_APPLICATION_CREDENTIALS.

The same settings can live in a YAML file instead of the environment.

gemini:
  api_key_env: GOOGLE_API_KEY
  vertex_ai:
    enabled: true
    project_id: "my-gcp-project"
    region: "us-central1"

And the example config can be copied and edited.

cp hound/config.yaml.example hound/config.yaml
# then edit hound/config.yaml to select providers/models and options

One note about secrets: the README says to keep API keys out of the repository, notes that API_KEYS.txt is gitignored and can be sourced, and says defaults work out of the box with many options overridable through CLI flags.

What the licence situation actually says

There is an inconsistency here that you should resolve yourself rather than take on faith.

The README carries a licence badge that reads Apache 2.0 and links to LICENSE.txt at the repository root. The licence field for the repository is marked as a custom licence that GitHub cannot classify, with a pointer to the LICENSE file. And the repository root contains both a LICENSE.txt and a CHANGELOG.md, plus CONTRIBUTING.md and a SECURITY.md.

So the badge and the metadata disagree, and the metadata explicitly tells you that the terms are in the file rather than in a category GitHub recognises. That is not automatically a problem, since many projects ship a modified licence that GitHub has no category for, but it does mean the badge is not a reliable summary.

Read LICENSE.txt before you use this in an automated pipeline or redistribute any part of it. The Apache 2.0 attribution in the badge should not be treated as the operative terms until you have read the file.

On the project side, the last push was on 2026-09-17 and there are no GitHub releases, so there is no version to pin and no release history to diff. The pyproject version is 2.0.0, so the package has had a major version, but the packaging does not appear to be published to a package index in any way the README describes. Installation is from the repository itself.

Where Hound is the wrong tool

The first wrong case is the large codebase, which the README names directly. Beyond context limits, the tool is not merely less thorough, it is the wrong shape of instrument, and you would spend the run watching it work on the parts you did not care about.

The second is a workflow that needs a verdict rather than an investigation. Hound's design is iterative and probabilistic. It builds hypotheses with confidence scores and refines them across runs, and the README tells you that quality scales with time and model capability. That is the right design for a hunting session, and the wrong one for a pipeline that must produce a repeatable pass or fail result for a code review gate.

The third is the cost predictability. Scout and strategist splitting controls per-token spend, but the total is a function of how long you let it run and which models you point it at. There is no stated fixed cost for a complete audit, so budgeting a security review around this tool means measuring a run rather than quoting a price.

The fourth is a codebase where the interesting security property is not graph-shaped. Hound models aspects of a system as graphs, and a system whose risks live in timing, deployment configuration or a third party dependency is not well served by more graphs.

And the fifth is simply that a static analyser or a human reviewer is different in kind. A linter gives you a fixed rule set applied deterministically, and a human auditor gives you judgement. Hound sits between them, and if your requirement is one of the other two, adding it is scope rather than coverage.

How it compares to a static analyser or a single model prompt

The realistic alternatives are two, and Hound is best understood by the difference from each.

Against a static analyser such as a linter or a taint analysis tool, the difference is what the tool reasons about. A static analyser has a fixed set of rules, applied deterministically, and it finds what its rules cover. Hound decides which aspects of the system matter and builds representations of them, then reasons across those representations, which is why it can follow a value flow from an external call into a state change that no rule set anticipated. The cost profile is inverted as well: a linter is free per run and shallow, Hound is expensive per run and has the capacity to be deep.

Against prompting a single frontier model with the code, the difference is structure and memory. A single prompt gives you a linear response with a context window and no memory between calls, so a two hundred file repository is truncated and every follow up question restarts from scratch. Hound keeps its findings in a graph that persists across the project, so the audit accumulates, and the aspect-specific graphs let it retrieve the exact code snippets behind a subsystem rather than hoping the right file is still in context.

The trade is that Hound needs a setup phase and a provider budget, where the single prompt needs neither. If your question is one question about one file, Hound is overhead. If your question is where the unhandled trust boundaries are in a service, the graph is the reason it can answer.

The walkthrough linked from the README is a full session against real code, and it is the most direct way to judge whether the quality of the reasoning justifies the setup cost.

Editorial conclusion

Hound fits a security team auditing a small to medium codebase, such as a smart contract application, who want an agent-driven audit that keeps its reasoning in a knowledge graph rather than in a linear transcript, and who can point it at a specific subsystem rather than a whole repository. It does not fit a large enterprise codebase, since the README warns that those may exceed context limits and need selective analysis, and it does not fit a team that needs a deterministic, reproducible audit result rather than a probabilistic one. Before adopting, run it against a codebase you already know well so you can judge the findings against ground truth, check the licence file yourself because the README badge and the licence field disagree, and treat the first run as a cost estimate rather than a verdict.

Frequently asked questions

Official sources

1. Issues
2. README
3. scabench-org/hound on GitHub