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.
Recent highlights include AI-assisted journal generation, a CLI breathing mode called The Void, configurable gamification milestones, and improved task/sub-task completion behavior.
The easiest way to install and keep Mindloop updated.
brew tap snehmatic/mindloop
brew install mindloopNote: If you are not seeing the latest version, run
brew updateto refresh the tap.
Run as a background service: You can use Homebrew Services to run the Mindloop server in the background:
brew services start mindloopIf you have Go installed, you can install the latest version directly:
go install github.com/snehmatic/mindloop@latestDownload the latest pre-compiled binary for your OS from the Releases Page.
-
Clone the repository:
git clone https://github.com/snehmatic/mindloop.git cd mindloop -
Build:
make build
This generates the
mindloopbinary. The same binary provides both CLI commands and the local server viamindloop server. -
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
Live Reloading (Development): For active development, you can run the server with live reloading. This requires Air. First, install
airglobally:go install github.com/air-verse/air@latest
Then, start the development server:
make dev
The server will automatically rebuild and restart when you save changes to Go, HTML, CSS, or JS files.
The project includes a Makefile to simplify common tasks:
make build: Build the binary.make run-server: Run the local server in the foreground.make dev: Run the server with live-reloading (requiresair).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 lint: Rungolangci-lint.make fmt: Format Go files.make clean: Remove build artifacts.
- 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.
- Roadmap: Current development status, experimental areas, and planned directions.
- Releasing Guide: Instructions on how to create and publish new releases.
- Contributing: Guidance for contributors, maintainers, and AI coding agents.
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.
- Copy the example env file:
cp example.env .env
- Edit
.envwith your database credentials (DB_HOST, DB_PORT, etc.).
Mindloop is a productivity suite for getting started with intentions, habits, journals, and focus sessions. As a developer with attention problems, Mindloop originally started as a very personal CLI tool to manage my daily work routine and reduce some of the mental clutter that comes with context switching all day. The initial workflow was intentionally simple:
- Intents to define one single thing I wanted to work on or pay attention to
- Focus sessions to break that intention down into smaller chunks of high quality, intentional deep work
That alone worked surprisingly well.
Instead of planning an ideal day or maintaining some giant productivity system that I'd eventually ignore, this gave me something much smaller and more immediate: decide what matters right now, work on it, and close the loop.
Along the way, additional features like habits and journal were added almost as an afterthought. But weirdly enough, those ended up becoming part of the workflow too.
I’d usually start my day by ticking off a few habits I cared about (daily and weekly), then work through an active intention using focus sessions, and by the end of the day, write a tiny journal entry just to mentally close work for the day, shut the laptop, and go touch some grass (or did I?).
Over time, Mindloop evolved beyond just a CLI experiment. What started as a tool to help me focus on work gradually became a slightly more opinionated system for managing attention, reflection, and intentionality. Tasks, subtasks, notes, summaries, side quests, AI overviews, and other features naturally grew around that core. But the philosophy has stayed mostly the same. Mindloop is not meant to be a system for planning the perfect day, optimizing every hour, or building the most aesthetic productivity dashboard known to mankind (I despise frontend). It is intentionally a bit more present and reflective.
The core idea is simple:
- pick something meaningful to focus on
- work on it in deliberate chunks
- keep track of a few recurring systems that matter
- reflect a little
- and finally, move on
This is also why some seemingly obvious productivity features have intentionally been avoided or delayed. For example, routines/rituals or heavily pre-planned workflows sound useful on paper (and honestly, I still think they are), but they introduce a strange overlap with the intention-centric design of Mindloop. If everything is pre-planned, templated, stacked, drag-and-dropped, and optimized into perfect routines, then the question becomes: what purpose do intentions serve anymore? That starts pulling Mindloop in a different direction.
At least for now, Mindloop is less about designing a perfect life system, and more about helping reduce mental chaos in the present. It exists to answer simpler questions:
- What am I doing right now?
- Am I actually paying attention to it?
- Did I close the day with some amount of intention? That’s really where Mindloop started, and honestly, still the soul of the project.