Contexter

Contexter is a powerful suite of Python command-line tools for packaging, reconstructing, and updating software projects as single, portable Markdown or HTML files. This workflow is perfect for sharing entire projects with AI models, creating simple text-based backups, or transferring projects between machines.

Key Features

• Context Packaging: Bundle your entire project source code into a single, AI-friendly Markdown (.md) or HTML (.html) file.
• Project Reconstruction: Rebuild a working project directory structure from a Contexter context file.
• AI Workflow Integration: Tools specifically designed to clean up and process code generated by LLMs.
• Smart Updates: efficiently update context files using diffs/patches or rsync-like logic.
• Context Version Control: Track and revert changes in your project using trackcontext (a lightweight, snapshot-based VCS).
• Format Conversion: Convert context files between Markdown and HTML formats.

Installation

Prerequisites

• Python 3.7 or higher
• pip (Python package installer)

Quick Install

1. Clone the repository:

   git clone -b cli https://github.com/ray0404/Contexter.git
   cd Contexter

2. Install the package:

   pip install .

   For development (editable mode):

   pip install -e .

3. Verify installation:

   buildcontext --help

Usage

Command Reference

Command	Description
buildcontext	Packages a directory into a single Markdown file.
reconstructor	Rebuilds a project from a Markdown context file.
sanitizecontext	Fixes AI-generated Markdown to be a valid Contexter file.
updatecontext	Creates a patch file by comparing two .md context files.
updater	Applies a patch file to an .md context file.
smartupdate	(Recommended) Creates a patch using rsync for high efficiency.
trackcontext	Manages project snapshots and history (commit, log, revert).
buildcontexthtml	Packages a directory into a single HTML file.
reconstructorhtml	Rebuilds a project from an HTML context file.
updatecontexthtml	Creates a patch (.md or .html) from two .html files.
updaterhtml	Applies a patch (.md or .html) to an .html file.
md2html	A utility to convert any Markdown file to HTML.
html2md	A utility to convert any HTML file to Markdown.

Run any command with -h or --help for detailed options (e.g., buildcontext --help).

Common Workflows

1. The AI Loop (Generate -> Sanitize -> Build)

This workflow is ideal when you ask an AI to "generate a project" and it gives you a long markdown response.

1. Save the Output: Copy and paste the AI's full response into a file named ai_output.md.
2. Sanitize: AI models often make formatting mistakes (like missing code fences). Use sanitizecontext to fix them:

   sanitizecontext ai_output.md clean_project.md

3. Reconstruct: Turn the text back into files and folders:

   reconstructor clean_project.md ./my-new-project

2. Context Sharing

To share your project with an AI for review or features:

1. Build Context:

   buildcontext context.md ./src ./include --exclude "*.log" --exclude "__pycache__"

2. Upload: Upload context.md to the AI chat.

Troubleshooting

"Command not found" after installation

If you installed with pip but the commands are not available:

1. Check your PATH: Ensure your Python user bin directory is in your system's PATH.
2. Legacy Workaround: If you still cannot get the global commands to work, you can use the legacy alias script:

   python3 create_aliases.py
   source ~/.bashrc  # or ~/.zshrc / ~/.profile