repoflux

repoflux

Deterministic repository context bundler and Model Context Protocol (MCP) server for language model workflows.

repoflux packages entire codebases into structured, token-bounded context payloads for OpenAI Codex, ChatGPT, Cursor, and autonomous coding agents. It scans repositories, parses AST declarations, calculates exact BPE token weights, strips credentials, and hosts an stdio MCP server for agentic IDEs.

---

Installation & Quick Start

Execute directly via npx:

# Bundle repository into default XML context
npx repoflux

# Copy prompt context directly to clipboard
npx repoflux -c

# Extract symbol outlines (functions, classes, interfaces) without loading file bodies
npx repoflux -s

# Only pack files changed in uncommitted git diff
npx repoflux -d

# Generate interactive HTML report with token distributions
npx repoflux --html

# Inspect project dependencies across Node, Rust, Python, Go
npx repoflux --deps

# Run live watch mode to regenerate bundle on file save
npx repoflux -w

Or install globally:

npm install -g repoflux

---

Technical Capabilities

• Zero-Dependency Architecture: Written in native TypeScript with no external runtime dependencies, providing sub-50ms execution.
• Symbol Outline Extraction (-s): Parses declarations and function signatures across TypeScript, JavaScript, Python, Go, and Rust without bloating context windows.
• Git Diff Scoping (-d): Isolates uncommitted changes or recent commit deltas for pull request code reviews.
• Automated Credential Redaction: Scans files against regex patterns for OpenAI, Anthropic, AWS, GitHub, Stripe, and private keys, replacing them with redaction placeholders.
• Deterministic Token Budgeting (-m): Estimates BPE subword tokens using cl100k/o200k calibrated heuristics and enforces hard budget ceilings.
• Model Context Protocol (MCP): Connects to OpenAI Codex, Cursor, and developer agents as an stdio server with tools for repo mapping, symbol inspection, and diff analysis.
• HTML Visualizer (--html): Compiles an offline, single-file HTML report with token distribution statistics and code trees.
• Exclusion Engine: Parses .gitignore and .repofluxignore alongside standard build and binary file exclusions.

---

Command-Line Interface

Option	Flag	Description	Default
--out	-o	Output file path	repoflux-output.<format>
--format	-f	Serialization format (xml, markdown, json)	xml
--max-tokens	-m	Hard token budget limit	Unlimited
--clipboard	-c	Copy output bundle directly to system clipboard	false
--outline	-s	Extract function and class signatures only	false
--diff	-d	Filter bundle to modified files from git diff	false
--deps		Print dependency graph across package manifests	false
--html		Generate self-contained HTML inspection report	false
--watch	-w	Watch filesystem and re-bundle on save	false
--prompt	-p	Prepend custom instructions or system prompt	None
--tree	-t	Print directory tree with token distribution	false
--mcp		Launch MCP JSON-RPC server over stdio	false
--no-redact		Disable automatic credential sanitization	false

---

OpenAI Codex & ChatGPT Integration

repoflux compiles structured codebase context optimized for OpenAI models (GPT-4o, o1, o3, Codex):

Web & CLI Pair Programming

Generate a sanitized, token-budgeted prompt bundle directly to clipboard and paste into ChatGPT Pro / Codex:

# Bundle whole repo and copy to clipboard
npx repoflux -c

# Pass symbol outlines for fast architectural review
npx repoflux -s -c

GitHub Actions PR Review Bot with OpenAI

Automate incoming pull request reviews in CI using repoflux and the OpenAI API:

- name: Bundle Changed Files
  run: npx repoflux -d -f markdown -o pr_context.md

- name: Run Codex Review
  run: |
    curl https://api.openai.com/v1/chat/completions \
      -H "Authorization: Bearer ${{ secrets.OPENAI_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d "{\"model\": \"gpt-4o\", \"messages\": [{\"role\": \"user\", \"content\": \"Review this pull request diff: $(cat pr_context.md)\"}]}"

---

Model Context Protocol (MCP) Configuration

For agentic IDEs and OpenAI coding assistants (such as Cursor or MCP-enabled agents), add repoflux to your MCP configuration file:

{
  "mcpServers": {
    "repoflux": {
      "command": "npx",
      "args": ["-y", "repoflux", "--mcp"]
    }
  }
}

Available MCP Tools

• get_repo_map: Returns ASCII directory tree with per-file token allocations.
• pack_codebase: Returns full sanitized repository context bounded by token limits.
• get_symbol_outline: Returns AST function and class outlines.
• get_git_diff: Extracts current diff for review workflows.
• get_dependencies: Returns dependency manifest details.
• audit_secrets: Audits repository files for leaked credentials.

---

Test Suite & Verification

# Build TypeScript
npm run build

# Run native test runner
npm test

---

License

MIT License (c) 2026 apple sauce