Demo: Vibe coding a command line Markdown viewer with the Gemini CLI

Key Concepts

• Markdown Formatter/Viewer: A tool to display markdown files with features like pagination and syntax highlighting.
• Command Line Interface (CLI): A text-based interface for interacting with a computer program.
• Gemini CLI: A specific AI-powered command-line tool used in the demonstration.
• User Guide: A document explaining how to use a software tool.
• Technical Design: A document outlining the technical specifications and architecture of a software project.
• Task Plan: A detailed breakdown of steps required to build a software project.
• Python: A programming language chosen for the project.
• Rich Library: A Python library for rich text and beautiful formatting in the terminal.
• Argparse: A Python module for parsing command-line arguments.
• File Structure: The organization of directories and files within a project.
• Logic Flow: The sequence of operations within a program.
• Workflow: The sequence of tasks and processes involved in a project.
• Implementation Notes: Details about how specific tasks were coded.
• Colloquial Communication: Using informal language and humor in AI interactions.
• Puns: Wordplay used for humorous effect.
• Executable: A program that can be run directly.
• Virtual Environment: An isolated Python environment to manage project dependencies.
• Error Handling: The process of anticipating and managing errors in software.
• Vibe Coding: A term used to describe a rapid, intuitive, and AI-assisted coding process.

Project: MD Viewer CLI

This summary details the process of building a command-line markdown viewer using an AI assistant, specifically the Gemini CLI. The goal is to create a tool that can paginate long markdown files and provide syntax highlighting, without editing capabilities.

1. Initial Prompt and User Guide Generation

The process begins with a high-level prompt to the AI: "I want to build a command line markdown viewer. It should paginate long markdown files, have some syntax highlighting, and does not include any editing features."

To establish a baseline and understand the AI's initial interpretation, the user requests a "user guide" to be written and saved as user_guide.md. Crucially, the user instructs the AI to "wait for my review" and "don't write any code yet." This habit is adopted to ensure control over the AI's output and prevent premature code generation.

The AI generates a user guide for a tool named "MD View," describing its simplicity and elegance. Key features outlined include:

• Rendering markdown.
• Using the spacebar to go to the next page.
• Using page up to go to the previous page.
• Using 'Q' to quit.

The user notes that the name "MD View" could be modified, perhaps to "MD Viewer."

2. Technical Design and Language Selection

Following the user guide, the next step is to create a technical design for "MD View." The user prompts the AI to suggest programming languages, asking for "three options and your final recommendation."

The AI proposes the following options:

• Go: Mentions the "glamour" library, but notes it's less flexible than Python's rich.
• Python: Highlights the availability of libraries like rich and argparse, deeming it a strong contender.
• Rust: Acknowledges its speed and performance with available crates, but suggests it might be "a bit much" for this project.

The AI's final recommendation is Python. The user accepts this, and requests a detailed technical design to be saved as arch.md. Again, the user emphasizes "be very detailed" and reiterates "wait for my review before coding."

The generated technical design for arch.md includes:

• Language: Python.
• Key Libraries: rich for formatting and argparse for command-line argument parsing.
• File Structure: A proposed directory and file layout (e.g., setup.py, viewer.py).
• Components: Identification of necessary components and their functions.
• Logic Flow: An outline of how the program will operate.
• Requirements: A list of functional and non-functional requirements.

The user acknowledges that in a real-world scenario, they would request even more detail.

3. Task Planning and Workflow Definition

With the technical design in place, the next step is to create a detailed task plan. The user requests this plan to be saved as plan.md. The plan should include a "general workflow flow" and instructions to "update plan.md when each task is completed with implementation notes."

This detailed tracking is important for maintaining continuity, especially if the AI session is interrupted or resumed later. The user also specifies that arch.md should be updated with any design changes.

The AI generates plan.md, which includes:

• General Workflow: Instructions to follow the plan and update it.
• Task Breakdown: A numbered list of tasks, starting with scaffolding.
• Implementation Notes Section: A dedicated area for recording details of each task's completion.

The user reviews plan.md and notes the inclusion of checkboxes for completed tasks and the implementation notes section.

4. Task Execution and Iterative Development

The user initiates the first task: "Let's do step one." The AI begins scaffolding the project. The user then demonstrates how to check the generated files using ls in the terminal, confirming the creation of setup.py and viewer.py as per the plan.

Colloquial Interaction and Humor: Before proceeding, the user asks the AI to adopt a more informal tone: "From here on out, address me as Kbro and use puns liberally." The AI responds enthusiastically, adopting the persona and even incorporating a pun related to the rich library: "It's time to make this code look rich." This highlights the AI's ability to adapt its communication style for a more engaging user experience.

The AI then moves to Task Two, which involves editing a file. The user notes that sometimes AI agents might encounter issues with file editing on the first attempt, but in this case, it was resolved quickly.

Progress Tracking and Continuity: The user then reviews the updated plan.md. They observe that Task One and Task Two now have checkboxes next to them, and implementation notes have been added. This visual progress tracking is highly valued by the user, as it preserves the project's history within the project structure itself, rather than relying solely on saving chat logs. This allows for easier transfer and continuation of work across different environments.

The user also points out that the Gemini.md file, which contains the instructions for the AI's persona, is also included, but distinguishes it from core project architecture files.

The process continues with Task Three, and the user expresses confidence that they have enough time to complete all five tasks. They also express a desire for potential errors to occur, so they can demonstrate error handling.

5. Finalization and Execution of the MD Viewer

The AI completes the tasks, and the user proceeds to the final stage, which involves turning "MD View" into an executable and testing it. The AI provides the command to execute the tool.

Instead of running the command directly within the AI's interface, the user opens a new terminal window and pastes the command: md_view test.md.

Successful Execution: To the user's satisfaction, the command works without errors. The output demonstrates the markdown rendering, including:

• Bold text.
• Italic text.
• Inline code.

The user confirms that the pagination features (using arrow keys and spacebar) are also functional.

6. Conclusion and Key Takeaways

The demonstration concludes with the successful creation and execution of the md_view command-line markdown viewer, built through an iterative process with AI assistance. The key takeaways are:

• AI as a Development Partner: The AI can effectively assist in various stages of software development, from initial concept and documentation to technical design and task execution.
• Structured Prompting: Clear and specific prompts, including instructions for review and code generation, are crucial for guiding the AI.
• Iterative Refinement: The process involves generating initial outputs (user guide, technical design, task plan) and then iteratively building upon them.
• Importance of Documentation: Maintaining detailed documentation (user guide, technical design, task plan with implementation notes) is vital for project clarity and continuity.
• AI Persona and Engagement: AI can be instructed to adopt specific personas and communication styles, making the development process more enjoyable and interactive.
• Preserving Project History: Integrating project progress and notes directly into the project structure (e.g., updating plan.md) is a robust method for maintaining continuity and context.
• "Vibe Coding" Potential: The demonstration showcases a rapid, AI-assisted development approach that can be termed "vibe coding," where the AI handles much of the boilerplate and initial implementation.
• Error Handling Preparedness: The user intentionally anticipated potential errors to demonstrate how to address them, highlighting the importance of robust error handling in AI-assisted development.