How tarekazabou/contextify works
1. Repo shape: mixed-language toolchain
- This repository is not a single app; it has a Python package in contextify/ and a TypeScript/Node layer in src/ with compiled output in out/.
- The Python side appears to be the core CLI/runtime, while the TypeScript side provides a CLI wrapper/extension integration and a bridge into the Python engine.
2. Primary user entrypoints
- The main command-line entrypoint is contextify/__main__.py, which likely dispatches into contextify/main.py.
- There are also shell/PowerShell launchers in scripts/ and a Windows .bat wrapper, which makes the tool runnable from different environments without manual wiring.
3. Core orchestration layer in Python
- contextify/main.py is the central coordinator for command execution.
- config.py handles environment/config loading and default behavior.
- onboarding.py manages setup/help/first-run flows.
- __init__.py exposes package metadata and package-level entrypoints.
4. Context collection and prompt assembly
- The core product behavior is: inspect the current repository, select relevant files, and generate a context-rich prompt or analysis report.
- The README’s flags map to a context-selection pipeline: --focus, --changed, --target, --tree-shake, --skeleton-context, --scope-function, and --git-aware.
- Sensitive-file filtering and .gitignore awareness are part of the filesystem scanning boundary, so the tool deliberately narrows what leaves the local repo.
5. AI/provider abstraction
- providers.py is the provider layer that chooses between Gemini, GitHub Copilot, OpenAI, Anthropic, or a local proxy.
- The repo treats provider selection as a configurable boundary, with priority rules based on available environment variables and optional explicit model selection.
- auth.py supports the GitHub Copilot path, including the README-described two-stage token exchange and header handling.
6. Enhancement/bridge boundary
- enhancer_bridge.py suggests a cross-runtime handoff, likely between the Python core and the TypeScript “enhancer” implementation.
- In src/core/enhancer.ts and src/core/pythonBridge.ts, the Node side appears to coordinate with Python rather than reimplement the whole engine, implying a split between orchestration and language/runtime-specific integration.
7. TypeScript/Node surface
- src/cli/index.ts is a Node CLI entrypoint, while src/extension.ts is the extension-facing integration point.
- This layer is compiled into out/, so the checked-in JS is the distributable artifact, not the source of truth.
- The Node side likely handles packaging, editor integration, and invoking the Python-side capabilities through the bridge.
8. Analysis mode as a separate product path
- --analyze is a distinct workflow from prompt generation.
- Static analysis produces architecture/structure/dependency/code-statistics style output, while --analyze --ai escalates that through an AI provider for deeper narrative analysis and recommendations.
- This means the system has two high-level flows: prompt generation and project analysis.
9. External dependencies and runtime concerns
- The project depends on Python 3.9+ and a Node/TypeScript build chain (package.json, tsconfig.json, package-lock.json).
- External integrations include clipboard support, Git history/diff inspection, environment variables, and the AI provider APIs themselves.
- requirements.txt and .env.example indicate the Python runtime is expected to be environment-driven rather than hardcoded.
10. Build and distribution boundary
- src/ is source; out/ is generated JavaScript with source maps.
- That separation matters architecturally: the repo supports both development-time TypeScript editing and runtime delivery via compiled assets.
- Tests are minimal in-tree (tests/test_simple.py), suggesting the current emphasis is on CLI/tooling behavior rather than a large application domain model.
11. Operational data flow
- User input enters via CLI/extension → config/env are loaded → repository context is scanned and filtered → files/metadata are selected → provider/auth logic is applied if AI output is needed → final prompt or analysis is emitted.
- Output can be routed to clipboard, stdout, or a file, so the final boundary is intentionally flexible for human-in-the-loop use.
Main entry points: main.py Main orchestrator · pythonBridge.ts Python bridge · package.json Node package · index.ts Node CLI
Components 19
Python core
CLI runtime, config, scanning, provider selection, and AI/auth boundaries.
- CLI entry · Module entry that starts the Python command-line flow.
contextify/__main__.py - Main orchestrator · Central command dispatcher for prompt generation and analysis workflows.
contextify/main.py - Config loader · Loads environment-driven settings and defaults.
contextify/config.py - Onboarding · Handles first-run guidance and setup-related user flows.
contextify/onboarding.py - Providers · Selects and configures AI backends such as Gemini, Copilot, OpenAI, Anthropic, or local proxy.
contextify/providers.py - Copilot auth · Supports GitHub Copilot token exchange and request header handling.
contextify/auth.py - Enhancer bridge · Cross-runtime handoff between Python core and the Node enhancer surface.
contextify/enhancer_bridge.py
Node layer
TypeScript source and compiled runtime for CLI and extension integration.
- Node CLI · TypeScript command-line entrypoint used by the Node wrapper.
src/cli/index.ts - Extension API · Editor/extension-facing integration surface.
src/extension.ts - Enhancer · Node-side enhancement coordination layer.
src/core/enhancer.ts - Python bridge · Invokes or coordinates with the Python engine from Node.
src/core/pythonBridge.ts - Built CLI · Distributable JavaScript output for the Node CLI.
out/cli/index.js - Built extension · Distributable JavaScript output for the extension surface.
out/extension.js - Built enhancer · Compiled output of the Node enhancement core.
out/core/enhancer.js - Built bridge · Compiled output of the Node-to-Python bridge.
out/core/pythonBridge.js
Operational surface
Scripts, examples, and distribution helpers for setup and execution.
- Install scripts · Setup and installation helpers for local environments.
scripts/install.sh - Launchers · Platform launch wrappers for running the tool from different shells.
scripts/contextify.bat - Python deps · Python runtime dependencies and environment expectations.
requirements.txt - Node package · Node/TypeScript build, packaging, and runtime metadata.
package.json
Connections 20
- CLI entry → Main orchestrator: dispatches · Python module entry hands off to the main coordinator.
- Main orchestrator → Config loader: loads · Main flow reads environment and default configuration.
- Main orchestrator → Onboarding: guides · Main flow can invoke setup or first-run guidance.
- Main orchestrator → Providers: selects · Main flow chooses AI providers when generation or analysis needs them.
- Providers → Copilot auth: auth path · Copilot provider uses the dedicated authentication boundary.
- Main orchestrator → Enhancer bridge: bridges · Python core can hand off enhancement work across the runtime boundary.
- Node CLI → Python bridge: invokes · Node CLI routes execution through the bridge layer.
- Extension API → Enhancer: uses · Extension surface depends on the Node enhancement core.
- Enhancer → Python bridge: coordinates · Enhancer delegates Python-specific work through the bridge.
- Python bridge → Enhancer bridge: handoff · Node bridge connects to the Python bridge boundary.
- Python bridge → Main orchestrator: executes · Bridge ultimately drives the Python orchestrator.
- Built CLI → Node CLI: builds from · Compiled CLI is generated from the TypeScript source.
- Built extension → Extension API: builds from · Compiled extension is generated from the TypeScript source.
- Built enhancer → Enhancer: builds from · Compiled enhancer is generated from the TypeScript source.
- Built bridge → Python bridge: builds from · Compiled bridge is generated from the TypeScript source.
- Launchers → CLI entry: launches · Shell and PowerShell wrappers make the Python entrypoint easy to run.
- Install scripts → Node package: sets up · Install helpers support the Node toolchain and runtime setup.
- Node package → Node CLI: packages · Package manifest defines the Node CLI build and distribution.
- Node package → Extension API: packages · Package metadata also covers the extension surface.
- Python deps → Main orchestrator: supports · Python dependency spec supports the core runtime.