codehound

An AST-based static analyzer that hunts real bugs in large Python codebases — twenty checks, seven backed by a bug that was actually found and merged into a major open-source AI framework, the rest hardening rules verified against real false positives across a ~20-framework validation corpus instead of just reasoned about.

Most linters flag style. codehound flags the subtle correctness and async-safety bugs that slip past code review and only bite in production — event-loop stalls, shared mutable state, leaked file descriptors, fire-and-forget tasks that get garbage-collected mid-run.

Most of the checks below aren't theoretical. I wrote them after finding — and fixing, via a merged pull request — that exact bug in a real, popular framework (agno 25k⭐, crewAI 30k⭐, mem0, llama_index, accelerate).

See it in action

Pointing codehound at agno (a 25k⭐ AI agent framework) surfaced real, previously-unreported bugs:

$ codehound scan agno/libs/agno/agno --select CH001,CH006

agno/integrations/discord/client.py:90:26: CH001 `requests.get()` blocks the event loop
    inside async function `on_message`; use the async equivalent.
agno/tracing/exporter.py:112:16: CH006 `asyncio.create_task(...)` result is discarded;
    keep a reference (the loop only holds a weak ref, so the task may be GC'd mid-run).

Found 2 issue(s) (CH001: 1, CH006: 1)

Both of these became merged/​open fixes upstream. The first froze the Discord bot's event loop on every video/document attachment; the second could silently drop telemetry when its export task was garbage-collected mid-run. codehound found them in seconds — see docs/FINDINGS.md for the full provenance of every rule.

Why this exists

I was contributing bug fixes to large AI frameworks and noticed the same handful of mistakes recurring across codebases. Instead of hunting them by hand, I encoded each one as an AST rule. codehound is the result: point it at a repo and it finds the bugs I'd otherwise have to read 100k lines to spot.

It found the bugs behind these merged fixes — and is built to find the next one.

Install

pip install codehound

Zero dependencies — it's ~2,200 lines on top of the standard-library ast module, so this installs instantly and runs fully offline, no API key or network call involved.

pip install -e .

# or run straight from source, no install needed
PYTHONPATH=src python -m codehound.cli scan path/to/project

Usage

# scan a project (skips tests/, docs/, examples/, vendored code by default)
codehound scan path/to/project

# scan multiple files/directories in one invocation (what pre-commit does)
codehound scan file1.py file2.py src/

# only run specific checks
codehound scan path/to/project --select CH001,CH006

# machine-readable output for CI dashboards
codehound scan path/to/project --format json
codehound scan path/to/project --format csv

# GitHub Code Scanning (Security tab) can ingest this directly
codehound scan path/to/project --format sarif > results.sarif

# list every available check
codehound list

codehound scan exits non-zero when it finds issues, so it drops straight into CI:

- run: codehound scan src   # fails the build on a regression

GitHub Action

- uses: kratos0718/codehound@v1
  with:
    path: src
    # select: CH001,CH006        # optional, defaults to all checks
    # fail-on-findings: "false"  # optional, report without failing the build
    # upload-sarif: "false"      # optional, skip the Code Scanning upload

Uploads findings to the repo's Security → Code Scanning tab via SARIF, in addition to failing the step (unless fail-on-findings: "false").

pre-commit

repos:
  - repo: https://github.com/kratos0718/codehound
    rev: v1.4.1
    hooks:
      - id: codehound

The checks

codehound list prints this from the source of truth.

CH007-CH020 don't have found-and-merged bugs behind all of them the way CH001-CH006 do - most are hardening rules for well-known Python correctness gotchas rather than something this project personally tracked down first. CH010 and CH011 are the exceptions: both found genuine bugs on their own, in HuggingFace's accelerate, optuna, and llama_index - see below. Building CH007-CH010 surfaced real false positives, each one fixed before shipping:

• CH007 (agno): a bare self.foo() call matched against an unrelated same-named async def foo on a different class (agno's own sync/async "twin method" convention, e.g. ZepTools/ZepAsyncTools), and a plain callable parameter shadowed by an unrelated same-named async function hundreds of lines away in the same file.
• CH009 (llama_index): a thread handed off through a different object's attribute, not self - chat_response.write_response_to_history_thread = thread, with chat_response itself returned and the thread joined later once the caller finishes consuming the stream.
• CH010 (marimo): sorted(rows, key=lambda row: row[sort_arg.by]) inside for sort_arg in ... - the lambda references the loop variable, but sorted() calls it immediately, synchronously, before the next iteration moves sort_arg on. Nothing outlives the iteration. This reshaped the check entirely: it now only fires when a lambda is directly stored (.append(...), assignment, return), not merely passed as a callback argument to something that consumes it on the spot.

The accelerate find (CH010): MegatronEngine.get_module_config builds one callback per model chunk for distributed-training parameter sync: [lambda x: self.optimizer.finish_param_sync(model_index, x) for model_index in range(len(self.module))]. Every lambda captures model_index by reference; by the time any of them actually runs, the comprehension has finished and model_index holds its final value for all of them - whichever chunk's callback fires, it reports the last chunk's index. Fixed with the standard default-argument capture (model_index=model_index) and a regression test that fails on the pre-fix code (all three callbacks report index 2) and passes on the fix. PR: huggingface/accelerate#4273.

Scanning ~20 major Python AI/ML frameworks with the fixed CH007/CH008/CH009 turned up zero further real instances beyond the ones above - itself a result, not a null: CH008's bug fails immediately and unconditionally, so it's very unlikely to survive basic testing; CH007 and CH009 both only match same-file names by design, and most real cases of either are plausibly cross-module.

The optuna and llama_index finds (CH011): both are @lru_cache(maxsize= None) decorating an instance method - a strong reference to self retained forever. In optuna, _FanovaTree's node-lookup methods leak every tree built for a get_param_importances() call (one per random-forest estimator). In llama_index, VectaraIndex._get_corpus_key leaks the index itself - and since VectaraIndex.__del__ exists specifically to close the index's requests.Session on garbage collection, the leak silently disables that cleanup too, so an HTTP session leaks along with every index. Both fixed the same way: move the cache from a class-level decorator to a per-instance one built in __init__, so it's freed with the instance instead of outliving it. Both have a regression test verified to fail pre-fix and pass post-fix. PRs: optuna/optuna#6859, run-llama/llama_index#23089.

CH016 found and fixed its own false positive the day it shipped. The first real-corpus scan of unclosed-socket turned up three hits in vllm's distributed process-group rendezvous code - all three sockets were actually handed off correctly (returned inside a tuple, collected into a list that's itself returned, passed as an argument into a function that takes ownership), just not in a shape CH005 (the check this one was modeled on) ever needed to recognize, since files aren't handed off this way nearly as often as rendezvous sockets are. Fixed by treating a name as escaped when it's returned as part of a tuple/list or passed as an argument to any call. A full corpus rescan afterward found zero remaining CH016 hits.

Two checks we built and did not ship. exception-chaining (except X as e: raise Y(...) with no from e, discarding the real traceback - overlaps flake8-bugbear B904) worked exactly as designed, but at a scale that says more about how common the pattern is than about anything worth flagging: 1,911 hits across the same ~20-framework corpus. Shipping a check that fires that often would make every scan result mostly noise, undermining the "a finding must be defensible" standard the rest of this tool holds itself to.

cancelled-error-swallowed (except asyncio.CancelledError: pass - premise: silently swallowing task cancellation is a bug) went further than volume alone: the first two real hits checked, in two different frameworks, were both correct code, not bugs. agno's was existing_task. cancel(); try: await existing_task; except CancelledError: pass - the textbook-correct way to await a task's own cancellation. letta's was an explicit, logged recovery path (except (CancelledError, ...) as e: logger .info(...); <continue processing>) with a comment literally saying it was overriding the cancellation on purpose. Unlike the exception-chaining volume problem, this one meant the check's core premise was false in a large fraction of real occurrences - so it was deleted outright rather than kept at a lower confidence tier. Both are: built, measured, and deliberately left out - a real decision, not an oversight.

How it works

codehound/
├── core.py          # file discovery, AST parsing, the Finding/Check contract,
│                    #   and a child→parent map so checks can ask "what's my
│                    #   enclosing function / am I inside a `with`?"
├── cli.py           # `scan` / `list`, text|json|csv|sarif output, CI-friendly exit codes
├── sarif.py         # SARIF 2.1.0 output for GitHub Code Scanning
├── terminal.py      # colored text output (auto-disabled for non-TTY / NO_COLOR)
└── checks/          # one small, independently-tested class per rule
    ├── blocking_async.py     (CH001)
    ├── mutable_defaults.py   (CH002)
    ├── datetime_utcnow.py    (CH003)
    ├── get_event_loop.py     (CH004)
    ├── resource_leak.py      (CH005)
    ├── floating_task.py      (CH006)
    ├── unawaited_coroutine.py (CH007)
    ├── asyncio_run_in_loop.py (CH008)
    ├── floating_thread.py     (CH009)
    ├── loop_closure_capture.py (CH010)
    ├── lru_cache_on_method.py  (CH011)
    ├── floating_process.py     (CH012)
    ├── discarded_future.py     (CH013)
    ├── unprotected_lock.py     (CH014)
    ├── async_property.py       (CH015)
    ├── unclosed_socket.py      (CH016)
    ├── collections_abc_import.py (CH017)
    ├── removed_asyncio_task_methods.py (CH018)
    ├── removed_getargspec.py   (CH019)
    └── bare_except.py          (CH020)

Each check receives a parsed ast tree plus the precomputed parent map and returns Findings. Adding a rule is one file + one registry line + a test. See docs/ARCHITECTURE.md for a full walkthrough of the engine, the parent map, and the design decisions.

False-positive discipline is a feature. CH005 won't flag a handle that's returned (the caller owns it) or explicitly .close()d. CH006 won't flag TaskGroup.create_task (the group holds the reference). CH001 only fires when the enclosing function is async. CH007 scopes self.foo() matches to async methods on the same class as the call site, and bare foo() matches to module-level async functions that aren't shadowed by a same-named parameter. CH009 doesn't flag a thread handed off as any object's attribute, not just self. CH010 only fires when a lambda is directly stored (appended, assigned, returned), not merely passed as a callback argument that gets consumed on the spot. CH016 doesn't flag a socket returned as part of a tuple/list, or passed as an argument to any call (as opposed to being the receiver of a call on itself) — real patterns found in vllm's rendezvous code. CH020 won't flag a BaseException handler whose bound name is actually referenced, or whose body re-raises anywhere in its own scope (not counting a nested try/except's own handler) — both real patterns found in agno. All of those guards exist because of real false positives caught while building the checks (see above and docs/FINDINGS.md). The test suite asserts both "bad code is flagged" and "correct code is not."

Tests

pip install -e ".[dev]"
pytest -q

Every check has paired tests: the buggy pattern is flagged, and the idiomatic fix is not.

Roadmap

• await on a non-awaited coroutine (missing-await detection) — CH007
• PyPI release — pip install codehound
• asyncio.run() inside a running loop — CH008
• Non-daemon thread started without a join — CH009 (the thread analog of CH006)
• Loop-variable closure capture in lambdas — CH010
• Pre-commit hook — .pre-commit-hooks.yaml
• GitHub Action — action.yml, uploads SARIF to Code Scanning
• SARIF output — --format sarif
• Colored terminal output (auto-disabled for non-TTY / NO_COLOR)
• Multi-path scan invocation (what the pre-commit hook needs)
• 20 checks — memory leaks (lru_cache on methods), floating processes, discarded futures, unprotected locks, async properties, unclosed sockets, removed-in-3.9/3.10/3.11 stdlib APIs, bare except: — CH011-CH020
• Cross-module resolution for CH007/CH009 (currently same-file only)
• Sync HTTP clients constructed inside async request handlers
• --fix for the mechanical rules (CH002, CH003, CH004)

License

MIT © Abhinav Tarigoppula