Codebase Genome Pipeline

Issue: timmy-home#665

This pipeline gives Timmy a repeatable way to generate a deterministic GENOME.md for any repository and rotate through the org nightly.

What landed

pipelines/codebase_genome.py — static analyzer that writes GENOME.md
pipelines/codebase-genome.py — thin CLI wrapper matching the expected pipeline-style entrypoint
scripts/codebase_genome_nightly.py — org-aware nightly runner that selects the next repo, updates a local checkout, and writes the genome artifact
GENOME.md — generated analysis for timmy-home itself

Genome output

Each generated GENOME.md includes:

project overview and repository size metrics
Mermaid architecture diagram
entry points and API surface
data flow summary
key abstractions from Python source
test coverage gaps
security audit findings
dead code candidates
performance bottleneck analysis

Single-repo usage

python3 pipelines/codebase_genome.py \
  --repo-root /path/to/repo \
  --repo-name Timmy_Foundation/some-repo \
  --output /path/to/repo/GENOME.md

The hyphenated wrapper also works:

python3 pipelines/codebase-genome.py --repo-root /path/to/repo --repo Timmy_Foundation/some-repo

Nightly org rotation

Dry-run the next selection:

python3 scripts/codebase_genome_nightly.py --dry-run

Run one real pass:

python3 scripts/codebase_genome_nightly.py \
  --org Timmy_Foundation \
  --workspace-root ~/timmy-foundation-repos \
  --output-root ~/.timmy/codebase-genomes \
  --state-path ~/.timmy/codebase_genome_state.json

Behavior:

fetches the current repo list from Gitea
selects the next repo after the last recorded run
clones or fast-forwards the local checkout
writes GENOME.md into the configured output tree
updates the rotation state file

Example cron entry

30 2 * * * cd ~/timmy-home && /usr/bin/env python3 scripts/codebase_genome_nightly.py --org Timmy_Foundation --workspace-root ~/timmy-foundation-repos --output-root ~/.timmy/codebase-genomes --state-path ~/.timmy/codebase_genome_state.json >> ~/.timmy/logs/codebase_genome_nightly.log 2>&1

Limits and follow-ons

the generator is deterministic and static; it does not hallucinate architecture, but it also does not replace a full human review pass
nightly rotation handles genome generation; auto-generated test expansion remains a separate follow-on lane
large repos may still need a second-pass human edit after the initial genome artifact lands

2.5 KiB Raw Blame History