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, rust-analyzer-backed Rust semantics, clangd-backed C-family semantics, structural fallbacks for Rust and C-family files, and tree-sitter-backed Markdown heading and section extraction.

Current implementation:

• Python structural parsing via tree-sitter.
• Rust semantic symbols, references, and callers via rust-analyzer when available.
• Rust structural parsing and fallback 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

Windows paths in plain text and JSON use forward slashes and omit the extended-path prefix (for example, H:/directory/file.py). UNC paths use //server/share/file.py.

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": "..."
}