orienting-codebases

Orienting Codebases

Interactive codebase orientation for the human, not the agent. Same tree-sitting + featuring pipeline as exploring-codebases, but synthesizes into guided HTML exercises via composing-html instead of analysis documents. See README.md for design rationale.

Pipeline

0. Setup (once per session)

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py
export COMPOSE=/mnt/skills/user/composing-html/scripts/build.py

1. Get the repo

OWNER=... REPO=... REF=main
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1

For local repos, skip the curl — point directly at the path.

2. Structural scan

$PYTHON $TREESIT /tmp/$REPO --stats

3. Feature gathering

$PYTHON $GATHER /tmp/$REPO \
  --skip tests,.github,node_modules --source-budget 8000

4. Targeted source extraction

For each exercise target identified from gather output, extract the actual source using treesit queries:

# Entry point source
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:main'

# Specific function for an exercise
$PYTHON $TREESIT /tmp/$REPO --no-tree 'source:validate_token'

# Imports for a hub file
$PYTHON $TREESIT /tmp/$REPO --no-tree 'imports:src/api.py'

This source feeds directly into the HTML artifact — the user sees real code, syntax-highlighted, without having to navigate the repo.

Do not show raw pipeline output to the user. It's material for exercise design. The user sees HTML artifacts and conversation.

Orientation session

After the pipeline steps, synthesize into an interactive orientation. Three phases.