ReflectionCLI 2.0: a local-first thinking CLI for AI-assisted development

#ai #cli #productivity #tooling

The original concept behind this tool won the runner-up award for the Github CLI Challenge earlier this year.

As a reminder, ReflectCLI is a tool to promote thoughtful coding through structured reflection.

What does it do?

Before each commit, answer reflective questions to build your personal developer knowledge dataset.

The tool is local-first by design. It stores everything locally inside the current Git repo:

.git/git-reflect/log.json

No account, no cloud sync, no authentication, and no external AI API call.

Why build it?

AI-assisted development is powerful, but it can encourage cognitive offloading, letting tools do the thinking instead of developing deeper understanding. git-reflect interrupts this pattern by making reflection part of your workflow.

Each answer becomes part of your personal knowledge base, documenting not just what you built, but why you built it that way and what you learned. Over time, this dataset reveals patterns in your thinking and helps you grow as a developer.

If you want to read about the original tool, check out my previous post here.

Since building the original version, I've spent months researching how AI changes the way developers learn, reason, and make technical decisions.

Many of the ideas from those discussions have now been incorporated into ReflectionCLI 2.0.

What started as a simple Git pre-commit reflection hook has evolved into a local-first thinking tool for developers working alongside AI assistants.

What's New

Comprehension debt tracking

You can now record artifacts you shipped but don't fully understand yet.

reflection debt add "Understand why the cache invalidates on user updates" \
  --project api \
  --tags cache,ai \
  --context "AI generated most of the invalidation logic"

These artifacts can easily be retrieved and resolved later.

reflection debt list
reflection debt resolve debt-001

Explain-back mode

This workflow focuses on active recall and asks a series of questions to assess your ability to explain the piece of code.

reflection explain

AI outsourcing audit

Checks whether too much judgment was outsourced to AI in a coding session.

reflection audit \
  --ai-generated yes \
  --verified no \
  --can-explain no \
  --edge-cases no \
  --alternatives no \
  --challenged no \
  --create-debt

Decision journal

You can record your technical decisions directly from the terminal.

reflection decide \
  --project api \
  --tags caching,performance \
  --title "Use Redis for session cache" \
  --context "Need shared cache across instances" \
  --options "Redis|In-memory cache|Database table" \
  --chosen "Redis" \
  --reasoning "Shared state and expiry support are built in" \
  --tradeoffs "Adds infrastructure dependency" \
  --expected "Lower latency and consistent sessions" \
  --review-date 2026-06-16

And review that decision at a later stage.

reflection decision review decision-001

Weekly thinking report

Generate a local Markdown report from your reflection data to summarize learning, surface unclear areas, AI usage types, comprehension debt levels and opportunities to improve.

reflection weekly --output weekly-thinking-report.md

Prompt reflection

This workflow is for reviewing prompts you used with AI so you can improve future prompting.

reflection prompt \
  --project cli \
  --tags prompts,testing \
  --prompt "Write unit tests for this parser" \
  --goal "Improve parser coverage" \
  --output "Generated happy path tests" \
  --worked "It identified basic branches" \
  --unclear "It did not know our edge cases" \
  --assumptions "Parser behavior was fully visible" \
  --lessons "Include edge cases and expected failures"

Direct reflection command You can reflect on your work through intentional thinking sessions, not just during commits.

reflection learn
reflection explain
reflection audit
reflection weekly

The goal here is not to avoid AI.

It's to ensure that while AI helps us write code faster, we continue building the understanding, judgment, and decision-making skills that make us better engineers over the long term.

If you want to check out the tool, it is open source here.

Let me know your thoughts on the new features and if you have any ideas for further improvements!