Mindloop

Mindloop is a comprehensive productivity suite designed for local-first workflow management. It operates as a CLI tool, a local API, and a UI, utilizing a local SQLite database with BYODB (Bring Your Own Database) support.

Table of Contents

• Getting Started
  • Prerequisites
  • Installation
  • Build Commands
• Documentation
• Configuration
• Motivation

Getting Started

Prerequisites

• Go 1.26+
• Make

Installation

Option 1: Homebrew (macOS/Linux)

The easiest way to install and keep Mindloop updated.

brew tap snehmatic/mindloop
brew install mindloop

Note: If you are not seeing the latest version, run brew update to refresh the tap.

Run as a background service: You can use Homebrew Services to run the Mindloop server in the background:

brew services start mindloop

Option 2: Go Install

If you have Go installed, you can install the latest version directly:

go install github.com/snehmatic/mindloop@latest

Option 3: Download Binaries

Download the latest pre-compiled binary for your OS from the Releases Page.

Option 4: Build from Source

1. Clone the repository:

   git clone https://github.com/snehmatic/mindloop.git
   cd mindloop

2. Build:

   make build

   This generates mindloop (CLI) and mindloop-server (Server) binaries.

3. Run the Server (Quick Start): For local development with the UI:

   make run-server

   This will start the server on port 8765 (default).

   To use a custom port or mode:

   make run-server PORT=9000 MODE=byodb

   Access the UI at http://localhost:8765

Build Commands

The project includes a Makefile to simplify common tasks:

• make build: Build both the CLI and Server binaries.
• make build-cli: Build only the CLI binary.
• make start-server: Build and run the server in the background (daemon).
• make kill-server: Stop the background server.
• make test: Run unit tests.
• make clean: Remove build artifacts.

Documentation

• Features: Explore the different features Mindloop offers like Intents, Focus Sessions, Habits, and more.
• Architecture: Learn about Mindloop's clean architecture, interfaces, and data layer.
• CLI Usage Guide: Detailed instructions on how to use Mindloop directly from the command line.
• Web UI Documentation: A visual tour of the web interface and responsive design.
• Releasing Guide: Instructions on how to create and publish new releases.

Configuration

By default, Mindloop runs in Local Mode using SQLite.

To use an external database (e.g., PostgreSQL), you can configure the application via environment variables.

1. Copy the example env file:

   cp example.env .env

2. Edit .env with your database credentials (DB_HOST, DB_PORT, etc.).

Motivation

Mindloop is a productivity suite, for getting started with intentions, habits, journals or focus sessions.

As a developer with attention problems, Mindloop started as a personal CLI tool to manage my daily work routine. Intents to set one single intention or work item to track and focus on, and focus sessions to break that intention down into chunks of high quality deep work frames.

This workflow worked well for starters. Alongside, the additional habits and journal features were added just because. But weirdly enough those caught up and I incorporated them into my workflow as well. I'd start my day ticking off habits that I had set (daily and weekly) and by the end of the day, write down a mini journal to just close the loop, end work and go touch some grass.