codescope

codescope is a purpose-built Rust CLI for listing and extracting source symbols without opening large files.

Initial commands:

codescope list-functions --path .
codescope extract-function --name Namespace::Class::method --path src
codescope extract-symbol --name Foo --kind class --path .
codescope extract-variable --name CONFIG --scope Foo --path .
codescope list-headings --path docs
codescope extract-section --name Usage --path README.md
codescope references --name foo --path .
codescope callers --name foo --path .
codescope context --name foo --path .

The first production slice supports tree-sitter-backed Python extraction, clangd-backed C-family symbols and references, tree-sitter/lexical fallback for C, C++, CUDA, and HIP, and tree-sitter-backed Markdown heading and section extraction.

Current implementation:

• Python structural parsing via tree-sitter.
• C-family semantic symbols/references via clangd LSP when available.
• C-family structural fallback via tree-sitter and lexical scanning.
• Markdown headings and sections via tree-sitter.
• Codex skill packaging in skill/SKILL.md.

See docs/USAGE.md for command details.

Install Locally

After a tagged release exists, install the Windows binary and skill metadata with:

.\scripts\install-skill.ps1

To build from the current checkout instead:

.\scripts\install-skill.ps1-FromSource

The install script copies codescope.exe into %USERPROFILE%\.codex\bin and installs the skill metadata into %USERPROFILE%\.codex\skills\codescope. Release downloads are verified against SHA256SUMS when available.

Exit Codes

• 0: found at least one match
• 1: no matches
• 2: CLI or configuration error
• 3: explicitly required backend failed

JSON Output

Use --json for stable machine-readable records:

{
"path": "src/example.cpp",
"language": "cpp",
"backend": "lexical",
"kind": "function",
"name": "method",
"qualified_name": "Namespace::Class::method",
"start_line": 10,
"end_line": 42,
"source": "..."
}

{
"path": "README.md",
"language": "markdown",
"backend": "tree-sitter",
"kind": "heading",
"name": "Installation",
"qualified_name": "Usage.Installation",
"start_line": 10,
"end_line": 42,
"source": "..."
}