NUdge 🚀

NUdge is a terminal-first reminder and productivity tool built in Go.

It focuses on clean daily workflow:

• Add reminders
• List actionable tasks
• Mark reminders as done
• Delete reminders
• Store everything safely in a local OS-specific config directory

No UI. No clutter. Just focused nudges.

---

✨ What We Have Built So Far

✅ Core Features

1️⃣ Add a Reminder

nudge add --title "Pay Rent" --due "2026-02-12 22:00"

• Generates a unique ID
• Stores reminder in JSON
• Automatically sorts by due date

---

2️⃣ List Reminders

Default (only actionable items):

nudge list

Show everything including finished:

nudge list --all

Reminders are tagged as:

• UPCOMING
• OVERDUE
• FINISHED

---

3️⃣ Mark as Done

nudge done <id>

This updates status to done but does NOT delete the reminder.

---

4️⃣ Delete Reminder

nudge delete <id>

This permanently removes the reminder from the database.

---

📂 Database Storage

NUdge stores data in your OS config directory:

• macOS:

  ~/Library/Application Support/nudge/db.json
  

• Linux:

  ~/.config/nudge/db.json
  

• Windows:

  %AppData%\nudge\db.json
  

On first run, NUdge asks permission before creating the database.

The database:

• Is automatically sorted
• Uses secure file permissions
• Is human-readable JSON

---

🛠 How To Run Locally

1️⃣ Clone the repository

git clone <your-repo-url>
cd nudge_tool

2️⃣ Build the binary

go build -o nudge ./cmd/nudge

3️⃣ Run commands

./nudge list
./nudge add --title "Task" --due "2026-02-12 22:00"
./nudge done <id>
./nudge delete <id>

---

🧠 How We Built This (Architecture Overview)

We intentionally built NUdge step-by-step with clean separation of concerns.

📁 Project Structure

cmd/nudge        -> CLI entrypoint + Cobra commands
internal/model   -> Reminder struct and status types
internal/store   -> JSON storage logic

---

🧱 Layered Design

CLI Layer (Cobra)

Handles:

• Parsing user input
• Validating arguments
• Calling the store layer

Example:

./nudge done 123

The CLI extracts 123 and passes it to the store.

---

Store Layer

Responsible for:

• Reading/writing JSON
• Sorting reminders
• Updating status
• Deleting entries

It does NOT care about CLI details.

---

Model Layer

Defines:

• Reminder struct
• Status types (pending, done)

Keeps the domain clean and simple.

---

🔐 Design Decisions

• Used os.UserConfigDir() for proper cross-platform DB location
• Used secure permissions (0700 dir, 0600 file)
• Sorted reminders before saving for stable JSON
• Used PersistentPreRunE in Cobra to ensure DB initialization

---

🚀 Next Steps (Planned)

• nudge start background nudge engine (ticker-based scheduler)
• Sound notifications
• Interactive mode
• Snooze functionality
• Optional auto-clean of finished reminders

---

Built with Go and intentional product thinking.

NUdge nudges you to act.