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

Mohd Saalim — Sat, 14 Feb 2026 07:13:23 +0000

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:

Opened each file individually
Asked for fixes per file
Manually ensured consistency
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:

Suggested Textual over alternatives (with reasoning)
Generated the complete TUI structure
Added keyboard shortcuts (q, ↑↓ navigation, Enter to edit)
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:

Function-level debugging: When a specific function had bugs, stepping through in the IDE with AI help is more natural
Code review: Reading generated code with inline suggestions is easier in an editor
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):

Task	Without AI	With Antigravity	With Copilot CLI
Project setup	4 hours	2 hours	30 min
Core algorithm	8 hours	4 hours	2 hours
TUI implementation	12 hours	8 hours	3 hours
Tests	10 hours	6 hours	2 hours
Documentation	8 hours	6 hours	1 hour
CI/CD	6 hours	5 hours	1 hour
Total	~64 hours	~31 hours	~13 hours

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:

Be specific: "Refactor this function to use async/await" beats "make it better"
Iterate: Start simple, then ask "how can we improve this?"
Learn, don't copy: Read the generated code, understand the patterns
Provide context: Mention what you're building and what problem you're solving
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

Forem: Mohd Saalim

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

What I Built

Core Features

Demo

My Experience with GitHub Copilot CLI

Why I Tried Something Different

The Starting Point (Feb 5, 2026)

Antigravity vs Copilot CLI: What I Noticed

Project-Level vs File-Level Context

DevOps and Tooling

Multi-File Refactoring

Documentation Generation

What Actually Happened

The Complexity Algorithm

The TUI Challenge

The Git Hook Problem

When Antigravity Would've Been Better

The Next 8 Days: Iteration and Polish

The Learning Curve

Real Productivity Gains(AI Generated)

What Actually Made Copilot CLI Valuable Here

My New Workflow

Tips for Using Copilot CLI

The Final Numbers

Would I Use It Again?

Try It