CodeGuide is a CLI that reads a code repository

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

CodeGuide is a CLI that reads a code repository and writes an onboarding guide for
a new developer. It outputs ONBOARDING.md and a single-file HTML report with a
searchable file tree and dependency graph.

I read the theme as the ghosts inside old codebases: the engineer who left, the
reason a strange function exists, the folder nobody dares touch. That knowledge
is in the code but nobody wrote it down. CodeGuide tries to bring it back, and it
only says what it can point to. Every claim cites a file and line range, or is
marked "unclear". A ghost story without evidence is just a rumor.

I built it because new hires spend their first week asking the same questions
in Slack, and the answers are already in the repo.

Demo

[Link to video or deployed report]

Sample run on [repo name]:https://github.com/brobengali/codereviewer
codeguide scan ./repo --offline
[Screenshot of the generated ONBOARDING.md and the HTML report]

Code

[GitHub repo link or embed]

How I Built It

• Python 3.11+, Typer for the CLI, pydantic for config and output validation, tree-sitter for parsing, Jinja2 for prompts and report templates.
• Local inference: with --offline, only a local OpenAI-compatible server is allowed ([Ollama / llama.cpp], model: [open-weight model you used]). No code leaves the machine. Gemini is an optional provider for people who want it.
• Untrusted input: the target repo is never executed. No install scripts, tests, or git hooks run. Secrets are redacted before any model sees the code.
• Prompt injection defense: repo text goes into a data block with a random per-request boundary token. The model gets no tools, and its output must pass a strict JSON schema with citations or it is rejected.
• No hard-coded values: models, limits, ignore patterns, detection rules and prompts all live in config, rule files and templates.
• Slop gate: codeguide lint-docs flags uncited, generic, or repeated sentences in generated docs, and a grounding pass checks that every cited line exists.

I built it step by step with a coding agent, one reviewed milestone at a time.

Why Does Open Innovation Matter?

The people who most need a codebase explained are often the ones who can't send
it to a third party: private repos, client code, regulated industries. Open-weight
models and local inference make --offline possible, so the code never leaves
the machine. A closed API would have forced a trade-off between a useful
onboarding guide and a data-policy violation.

Open tooling also means anyone can inspect the prompts, the redaction rules and
the rule files, then change them. Adding a new language is a data file, not a
fork of the core.

My Agent Session

[Link or agent_session embed, or remove this section]

The Spirit of It

[Optional: one real moment. For example, the first time it explained a repo
you had never opened and you checked the cited lines and they were right.
Or the first time it said "unclear" instead of making something up.
If you don't have one, delete this section.]

Prize Categories

[List the partner categories that apply after checking the challenge page.
Candidates: anything tied to local or open-weight inference. Otherwise remove.]