Introduction

Habits is a lightweight workflow creator, runtime, and packer for building agents, automations, full-stack apps, SaaS, and micro-apps. It combines a visual builder (Base) with a decentralized execution engine (Cortex) — all under Apache 2.0.

What Can You Build?

Category	Examples
AI/ML	AI assistants, image analyzers, voice generators, quiz creators
Business	Invoice generators, competitor analysis, real estate tools
Communication	Email classifiers, newsletter generators, social media managers
Development	Code reviewers, bug reporters, documentation generators
Productivity	Meeting summarizers, research assistants, resume analyzers

Core Components

Component	Role	Description
Stack	Workflow Set	Multiple habits running together
Habit	Workflow	A YAML file defining connected nodes
Bit	Node	A single step: Habits bit, ActivePieces piece, n8n node, or script
Base	Builder	Visual editor for creating habits
Cortex	Executor	Runtime that executes workflows

Naming Origin

The naming draws from neuroscience, the brain's cortex orchestrates behavior while basal ganglia forms habits.

How It Works

Visual Overview

	Base (Visual Builder)	Cortex (Execution Engine)
Purpose	Drag-and-drop workflow creation	Executes workflows (habits)
Features	- Visual editor - Export to YAML - Frontend builder - Template library	- CLI execution - REST API server - Multi-framework support - Dynamic module loading

• Base: Design and prototype workflows visually, then export to YAML for version control or CI/CD.
• Cortex: Run workflows via CLI or REST API, supporting multiple frameworks and dynamic module loading.

Ways to create habits:

1. Visual Builder: Use Base UI to drag-and-drop nodes
2. Code-first: Write YAML directly for version control and CI/CD
3. AI: As the AI to directly create you the habit.

Ways to run:

• REST API: Start a server and trigger via HTTP/Frontend
• CLI: habits execute --config ./stack.yaml

Key Features

• Multi-Framework Support — Combine ActivePieces pieces, n8n nodes, custom bits, and scripts in one workflow
• Apache 2.0 License — Embed in commercial products, distribute without restrictions
• Flexible Execution — Run via CLI, REST API, or with an auto-generated frontend
• Dynamic Module Loading — Install modules from npm, GitHub, or local sources on-the-fly
• Lightweight — Minimal footprint for serverless, edge, and embedded deployments
• Security — Built-in DLP, PII protection, supply chain integrity, and sandboxing

Documentation Reading Order Checklist

• [ ] Read Introduction - understand what Habits is
• [ ] Read Motivation - understand why Habits exists
• [ ] Read When to Use - see if Habits fits your use case
• [ ] Read Concepts - learn core concepts (stacks, habits, nodes)
• [ ] Read First Habit - build your first habit
• [ ] Browse Examples Index - see what's possible

If you want to understand Habits in-depth

• [ ] Read Variables - learn how to pass data between nodes
• [ ] Read Habit Schema - full schema reference
• [ ] Read Creating Habits - advanced creation techniques
• [ ] Read Running Habits - different modes and options
• [ ] Read Logging - debugging and monitoring

If you want to see working examples

• [ ] Check Mixed Framework Example - combines multiple frameworks
• [ ] Check AI Cookbook Example - AI-powered recipe generation
• [ ] Check Email Classification Example - email processing
• [ ] Check Minimal Blog Example - simple content management
• [ ] Browse Examples Directory - all example stacks with code

If you want to import from existing tools

• [ ] Read Importing & Converting - import from n8n, Activepieces, etc.

If you want to distribute your habits

• [ ] Read Pack & Distribute - export and distribution options
• [ ] Follow export checklists in this document (Docker, Binary, Desktop, Mobile)

If you want to contribute or understand internals

• [ ] Browse Development documentation in docs/development/ folder
• [ ] Browse Roadmap documentation in docs/roadmap/ folder
• [ ] Check Stability - API stability guarantees

If you have specific questions

• [ ] Check Security Documentation - security best practices
• [ ] Browse Extra Reading in docs/extra-reading/ folder
• [ ] Browse Misc documentation in docs/misc/ folder

Next Steps

• Core Concepts — Deep dive into terminology
• Build Your First Habit — Hands-on tutorial
• When to Use Habits — Check if it fits your use case
• Why Habits? — Detailed rationale and comparison