Building a Production CLI Tool to Gamify and Enforce Code Documentation with GitHub Copilot CLI

This is a submission for the GitHub Copilot CLI Challenge

What I Built

Cognitive Guard - A CLI tool that analyzes code complexity and blocks commits when complex functions lack documentation. It uses cognitive complexity (not just lines of code) and adds gamification to make documentation less painful.

🔗 GitHub: cognitive-guard


📦 PyPI: pip install cognitive-guard

Core Features

• Analyzes cognitive complexity using AST parsing


• Blocks git commits with undocumented complex code


• Interactive TUI for fixing violations in-terminal


• Achievement system with progress tracking


• Multi-language support (Python, JS, TS)

Demo

# Quick demo

cognitive-guard demo



# Interactive setup

cognitive-guard init --interactive



# When you try to commit undocumented code:

git commit -m "Add feature"



🔍 Analyzing staged files...

🚫 COMMIT BLOCKED



Found 2 violations:

  📁 src/utils.py

     ❌ calculate_discount (complexity: 15) - Missing docstring



# Progress tracking

cognitive-guard stats



📊 Your Documentation Journey

   Current:  ████████░░ 80% documented

   Goal:     ██████████ 90% documented

   🎯 Just 5 more function(s) to go!

My Experience with GitHub Copilot CLI

Why I Tried Something Different

I've been using Antigravity (Google's VS Code fork with AI chat) for my daily coding. It's solid for writing functions and getting inline suggestions. But for this project, I wanted to try GitHub Copilot CLI to see what difference the terminal-based approach makes.

Spoiler: The differences were significant.

The Starting Point (Feb 5, 2026)

I started with a simple prompt:

gh copilot suggest "Build a Python CLI tool that analyzes code complexity 

and enforces documentation. Include git hooks, interactive TUI, and tests."

Over the next 6 hours and multiple follow-up prompts, I had:

• A working complexity analyzer using Python's AST module


• CLI with 7 commands (init, scan, check, tui, stats, hook, update-hook)


• Interactive TUI using Textual


• Git hook integration with safe installation


• 19 tests with pytest


• Complete documentation

That first day ended with a functional Python package. This would have taken me weeks solo.

Antigravity vs Copilot CLI: What I Noticed

Project-Level vs File-Level Context

Antigravity (chat in IDE):

• Works great when I'm focused on a single file


• Chat window helps with function-level questions


• Needs me to manually provide context about other files


• Better for "fix this function" or "add this feature to this class"

Copilot CLI:

• Sees the entire project structure from the start


• Understands relationships between modules


• Suggests architecture patterns, not just code


• Better for "set up CI/CD" or "structure this project"

Example: When I asked Copilot CLI about project structure, it suggested:

cognitive_guard/

├── core/          # Core logic

├── cli/           # CLI interface

├── tui/           # Interactive UI

├── hooks/         # Git integration

└── utils/         # Utilities

With Antigravity, I would've had to think through this structure myself, then ask it to help implement each part.

DevOps and Tooling

Antigravity:

• Struggles with questions about GitHub Actions


• Limited help with package configuration


• Not designed for Makefile or Docker questions

Copilot CLI:

• Generated complete CI/CD workflows


• Helped with pyproject.toml configuration


• Suggested pre-commit hooks setup


• Created Makefile with relevant targets

The CLI is in its natural environment for these tasks. It understands terminal workflows.

Multi-File Refactoring

The CI/CD Disaster:

My GitHub Actions were failing with 73 linting errors across 22 files. Deprecated type hints (Dict → dict), unused imports, formatting issues.

With Antigravity, I would've:

1. Opened each file individually


2. Asked for fixes per file


3. Manually ensured consistency


4. Probably missed some files

With Copilot CLI, I asked:

gh copilot suggest "Fix all Black and Ruff linting errors across the codebase"

It:

• Scanned all 22 files


• Applied consistent fixes


• Explained the changes


• Updated everything in one pass

73 errors → 0 in one session.

Documentation Generation

Antigravity:

• Good for docstrings when I'm in a file


• Helps with comments and inline docs


• Needs me to create documentation files first

Copilot CLI:

• Generated README.md structure


• Created CONTRIBUTING.md, SECURITY.md


• Suggested what docs I needed


• Provided examples of each doc type

When I asked "What documentation does this project need?", Copilot CLI listed: README, QUICKSTART, ARCHITECTURE, CONTRIBUTING, SECURITY, CHANGELOG. Then helped create each one.

What Actually Happened

The Complexity Algorithm

I asked: "I need cognitive complexity analysis counting control flow, nesting, and boolean logic"

Copilot CLI generated an AST-based analyzer. What caught my attention: it didn't just give me code—it explained the cognitive complexity concept and showed me Python AST patterns I hadn't used before.

def calculate_complexity(node: ast.AST) -> int:

    complexity = 0

    nesting_level = 0



    for child in ast.walk(node):

        if isinstance(child, (ast.If, ast.While, ast.For)):

            complexity += 1 + nesting_level  # Nested = harder to understand

        elif isinstance(child, ast.BoolOp):

            complexity += len(child.values) - 1



    return complexity

The comment about nested control flow? That was from Copilot CLI explaining why the formula works that way.

The TUI Challenge

I needed an interactive terminal UI. I'd heard of Textual but never used it.

Me: "I want an interactive TUI where users can browse violations and edit docstrings"

Copilot CLI:

