Skip to content

First run

This guide walks through lh init from a clean machine. If you are migrating an existing Claude Code setup, see migrating instead.

What lh init does

  1. Refuses to run if you have existing Claude Code state (~/.claude/, ~/.claude-*/, or an existing ~/.config/lazy-harness/config.toml).
  2. Asks for a profile name (default: personal).
  3. Asks for the agent (default: claude-code; codex and copilot are the other registered answers — see supported agents).
  4. Asks for the billing model (per_token or flat_rate, default: per_token — ADR-050 rejects a per-agent default, so this stays per_token for every agent unless you answer flat_rate).
  5. Asks for a knowledge directory path (default: ~/Documents/lazy-harness-knowledge).
  6. Detects QMD if present and offers to configure a knowledge collection.
  7. Writes ~/.config/lazy-harness/config.toml, with config_dir following the agent's own convention (~/.claude-<name>, ~/.codex-<name>, ~/.copilot-<name>).
  8. Creates the profile directory at ~/.config/lazy-harness/profiles/<name>/ with a minimal CLAUDE.md and settings.json.
  9. Creates the knowledge directory with sessions/ and learnings/ subdirs.

Running it

lh init

Sample session:

lazy-harness — initial setup

Profile name [personal]:
Agent [claude-code]:
Billing model (per_token, flat_rate) [per_token]:
Knowledge directory [~/Documents/lazy-harness-knowledge]:
QMD detected. Configure knowledge collection? [Y/n]: Y

✓ Config created at ~/.config/lazy-harness/config.toml
✓ Profile 'personal' created
✓ Knowledge directory ready at ~/Documents/lazy-harness-knowledge
✓ QMD collection configured

Run `lh doctor` to verify your setup.

Verifying

lh doctor     # system prerequisites
lh selftest   # framework integrity
lh profile list # list configured profiles

All three should exit 0 with green output.

Starting an agent session

CLAUDE_CONFIG_DIR=~/.claude-personal claude

This launches Claude Code with your personal profile. The CLAUDE_CONFIG_DIR env var tells Claude Code to read settings from ~/.claude-personal/ instead of the global ~/.claude/. You can alias this:

alias claude-personal='CLAUDE_CONFIG_DIR=~/.claude-personal claude'

Customizing the profile

Your profile lives at ~/.config/lazy-harness/profiles/personal/. Edit:

  • CLAUDE.md — the project-level instructions Claude Code will load
  • settings.json — Claude Code settings (hooks, permissions, etc.)
  • skills/ — custom skills
  • commands/ — custom slash commands

After editing, run lh deploy to refresh the symlinks into ~/.claude-personal/.

Versioning your profile

lh init does not version your profile for you. Connect it to your dotfiles manager of choice:

cd ~/.config/lazy-harness
chezmoi add profiles/

(or yadm, or a git submodule, or a plain git repo inside ~/.config/lazy-harness/profiles/.)

Next steps