installation.md

Installation Guide

Step-by-step install for macOS and Linux. Total time: ~5 minutes.

Prerequisites

You need:

• Claude Code v2.0 or later — check with claude --version. If older, upgrade at code.claude.com.
• bash — already installed on every macOS/Linux system.
• jq — JSON parser. On macOS: brew install jq. On Debian/Ubuntu: sudo apt install jq. On Fedora/RHEL: sudo dnf install jq.
• git — for cloning the repo. Already installed on every dev machine.

Verify prerequisites:

claude --version && bash --version | head -1 && jq --version && git --version

All four should print version numbers.

Step 1 — Clone the repo

git clone https://github.com/codebloodedai/claude-codestart.git ~/src/claude-codestart
cd ~/src/claude-codestart

You can clone anywhere you like — ~/src/ is just a convention.

Step 2 — Create your workspace directory

This is where your personal pulse and state files live. It's separate from the cloned repo on purpose — the repo ships the tool, your workspace holds your data.

mkdir -p ~/.claude-codestart/journal

Step 3 — Copy the generator template

cp scripts/build-pulse.sh ~/.claude-codestart/build-pulse.sh
chmod +x ~/.claude-codestart/build-pulse.sh

You now have your own editable copy. The template in the repo is unchanged — edits go in your ~/.claude-codestart/ copy.

Step 4 — Customize the generator

Open ~/.claude-codestart/build-pulse.sh in your editor. The file has clearly marked SECTION blocks. Read through them once — each section has comments showing how to add your own state sources.

For a first-time setup, the minimal edit is:

1. Go to SECTION 1 — IDENTITY and replace the placeholder text with one sentence about who you are.
2. Leave the other sections as-is for now. You'll add to them as you figure out what you want Claude to know.

Save the file.

Step 5 — Test it manually

~/.claude-codestart/build-pulse.sh
cat ~/.claude-codestart/PULSE.md

You should see a rendered markdown snapshot with your identity at the top and the "Edit build-pulse.sh to add your own sections" placeholder. If you see that, the generator is working.

Step 6 — Register the SessionStart hook

This is the step that wires the generator into Claude Code. Open ~/.claude/settings.json:

# If you don't have a settings.json yet, create an empty one:
mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json

# Then open it in your editor
open -a "Visual Studio Code" ~/.claude/settings.json   # macOS with VS Code
# or: nano ~/.claude/settings.json
# or: vim ~/.claude/settings.json

If your file is currently empty (just {}): replace the contents with:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude-codestart/build-pulse.sh >/dev/null 2>&1 && cat $HOME/.claude-codestart/PULSE.md",
            "timeout": 30,
            "statusMessage": "Loading codestart pulse..."
          }
        ]
      }
    ]
  }
}

If your file already has content: merge the "hooks" key into it carefully. If you already have a "hooks" key, add this SessionStart entry to its array. Do not overwrite settings you already depend on.

Save the file.

Step 7 — Verify the warm start works

Open a completely fresh terminal window and run:

claude --print "No tool calls. Summarize everything you know about me from the pulse I provided at session start. If the pulse is empty or not loaded, say so."

You should see Claude describe the identity line you wrote in Step 4, plus whatever sections you've customized. If Claude says "I have no pulse data" or "I don't see any session start context," the hook didn't fire — check Troubleshooting below.

Step 8 — Start building your pulse

Now that the pipeline works, the actual value comes from what you put in the pulse. Open ~/.claude-codestart/build-pulse.sh again and start adding sections for:

• Your current project's git state
• Open PRs assigned to you
• Today's calendar
• A hand-maintained todo.md with your top 3 priorities
• A daily journal entry
• Whatever your personal state system looks like

See examples/ in the repo for reference implementations.

Every time you edit the generator, run it manually once to verify the output:

~/.claude-codestart/build-pulse.sh && cat ~/.claude-codestart/PULSE.md | less

When you're happy, the next claude session will pick up the new version automatically.

Troubleshooting

The hook doesn't seem to fire. Check that your ~/.claude/settings.json is valid JSON:

jq . ~/.claude/settings.json

If jq complains, your JSON has a syntax error — fix it. A missing comma or a stray } will silently disable all hooks.

The hook fires but the output is empty. Run the generator manually first — it might be erroring silently when run from the hook. The hook redirects stderr to /dev/null for cleanliness, which hides errors. Temporarily change the hook command to:

"$HOME/.claude-codestart/build-pulse.sh && cat $HOME/.claude-codestart/PULSE.md"

(Drop the >/dev/null 2>&1.) Start a new claude session and watch for error messages in the hook output. Fix the issue, then restore the 2>&1 redirect.

Claude's context is full and nothing works. Your pulse is probably too big. Run wc -c ~/.claude-codestart/PULSE.md — if it's over 100,000 bytes, trim your sources. See architecture.md#token-budget for guidance.

I changed build-pulse.sh but claude doesn't see the changes. The script only runs on session start. If you're in an existing session, start a new one or run /compact or /clear to re-trigger the hook.

I'm on Windows. claude-codestart v0.0.1 is bash-first. For WSL users it should work identically to Linux. For native Windows, wait for v0.1.0 which will include a PowerShell version of the generator, or contribute one.

Uninstall

To remove claude-codestart entirely:

1. Delete the SessionStart hook block from ~/.claude/settings.json
2. rm -rf ~/.claude-codestart
3. rm -rf ~/src/claude-codestart (if that's where you cloned it)

Nothing else was installed system-wide. Your Claude Code installation is untouched.