setup

name	setup
description	Initialise claudia for a new user — walks through prerequisites, then uses the Obsidian CLI to set up the vault

Welcome to claudia. This will configure the system for your machine.

---

Phase 1 — Prerequisites (requires user action)

Step 1 — Detect the project path

pwd

Store this as PROJECT_PATH — you'll need it throughout.

Step 2 — Check Obsidian is installed

which obsidian 2>/dev/null || echo "not found"

If not found, tell the user:

Before we continue, you need Obsidian installed with the CLI enabled.

1. Download and install Obsidian from https://obsidian.md (v1.12.4 or later)
2. Open Obsidian and create a vault (or open an existing one)
3. Go to Settings → General → Command line interface → Register CLI
4. Come back here and tell me when you're done.

Wait for the user to confirm before continuing.

Step 3 — Verify CLI is working

obsidian version

If this fails, the CLI isn't registered. Ask the user to check the Obsidian setting and try again. Do NOT proceed until this command succeeds.

---

Phase 2 — Questionnaire

Ask the following questions one at a time, waiting for each answer.

Q1: What's your name?

Used to personalise CLAUDE.md.

---

Q2: Where is your Obsidian vault?

Auto-detect first:

obsidian vaults

Show the results and ask which vault to use, or let them enter a custom path. Store the vault name and path.

If they need to target a specific vault in later CLI commands, use vault="VAULT_NAME" parameter.

---

Q3: Do you want macOS notification reminders? (recommended)

"Would you like macOS notifications to remind you to check in at end of day and do your weekly review? This is optional but recommended."

If yes, continue with Q3a and Q3b. If no, skip to Q4 and skip Phase 5.

---

Q3a: When do you want your daily check-in reminder?

"What time should I remind you to do your end-of-day check-in? This runs Monday–Friday. (e.g. 5pm, 17:30)"

Convert to hour and minute:

• "5pm" → hour=17, minute=0
• "5:30pm" → hour=17, minute=30

---

Q3b: When do you want your weekly review reminder?

Ask for the day:

"Which day for the weekly review reminder? (e.g. Friday, Sunday)"

Then the time:

"What time? (e.g. 4:30pm, 17:00)"

Convert to day number and hour/minute:

• Day names → numbers: Monday=1, Tuesday=2, Wednesday=3, Thursday=4, Friday=5, Saturday=6, Sunday=0
• "4:30pm" → hour=16, minute=30; "9am" → hour=9, minute=0

---

Q4: What kind of work do you do?

"What's your role? (e.g. software engineer, product manager, designer — a sentence is fine)"

---

Phase 3 — Update project files

Use the Read and Edit tools for these.

3a. Update CLAUDE.md

Read CLAUDE.md and update:

• The Vault path with the vault path from Q2
• The Who section with the user's name (Q1) and role (Q4)

3b. Update session-start.sh

Read .claude/hooks/session-start.sh and update the VAULT= line with the correct vault path.

3c. Make scripts executable

chmod +x .claude/hooks/session-start.sh scripts/checkin-reminder.sh scripts/weekly-reminder.sh

---

Phase 4 — Create vault structure via Obsidian CLI

Use the Obsidian CLI for all vault operations from this point on. If the user has multiple vaults, add vault="VAULT_NAME" to each command.

Folders are created automatically when files are created via obsidian create path=. Most folders will be created when seeding files below. For the empty Archive/ folder, create it via the filesystem:

VAULT_PATH="[vault path from Q2]"
mkdir -p "$VAULT_PATH/Archive"

4a. Seed Atlas files

Only create each file if it does not already exist. Check with:

obsidian read path="Atlas/Work.md" 2>&1 | head -1

If a file doesn't exist, create it with obsidian create. Use the content templates below.

Atlas/Work.md:

obsidian create path="Atlas/Work.md" content="Map of all work achievement notes. Primary source for performance review summaries.\n\n## $(date +%Y)\n\n### Q1 (Jan–Mar)\n\n### Q2 (Apr–Jun)\n\n### Q3 (Jul–Sep)\n\n### Q4 (Oct–Dec)\n\n---\n\n## Tags\nwork/shipped — work/unblocked — work/led — work/learned — work/improved"

