Initialize a Project

Prerequisites

1. Install Hyprlayer
2. Have a thoughts repository (or let Hyprlayer create one)

If your team already has a shared thoughts repository, clone it first:

gh repo clone <org>/<thoughts-repo> ~/thoughts

Initialize

Go to your project and run:

cd ~/Projects/my-project
hyprlayer thoughts init

First-Time Setup

On your first init, Hyprlayer walks you through configuration:

1. Storage backend. git (default), obsidian, notion, or anytype. Skipped when you pass --backend
2. Thoughts repository location. Where Hyprlayer keeps your thoughts (default: ~/thoughts)
3. Repos directory name. Subdirectory for project-specific thoughts (default: repos)
4. Global directory name. Subdirectory for cross-project thoughts (default: global)
5. Username. Your identifier for personal thoughts (default: system username)

Steps 2 to 4 apply to the git and obsidian backends. See Storage Backends for what notion and anytype ask instead.

What Init Does

1. Creates the thoughts directory structure in your thoughts repository
2. Sets up symlinks from thoughts/ in your project to the thoughts repository
3. Installs git hooks for protection and auto-sync
4. Saves the repository mapping to your global config

After initialization, your project will have:

my-project/
  └── thoughts/
       ├── <username>/     → ~/thoughts/repos/my-project/<username>/
       ├── shared/         → ~/thoughts/repos/my-project/shared/
       └── global/         → ~/thoughts/global/

Using a Profile

Point a project at a second thoughts repository (work and personal, say) with a profile:

hyprlayer thoughts init --profile work

See Profiles for more on managing multiple thoughts repositories.

Non-Interactive Mode

--directory answers the directory-name prompt:

hyprlayer thoughts init --directory my-project

To run with no prompts at all, pass --yes with --directory. This needs an existing global config:

hyprlayer thoughts init --yes --directory my-project

Force Reinitialize

hyprlayer thoughts init --force

Reconfigures thoughts for a project you already initialized. To repair agent files, use hyprlayer ai reinstall.

Git Hooks

Initialization installs a pre-commit hook for every backend and, for the git backend only, a post-commit hook.

Pre-commit Hook

Keeps the thoughts/ directory out of your code repository. Stage a thoughts file and the hook unstages it, then blocks the commit.

Post-commit Hook

Syncs thoughts to the thoughts repository after each commit in the main checkout. It runs in the background, so it never slows you down. Commits inside a git worktree skip it; run hyprlayer thoughts sync there yourself.

Both hooks carry a version, and init updates them on a re-run. Hyprlayer backs up any existing non-Hyprlayer hook to <hook>.old.

Remove Thoughts

To remove thoughts setup from a repository:

hyprlayer thoughts uninit

This removes the thoughts/ symlink structure and the repository mapping from your config. Your thoughts content stays where it is, in the thoughts repository.

Next Steps

Start using the development workflow.