Introducing Puzzlegrep:

By /

Grep for Structured Code Tags (and AI-Aware Source)

Published: July 3, 2025 Tags: code search, dev tools, AI, RobokeyTags, open source, Bun

Why “Context” in Code Matters – More Than Ever

If you’ve ever found yourself endlessly scrolling for TODOs, wondering “where’s that AI refactor suggestion?” or wishing you could grep by meaning and not just plain text, you’ll know the pain that inspired this project.

In my own projects; and as AI coding assistants get more capable: I found myself needing a new class of tooling:

Something that lets both humans and bots search for rich, structured context, not just raw code or plain comments.

Code Comments Aren’t Enough (Not for Humans or AI)

Traditional comments are informal and inconsistent.

A TODO here, a FIXME there, and, increasingly, “AI suggestion”.

They’re useful, if you can find them. But as teams grow (and bots join the team!), scattered context becomes invisible, and even grep or ripgrep falls short:

  • Grep finds words, not meanings or regions
  • Comments can be duplicated, typo’d, or missed entirely
  • AI agents can’t reliably parse intentions from free text

Enter RoboKeyTags: A Universal Markup for Code Regions

So I started developing RoboKeyTags:

A structured, language-agnostic way to annotate code regions, notes, and intent that uses standardized tags like:

JavaScript

[🧩 Section: api/auth]
...code...
[/🧩 Section: api/auth]

[📌 Note: refactor] Remove legacy login
[🤖 Region: ai/suggestion]

With RoboKeyTags, meaningful context becomes discoverable, both for humans and for LLMs, code agents, or CI tools.

But How Do You Find All Those Tags? Introducing Puzzlegrep

Meet Puzzlegrep! Its a CLI tool to search, filter, and report on RoboKeyTags (and similar) anywhere in your codebase.

  • Filter by marker: Find just human (📌), tool (🧩), or AI (🤖) tags
  • Filter by tag-type: E.g. --tag-type=Note to see only notes
  • Pattern-match by path, region, or description
  • Output as text or JSON (for CI, scripts, or bots)
  • Language-agnostic: Works on any source file, any language

Real-World Examples

Find all human-written notes in your codebase:

Bash

bun tools/puzzlegrep/puzzlegrep.js --pin --tag-type=Note "**/*"

Find all tool-generated, non-editable regions:

Bash

bun tools/puzzlegrep/puzzlegrep.js --puzzle --tag-type=Region "**/*::NonEditable*"

Output every AI suggestion as JSON (for scripting/analytics):

Bash

bun tools/puzzlegrep/puzzlegrep.js --robot --tag-type=Note "**/*" --json

Sample output:

Bash

dummy/src/a.ts:
  [📌 Note: refactor] → dummy/src/a.ts::refactor

dummy/notes/readme.md:
  [📌 Note: docs] → dummy/notes/readme.md::docs

How It Works

Puzzlegrep scans your files (supports globs/wildcards), finds RobokeyTags blocks, and lets you slice and dice by marker, subtype, path, or text.

It’s built for speed, hackability, and integration—no dependencies beyond Bun or Node.

Get Started

Requirements:

  • Recommended: Use the prebuilt binaries (no other runtime required)
  • Or run from source with Bun (preferred) or Node.js

Install/Run:

  • With prebuilt binary:
    Download the release for your platform and run: sh CopyEdit ./puzzlegrep --help
  • Or, run from source: sh CopyEdit git clone https://github.com/robokeys/robokeytags-tools.git cd robokeytags-tools/tools/puzzlegrep bun puzzlegrep.js --help # or: node puzzlegrep.js --help

For full usage docs, see puzzlegrep.md.

Why Not Just Use Grep?

Because grep (and ripgrep) don’t know about structured meaning, authorship, or region boundaries.

Puzzlegrep does.

It finds just the regions you care about! Not every comment or variable. It enables AI and human cooperation, discoverable from the codebase itself.

What’s Next?

  • More CLI tools (tree visualizer, tag stats, IDE integration?)
  • Community feedback – PRs, issues, and suggestions very welcome!
  • If you want to adopt RobokeyTags or build your own tools, read the spec, or drop me a message.

Puzzlegrep Is Just the Beginning

Puzzlegrep is only the first of many tools and pieces of the puzzle, I’m building for RobokeyTags. My vision is for a whole ecosystem:

Search, visualization, code analysis, even collaborative code agents, all working together on a foundation of discoverable, structured context.

I promise to make something special!

But you don’t have to wait for the future: Puzzlegrep is available right now, and it’s the first step to making RobokeyTags not just a spec, but a living, usable reality in real-world code. Give it a try, and watch this space as more pieces come together!

Thanks for Reading!

If you try Puzzlegrep, let me know how it goes!

File issues, star the repo, or just send feedback. I’m building this to solve real developer (and future AI) pain.

Rob Deas robd.tech robokeys.tech GitHub: robokeys/robokeytags-tools

Scroll to Top