Atlas/Ideas.md:

obsidian create path="Atlas/Ideas.md" content="Map of all idea notes. Reviewed weekly — stale unrefined ideas get a decision.\n\n## Unrefined\n\n## Active\n\n## Archived"

Atlas/Tasks.md:

obsidian create path="Atlas/Tasks.md" content="One-off tasks with deadlines. Reviewed daily — overdue items are flagged immediately.\nUnchecked = open, checked = done."

Atlas/Knowledge.md:

obsidian create path="Atlas/Knowledge.md" content="## Engineering\n\n## Process & Craft\n\n## Personal\n\n## Reference"

4c. Create the daily note template

obsidian create path="Daily Notes/Templates/Daily Note.md" content="---\ndate: {{date:YYYY-MM-DD}}\ntype: daily\n---\n\n# {{date:dddd, MMMM D, YYYY}}\n\n## Focus\n> What's the one thing that makes today a success?\n\n## Tasks\n- [ ]\n\n## Notes & Ideas\n> Anything worth capturing? Use /idea or /task if it needs tracking.\n\n## Work\n> Anything shipped or unblocked today? Use /log to record it.\n\n## End of Day\n- [ ] Anything worth logging with /log?\n- [ ] Any new ideas captured?\n- [ ] Ideas captured or refined?"

4d. Configure the daily note template setting

This can't be done via the CLI. Write directly to the vault's Obsidian config:

VAULT_PATH="[vault path from Q2]"

Read the current daily-notes.json:

cat "$VAULT_PATH/.obsidian/daily-notes.json"

Update it to include the template field. The file is JSON — merge in "template": "Daily Notes/Templates/Daily Note" while preserving existing fields (like format). Write the result back using the Write tool.

4e. Install Dataview plugin

obsidian plugin:install id=dataview enable

---

Phase 5 — Set up launchd agents (optional)

Skip this phase entirely if the user said no to reminders in Q3.

5a. Check alerter is installed

which alerter 2>/dev/null || echo "not found"

If not found, tell the user:

You need alerter for macOS notifications.

brew install vjeantet/tap/alerter

After installing, the first time a notification fires you'll need to enable it in System Settings → Notifications → Terminal (or whichever app triggered it). Toggle "Allow Notifications" on.

Wait for the user to confirm before continuing.

5b. Install launchd agents

Check if claudia launchd agents already exist:

launchctl list 2>/dev/null | grep claudia

If any exist, show them and ask: "Existing claudia launchd agents found. Replace them?"

Install the agents using the install script. Convert the user's check-in time (Q3a) and weekly review schedule (Q3b) to the required arguments:

• Day names → numbers: Monday=1, Tuesday=2, Wednesday=3, Thursday=4, Friday=5, Saturday=6, Sunday=0
• Time → HOUR and MINUTE: e.g. "5pm" → hour=17, minute=0; "4:30pm" → hour=16, minute=30

The install script handles the overlap logic automatically (if weekly review lands on a weekday at the same time as the daily check-in, it excludes that day from the daily schedule).

bash [PROJECT_PATH]/scripts/install-launchd.sh [PROJECT_PATH] [CHECKIN_HOUR] [CHECKIN_MINUTE] [WEEKLY_DAY] [WEEKLY_HOUR] [WEEKLY_MINUTE]

Verify:

launchctl list | grep claudia

---

Phase 6 — Summary

## Setup complete

**Name**: [name]
**Vault**: [vault path]
**Reminders**: [if enabled: "weekdays at [time], weekly on [day] at [time]" / if disabled: "off"]

### Done automatically
- [x] CLAUDE.md configured
- [x] session-start.sh configured
- [x] Vault folders created (via Obsidian CLI)
- [x] Atlas and Template files seeded (via Obsidian CLI)
- [x] Daily note template configured
- [x] Dataview plugin installed and enabled
- [x] Daily check-in launchd agent installed (if reminders enabled)
- [x] Weekly reminder launchd agent installed (if reminders enabled)

### You're ready. Start with:
   cd [PROJECT_PATH] && claude
   /daily