oneport-context

Code Contextualizer — NotebookLM for your codebase, that never leaves your machine.

Point it at any repo (however large — no upload) and it builds a hierarchical understanding locally, then turns it into a narrated architecture walkthrough, a narrated MP4 video, a PDF handbook, a chat that knows your code, and hover-to-explain in your editor. Runs on your own model key (Google Gemini free tier) or fully local — your code never leaves the machine.

Try it in 60 seconds (no setup)

pip install oneport-context
oneport-context demo

Opens a narrated, animated walkthrough of a bundled sample repo in your browser — no API key needed.

Use it on your own repo

onp account login <op_live_...>    # 0-BYOK: managed models, metered to your account
                                   # token: https://www.oneport.co.in/console

oneport-context index ./my-repo    # build the understanding (cached in .context/)
oneport-context show  ./my-repo    # narrated walkthrough in the browser
oneport-context video ./my-repo    # narrated MP4 (>= 8 min)   -> needs [video]
oneport-context pdf   ./my-repo    # PDF handbook, opens in browser -> needs [pdf]
oneport-context chat  ./my-repo    # ask questions in the terminal
oneport-context lsp   ./my-repo    # editor hover-to-explain -> needs [lsp]

Without a login it still works in heuristic mode (structure + docstrings) — free and offline, just less prose.

Keeping the index fresh

The index is cached in .context/ so show/video/pdf/chat are instant — but a cached index is a snapshot, and a stale snapshot drives a wrong tour. oneport-context checks the cache against your repo as it is now and tells you when it has drifted:

oneport-context index ./my-repo --check   # "index is stale — 3 added, 1 modified"; exit 1 if stale
oneport-context show  ./my-repo --fresh   # rebuild before showing (any command takes --fresh)

show/video/pdf/chat print a clear warning when they're driven by a stale index, rather than presenting it as current. index --check exits non-zero when stale, so you can wire it into a pre-commit hook or CI.

Tuning the scan

By default the walker skips the usual noise (node_modules, .venv, build output), respects your repo's .gitignore, and caps at 4000 files. Override any of that in an optional .oneport-context.yml at the repo root:

scan:
  ignore: ["generated/**", "*.pb.go"]   # extra glob patterns to skip
  languages: {".astro": "Astro"}        # index extra extensions as a language
  max_files: 12000                      # raise the cap for a big monorepo
  respect_gitignore: true               # (default) honor .gitignore

If the file cap truncates the scan, that's surfaced — a partial index is never presented as a complete one.

Commands

Install with the features you want

pip install 'oneport-context[video,pdf,lsp]'

• [video] — pillow, moviepy (ffmpeg), gTTS voice
• [pdf] — reportlab
• [lsp] — pygls

Why CLI, not upload

Big repos don't fit an upload box. The CLI walks the tree locally and builds a file -> module -> repo summary (module summaries are batched, so a large repo costs only a handful of model calls). Everything is cached in .context/; your code never leaves the machine.

Notes

• video/pdf/chat produce their best output when logged in (oneport-account login); heuristic mode works without it.
• Only structure travels to the model — file paths, symbol names, docstrings and the README, never raw file contents. Your code stays on your machine.

License

Apache-2.0