How I built a Laravel package that transforms @ghost and @todo comments into a beautiful developer diary and a real-time web dashboard.
Introduction
As developers, we often leave breadcrumbs in our code. Whether it’s a quick // @todo: Fix this or a cryptic // @ghost: Refactor this later, these notes often get lost in the sea of thousands of lines of code.
I wanted a way to keep track of these "ghostly" thoughts without manual effort. So, I decided to build GhostNotes—a Laravel package that scans your code, identifies your notes, finds out who wrote them via Git, and presents them in a beautiful Markdown file and a modern web dashboard.
The Problem: The "Lost Comment" Syndrome
In a fast-paced development cycle, we often forget the small improvements we intended to make. Existing project management tools like Jira or Trello are great for big tasks, but they feel too heavy for a 1-line code thought. I needed something:
- Lightweight: Living right inside the code.
- Automated: No manual copying.
- Visual: A clean UI to see everything at a glance.
The Solution: GhostNotes
GhostNotes is a Laravel package that acts as a bridge between your messy comments and a clean developer diary.
Key Technical Challenges I Solved:
Dynamic Scanning: I used Regex to scan the entire app/ directory for customizable tags like @ghost, @todo, and @fixme.
Git Blame Integration: To make it useful for teams, I integrated git blame commands via PHP's shell_exec. This allows the tool to identify exactly who wrote each note.
Modern Dashboard: I didn't want just a boring text file. I built a modern, dark-themed dashboard using Tailwind CSS that renders your notes in the browser.
Auto-Cleanup: One of my favorite features is the --clear flag. It generates your diary and then automatically wipes those comments from your source code to keep it clean.
How it Works
Installing it is as simple as any other Laravel package:
composer require iamsabbiralam/ghost-notes
Simply run a command:
php artisan ghost:write
And boom! You have a "GHOST_LOG.md" and a dashboard at "/ghost-notes"
The Architecture
I kept the architecture clean and "Laravel-way":
- Service Provider: To register routes, views, and commands.
- Custom Commands: For the CLI experience.
- Blade & Tailwind: For the zero-config dashboard.
What’s Next?
This is just the beginning. I'm planning to add:
- Slack/Discord Notifications: To alert teams when a new @fixme is added.
- Custom Export: Exporting the diary to PDF or HTML.
Check it out!
If you want to try it out or contribute, here is the GitHub repository: 👉 https://github.com/iamsabbiralam/ghost-notes
I’d love to hear your feedback. What do you do with your @todo comments? Let’s discuss in the comments!
Top comments (0)