find_dead_code
Detect C/C++ functions defined but never referenced anywhere in the indexed codebase, so you can find dead and possibly dead symbols before deleting code.
Instructions
Find C/C++ functions that are defined but never called — libclang-powered dead code detection across the entire indexed codebase. Distinguishes called from uncalled symbols globally, not just within a single file — text-based search cannot determine whether a function is actually reachable.
What "dead" means: zero references of any ref_kind in the
index — no call, no read, no function-pointer use, no vector slot.
Only functions, methods, constructors, and destructors with a
definition are checked. This is a
single-layer reference check, NOT a reachability analysis from the
entry points (main, ISR, exported symbols): a function that only a
second dead function calls still has a reference, thus this tool does
not mark it. For transitive reachability, trace from your entry points
with find_callees_recursive.
The status field splits the results:
"dead"— no reference at all. Likely unused."possibly_dead"— assigned to a function pointer (ref_kind="indirect") and never called directly, but no call site through that pointer resolved. Unindexed code or a type-erased API can still call it. Treat it as uncertain, and check each hit withfind_indirect_targetsbefore you delete anything.
fw-context detects a constructor call through global/static object and
member-field initialization as an implicit_construct reference.
ISRs: a handler that an assembly vector table names (.word) has a
vector reference, and one that NVIC_SetVector installs has a
runtime_vector reference, thus neither is reported. A handler in
a table that the build generates in C has an indirect reference
and can show as possibly_dead. A handler that no readable table
names (a slot with a linker-resolved address; arm64, Xtensa, MIPS
tables of branch instructions) shows as dead. Use
get_vector_table to check.
Other known false positives: constructors from factories, virtual method overrides, and weak-aliased symbols. Always verify before you delete.
project_only=True (default) excludes the SDK and vendor paths
through the is_project column, which follows the vendor_paths
and project_paths config. Set project_only=False to see the
vendor results too. No config default is added to
exclude_paths.
Read-only. No side effects. Requires the reference index
(fw-context index — refs on by default).
Args:
project_root: Project root. Auto-detected if omitted.
project: Project name or project_id — call list_projects to get them. Use
it to ask about a project that is not the project of the current
directory. It is an alternative to project_root, which takes a root
path. Give one of the two, not both.
limit: Maximum results of one page (default 100, max 200).
offset: Skip this many results. Reads the next page; the page
notice names the offset to use.
exclude_paths: Additional LIKE patterns to exclude (user-supplied
tool parameter, not config). E.g. ['lib/%'].
project_only: When True (default), filters to is_project = 1
symbols. Set False to see all results.
variant: Variant of the build (a board, or a PlatformIO
environment). On a project of more than one build, give the
arguments of one build as the refusal lists them: the
variant, the image, or the two. fw-context does not select a
build. One query answers for ONE build.
image: Image of the build: a separate program, such as the
application or the bootloader. Give it when the build has an
image name.
Returns:
The page notice first — total, offset, shown, more
— then a dict per function with: name, qualified_name, kind,
signature, file (str — absolute), line, status ("dead" or
"possibly_dead"), and reason (str — explains why the function
is classified as dead or possibly dead). A "possibly_dead" row
also holds indirect_refs (str — up to 3 file:line pointer
uses, absolute paths, joined with ", "). "dead" rows come
first.
Never empty: one dict with ``error`` or ``info`` replaces an empty
result. Check both keys first.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. | |
| limit | No | Maximum results of one page (default 100, max 200). | |
| offset | No | Skip this many results. Reads the next page of a long report. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build for you. One query answers for ONE build. | |
| project_only | No | When True (default), keeps only project code (is_project, from the vendor_paths/project_paths config and SDK detection). Set False to see all results. | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. | |
| exclude_paths | No | LIKE patterns on the project-relative file path to exclude, on top of project_only. E.g. ['lib/%']. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |