groktools groktools is a suite of publicly available tools designed to make developing Python scripts with Grok bulletproof. It provides a set of utilities to maintain scripts with consistent versioning, changelogs, prompt storage, and automated patching, ensuring clarity and traceability even at 3am. Whether you’re managing complex data processing scripts like process_527_stats.py or building visualizations, groktools helps you keep your code organized, documented, and easy to update. Features

Automated Patching: Generate and apply patches to Python scripts with patchBuilder.py and grokpatcher.py. This is critical when you hit the resource limits for grok. Version Tracking: Maintain a VERSION constant to track script versions. Change Logging: Keep a Change Log section to record updates, artifact IDs, and prompts. Prompt Storage: Add grok:-annotated comments for documentation and context restoration, with fileref: support for external files. Context Restoration: Bootstrap conversations by parsing grok: annotations with the Restart tool. Best Practices: Follow coding standards for consistency and maintainability (see bestpractices.md).

Project Structure

src/: Contains the user side tools: docs/prompts: contains the grok side tools (i.e. prompts) docs/: Documentation for each tool (e.g., grokpatcher.md, patchBuilder.md). docs/prompts/: Prompt files for Grok to use the tools (e.g., groktools_meta_prompt.md). examples/: Example scripts, patches, and a script to test patching (apply_patches.sh).

Installation

Python: Ensure Python 3.8+ is installed. GNU Tools: Install diff and gpatch, as the system patch (e.g., on macOS) is unreliable. macOS: brew install diffutils gpatch Linux: Typically pre-installed as diff and patch. grok: grok-side tools aka "prompts" can be referenced via https://github.com/twinforces/groktools/raw/refs/heads/master/docs/prompts/groktools_meta_prompt.md or the equivalent for the individual tools i.e: https://github.com/twinforces/groktools/raw/refs/heads/master/docs/prompts/*.md.

Ensure Requirements:

Python 3.6+ is installed. No external dependencies are required beyond the standard library.

Explore the Tools:Use Grok to interact with the suite by referencing the meta prompt:

Tell Grok to read docs/prompts/groktools_meta_prompt.md to use all features. Or cherry-pick specific tools using docs/prompts/*_prompt.md files (e.g., grokpatcher_prompt.md).

Try the Examples:The examples/ directory contains sample scripts and patches to demonstrate usage: cd examples chmod +x apply_patches.sh ./apply_patches.sh

Follow the instructions in examples/README.md to apply patches using pbcopy and grokpatcher.py.

User Side Tools

GrokPatcher: Service that takes grokpatch pastes to update files using natural and artificial anchors. PatchBuilder: Generates grokpatch files by comparing before and after versions of a script, automatically incrementing the VERSION. diffextract: Extracts and unescapes unified diffs from .grokpatch files for gpatch. Usage: python src/diffextract.py file.grokpatch | gpatch -p1.

Grok Side Prompts

Versioning: Maintains a VERSION constant to track script versions. Changelogs: Keeps a Change Log section to record version updates and artifact IDs. Prompt Storage: Adds grok:-annotated comments for documentation and context restoration. Restart: Bootstraps conversations by parsing grok: annotations, with optional Change Log enhancement. Best Practices: Things I've found useful to tell grok to do when generating code.

.grokpatch Format A .grokpatch file wraps a unified diff for safe transmission and application:

Metadata: !INPUT: and !OUTPUT: specify input and output files. Unified Diff: Follows docs/prompts/diffu_prompt.md, generated by diff -u on the user side, with backticks escaped (e.g., \code``) for copypasta boxes. EOF Marker: !GO! at the end signals patch completion. Patch Set Terminator: !DONE! marks the end of multiple patches.

Example: !INPUT: script.py !OUTPUT: script.py --- script.py +++ script.py @@ -1,3 +1,4 @@ def main(): print("Hello")

• print("World")

• print("Grok with `code`") return !GO!

Standards

Unified diffs align with GNU diffutils (https://savannah.gnu.org/projects/diffutils). Prompts in docs/prompts/ are modular tools, read by Grok as components of the Grok programming language (e.g., diffu_prompt.md for diffs).

Contributing We welcome contributions to groktools! To contribute:

Fork the repository at https://github.com/twinforces/groktools. Submit pull requests with new features or bug fixes (e.g., enhancing patchBuilder.py with interactive input). Report issues via GitHub Issues.

License MIT License. See LICENSE for details.