1. Suggested Textual over alternatives (with reasoning)


2. Generated the complete TUI structure


3. Added keyboard shortcuts (q, ↑↓ navigation, Enter to edit)


4. Included error handling for file operations

I learned a new framework while building the feature.

Note: Antigravity would've been great once I knew I wanted Textual. But Copilot CLI helped me choose Textual in the first place.

The Git Hook Problem

Safe git hook installation is tricky. Copilot CLI's solution included:

• Backing up existing hooks


• Creating a hook that fails gracefully


• Providing clear instructions when blocking commits


• Including a bypass option (--no-verify)

These were edge cases I would have discovered through bug reports, not upfront design.

When Antigravity Would've Been Better

To be fair, there were moments where Antigravity's IDE integration would've been smoother:

1. Function-level debugging: When a specific function had bugs, stepping through in the IDE with AI help is more natural




2. Code review: Reading generated code with inline suggestions is easier in an editor




3. Incremental changes: Making small tweaks to existing functions works better with IDE context

But for building a new project from scratch, especially one that involves DevOps, testing, and documentation—Copilot CLI was the better choice.

The Next 8 Days: Iteration and Polish

Days 2-3 (Feb 6-8): GitHub Integration

• Added CI/CD workflows


• Created issue templates


• Set up pre-commit hooks

Days 4-5 (Feb 12): The CI/CD Maze

Copilot CLI fixed all 73 linting errors in one pass. It:

• Updated type annotations to Python 3.9+ style


• Removed unused imports consistently


• Fixed import ordering


• Explained each change type

More importantly, I learned why modern Python prefers dict over typing.Dict.

Days 6-7 (Feb 12): PyPI Preparation

Copilot CLI helped with:

• Package metadata in pyproject.toml


• Build configuration


• Distribution setup


• Installation testing

All terminal-based tasks where Antigravity wouldn't have much to offer.

Days 8-9 (Feb 13-14): Usability Push

I had a working tool but wanted it friendlier. I asked for:

• A demo command for quick onboarding


• Interactive setup with questions


• Better error messages with fix suggestions


• Visual progress bars in stats

Copilot CLI generated encouraging messages that weren't cheesy, progress bars using ASCII art, and error messages that guide instead of blame.

The Learning Curve

Some things took adjustment:

Over-Engineering: Initial suggestions were sometimes too comprehensive. I learned to ask for "simple" or "minimal" first, then iterate.

Context Matters: For large changes, breaking requests into smaller prompts worked better. "Refactor this specific module" beats "improve my codebase."

Test Verification: Generated tests were solid starting points but needed domain-specific adjustments. The structure and patterns were valuable though.

Real Productivity Gains(AI Generated)

Time comparison (estimated vs actual):

Antigravity would've saved me time, but Copilot CLI was faster for this type of project.

What Actually Made Copilot CLI Valuable Here

1. It's a Teacher

Every suggestion came with context. Not just "use this pattern" but "use this pattern because of X, and watch out for Y."

2. Architecture Guidance

When I asked about project structure, it suggested separation of concerns, proper package organization, and configuration patterns. This shaped the whole project.

3. DevOps Knowledge

The CI/CD workflows included matrix testing, caching, artifact uploading, and coverage reports. I learned GitHub Actions patterns I didn't know existed.

4. Documentation Generation

The generated README followed best practices with installation, usage, examples, and contribution guidelines. I learned what good documentation looks like.

My New Workflow

After this experience, here's how I think about using both tools:

Use Antigravity or Copilot Chat when:

• Writing and refining individual functions


• Debugging specific code sections


• Doing code review


• Making small, focused changes


• Working within a single file

Use Copilot CLI when:

• Starting a new project


• Setting up tooling (CI/CD, pre-commit, etc.)


• Generating documentation


• Multi-file refactoring


• Learning about project structure


• Anything DevOps-related

They complement each other. Copilot CLI gets the project structured and running. Antigravity helps refine the details.

Tips for Using Copilot CLI

Based on 17+ sessions:

1. 
   Be specific: "Refactor this function to use async/await" beats "make it better"


2. 
   Iterate: Start simple, then ask "how can we improve this?"


3. 
   Learn, don't copy: Read the generated code, understand the patterns


4. 
   Provide context: Mention what you're building and what problem you're solving


5. 
   Use it beyond code: Documentation, debugging, DevOps, learning new tools

The Final Numbers

After 9 days:

• 
  Code: 1,200+ lines across 24 Python files


• 
  Tests: 19 tests, 40% coverage, all passing


• 
  Quality: Black and Ruff linters passing


• 
  Documentation: 15+ markdown files, 15,000+ words


• 
  Status: Published on PyPI, production-ready

Would I Use It Again?

Yes. For new projects, especially those involving DevOps and documentation, Copilot CLI is now my starting point.

The 5x speed improvement over solo work is real, but the continuous learning is more valuable. Each session taught me something new about Python, tooling, or best practices.

Antigravity remains my go-to for daily coding tasks. But for "build something new from scratch"? Copilot CLI won me over.

Try It

pip install cognitive-guard

cognitive-guard demo

cognitive-guard init --interactive

📦 PyPI: cognitive-guard


🔗 GitHub: cognitive-guard

The question isn't which AI tool is better. The question is which tool fits the task. For building this project, Copilot CLI was the right choice.

Built in 9 days • 17+ Copilot CLI sessions • 1,200+ lines of code