-
-
This is the NPM JS page for crisis-to-calm
-
Result of running ```calm --help```. All the flags a user can use.
-
Testing that the ```npm i -g crisis-to-calm``` command works on a virtual machine I set up with only Node.js installed. (It works!)
Inspiration:
As someone who gets easily overwhelmed by a heavy workload, I use breathing exercises to stay grounded. Developers are constantly pushed to their limits, yet most wellness tools require leaving the workstation. I chose to build this as a terminal script because I wanted to meet developers where they are most comfortable. It was also vital that the tool be lightweight and fast to set up and use, as eating into a user's time only adds more stress. This is how crisis-to-calm was born.
What it does:
crisis-to-calm is a CLI tool that guides users through Box Breathing, a grounding technique used by high-performance professionals to manage stress. It guides users through four rounds of "box breathing", a grounding technique where you inhale, hold, exhale, and hold again for four seconds each. While the default theme is a clean white box, users can choose from several others to make it feel personal, including forest, ocean, and rainbow themes, among others. For those who enjoy surprises, or are simply indecisive, the --random flag selects a theme for the user. Users can also customize the breath duration for a specific session by running calm --[number] (ex. calm --6). For a more immersive experience, users can enter "Deep Mode", removing the distracting blinking cursor and playing a sound when the session ends, allowing them to close their eyes. To keep users engaged, the script tracks daily streaks and features nine levels of progression. Starting as a "Baby Breather," users work their way up to "Zen Legend" by practicing mindfulness. Leveling up triggers a small terminal celebration and unlocks new emojis. After each session, the terminal displays a progress bar and updated stats. Users can also access a --help menu for instructions or use --reset to clear their progress. Finally, the script ends with a quick mental health check-in, providing resources if the user indicates they still feel overwhelmed.
The box breathing technique follows a simple 1:1:1:1 ratio. If a user sets a breath duration of s seconds (default is 4), one full cycle C is calculated as:$$C = s_{inhale} + s_{hold} + s_{exhale} + s_{hold} = 4s$$To reach the "Zen Legend" rank (10,000 breaths), a user completing standard 4-second cycles will have practiced mindfulness for over 11 hours!
How we built it
I built this using JavaScript, starting with the basic box drawing and breathing timers. I eventually integrated themes, flags, and streak tracking into the main startBreathing() function. I used Gemini 3 to assist in ideating and debugging throughout the process. After building it, I published it on NPM and tested it by running it on a virtual machine I set up with nothing but Node.js installed to make sure it worked.
Challenges we ran into
One of the most persistent challenges was implementing the rainbow theme. I had to refactor the code to use hex values instead of standard chalk colors to achieve the color-changing effect, although this proved to be useful when implementing the gradient for the other themes. During this phase, the box unexpectedly warped into a rectangle, which turned out to be a character-encoding issue that took some time to identify. I also faced a compatibility hurdle when creating the .exe file because pkg utilizes CommonJS. I solved this by using a bundler to format the code correctly. I also tackled a critical bug where streaks wouldn't increment due to relative path resolution; I solved this by implementing path.join(__dirname) to ensure the stats.json remained stable regardless of where the command was called.
Accomplishments that we're proud of
I was able to get this published to NPM, making it accessible to anyone with Node.js via npm i -g crisis-to-calm, which I consider a huge accomplishment, as I was able to get this tool out into the world already. Testing this with a virtual machine and seeing it run perfectly was amazing. I am particularly happy with the user-friendliness of the tool. As someone who often needs a little extra encouragement to practice mindfulness, I find the gamification and rewards system to be a great incentive.
What we learned
This project was my first experience with persistent data storage. Learning how to save and retrieve streak information was a rewarding challenge. Since I began with limited JavaScript knowledge, this project provided essential practice, especially with asynchronous functions. Learning when and where to use await took me a second, but I'm glad I learned it.
What's next for crisis-to-calm
I plan to add streak celebrations for milestones like 3, 7, or 30 days. I also want to track "total seconds breathed" as an additional statistic measuring how many seconds the user has practiced mindfulness with crisis-to-calm. Another update I want to make is ensuring that when users reply, the program doesn't respond unless they press one of the keys it asks for. Future updates will likely include a configuration system so users can save their favorite theme and breath duration as personal defaults. I will most likely add some more themes as well. After I'm happy with it, I want to make it compatible with MacOS and Linux as well.
Log in or sign up for Devpost to join the conversation.