devReflections

A local-first journaling and reflection tool for developers.

🏠 Local-first · 🔓 Open-weight models · 🔒 Privacy-minded

devReflections helps developers and open-source contributors reflect on their daily experiences. Choose a starter prompt or write freely, the let a locally running AI model ask a follow-up question to encourage deeper reflection.

Reflection can help developers make sense of what they learn, the challenges they encounter, and the decisions they make along the way. devReflections offers a lightweight way to explore these experiences without telling you what to think or do.

Your journal is personal. devReflections runs on your own machine, and entries are saved as local Markdown files that you can read, edit, and keep under your control.

Quick Start

Prerequisites

• Python 3.12+
• Ollama

Setup

Clone the repository and navigate to the project directory:

# Clone the project and enter its directory
git clone <repo-url>
cd devReflections

Download the required AI model and create a virtual environment:

# Download the required local AI model
olama pull gemma4:e4b

# Create and activate a virtual environment
python -m venv .venv

Activate the environment

# macOS / Linux
source .venv/bin/activate

# Windows (Powershell)
.venv\Scripts\Activate.ps1

Install and run devReflections:

# Install the project and its dependencies
python -m pip install -e .

# Start journaling.
python main.py

Make sure Ollama is running before starting devReflections.

Features

• Guided or free writing: Choose from five starter prompts or write about anything on your mind.
• AI-powered reflection: Receive one follow-up question generated by a local AI model based on your journal entry.
• Markdownlint journaling: Save your entry, the AI question, and your answer as a Markdown file.
• Organized entries: Entries are automatically organized by year and month for easy browsing.
• Local-first workflow: Run the AI model on your own machine and keep your journal entries in local files.

How It Works

1. Choose a prompt: Select a starter prompt or write freely.
2. Reflect: Write about your experiences, challenges, decisions, or learning.
3. Explore further: A local AI model generates a follow-up question based on your entry.
4. Respond: Write your answer to deepen your reflection.
5. Save: Your entry and responses are saved as a Markdown file in the entries/directory.

Entry Storage

Journal entries are saved as Markdown files in the entries/directory, organized by year and month:

entries/
└── YYYY/
    └── MM/
        └── YYYY-MM-DD_HH-MM-SS.md

You can open, edit, or back up these files with any text editor. Your entries remain on your local machine unless you choose to share or sync them elsewhere.

You can also explore a sample journal entry to see how entries are formatted.

Reflection Philosophy

devReflections is designed to make reflection feel natural, meaningful, and pressure-free. Its AI-generated questions aim to embody five core qualities:

• 💗 Caring: Warm, considerate, nonjudgmental, and empathetic.
• 🌿 Approachable: Simple, natural, conversational, and low-pressure.
• 💭 Reflective: Thought-provoking, curious, and meaningful without demanding deep answers.
• 🧭 Grounded: Relevant to the user's actual experiences, challenges, and motivations.
• 🕊️ Gentle: Patient, nonintrusive, and never demanding.

Troubleshooting

Ollama connection error

If devReflections cannot connect to Ollama, make sure Ollama is installed and its local server is running.

• Windows / macOS: Open the Ollama application.
• Linux: If Ollama is installed as a systemd service, run sudo systemctl start ollama.
• Manual startup: Run ollama serve in a separate terminal.

See the official Ollama documentation for Linux setup or the troubleshooting guide for further help.

Project Status

devReflections is an early-stage project built to explore a simple, local-first reflection workflow for developers.

Current features include guided prompts, AI-generated follow-up questions, Markdown entry storage, and automated tests.

Possible future improvements include AI-generated monthly summaires and further refinement of the reflection experience based on real-world use.

License

Apache 2.0 -See License for details.

Disclaimer

devReflections is a personal reflection tool intended for learning and journaling. AI-generated questions may be imperfect, inaccurate, or unsuitable for some situations. They are not professional advice or a substitute for human judgment.

The software is provided "as is", without warranties of any kind. See the License file for details.