End cold starts for Claude Code sessions. Your LLM wakes up already knowing.
claude-codestart is a tiny tool that injects your live, personal state into every Claude Code session at startup. Instead of re-explaining what you're working on, what you ate, what broke, or what you decided yesterday, Claude already knows — because your state is delivered to it automatically the moment the session begins.
No vectors. No embeddings. No black box. Just a markdown file and a hook.
Part of the CodeBloodedAI family of tools for the Claude Code era.
You open claude in a new terminal. It auto-loads your CLAUDE.md — your identity, your rules, your project paths. That's who you are, stable.
What it doesn't load is what's happening today:
- What's on fire in the repo right now
- Which PRs are open
- What test is broken
- What decision you locked in this morning
- What your teammate DM'd you at 2pm
- What you ate for lunch (if you're using Claude for health tracking)
- What the build is doing right now
Every session starts amnesiac about today. You either spend the first five minutes copy-pasting context, or Claude guesses wrong and you correct it for another five minutes. Multiply by ten sessions a day. That's an hour a day of repeated context.
Claude Code supports a SessionStart hook that runs a script when a new session begins. The script's stdout becomes part of Claude's system context, just like CLAUDE.md.
claude-codestart gives you a generator script that reads your live state files (whatever they are — JSON, markdown, shell output, git logs) and compiles them into a single PULSE.md markdown file. That file gets injected into every new session automatically via the hook.
The result: Claude wakes up with today already loaded before you type your first word.
$ claude --print "No tool calls. What am I working on today?"
I don't know. I don't have context about your current work.$ claude --print "No tool calls. What am I working on today?"
Based on today's pulse: you're mid-way through a PSMF cut (Day 9),
ordered a Lofta WatchPAT home sleep study arriving Friday, and the
SnoreLab score last night was 206 (severe OSA territory). Your top
action is tonight's 19:00 dinner cutoff — first night with the new
rule active.Both of those are real outputs from the same fresh claude --print session — the only difference is whether the hook was installed. Zero tool calls. The LLM just knew.
┌───────────────── SOURCES OF TRUTH ─────────────────┐
│ Your state files, updated as you live/work: │
│ │
│ daily-log.json journal/*.md status.json │
│ git log gh pr list build output │
│ (anything you want Claude to know about today) │
└──────────────┬─────────────────────────────────────┘
│
▼
┌──────────────────────┐
│ build-pulse.sh │ GENERATOR
│ (you customize) │ reads sources → PULSE.md
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ ~/.../PULSE.md │ ARTIFACT
│ single markdown file │ regenerated on every session
└──────────┬───────────┘
│ triggered by SessionStart event
▼
┌──────────────────────┐
│ SessionStart hook │ DELIVERY
│ ~/.claude/settings │ runs generator, cats PULSE.md
└──────────┬───────────┘
│
▼
┌──────────────────────────────────────────────┐
│ ANY NEW CLAUDE CODE SESSION │
│ (any agent, any directory, any project) │
│ │
│ First user message hits an LLM that │
│ already knows today's state. │
└──────────────────────────────────────────────┘
Full architecture in docs/architecture.md.
Requirements: macOS or Linux, bash, jq, Claude Code v2.0+.
git clone https://github.com/codebloodedai/claude-codestart.git
cd claude-codestartmkdir -p ~/.claude-codestart
cp scripts/build-pulse.sh ~/.claude-codestart/build-pulse.sh
chmod +x ~/.claude-codestart/build-pulse.shOpen ~/.claude-codestart/build-pulse.sh and edit the SOURCES section at the top. Point it at your state files. The default shows examples; delete what you don't need, add what you do.
The tool is intentionally a customizable template instead of a config-driven framework. Your state is yours — the script is yours to shape.
~/.claude-codestart/build-pulse.sh
cat ~/.claude-codestart/PULSE.mdYou should see a rendered markdown snapshot of everything you declared as sources.
Edit ~/.claude/settings.json and add the hook:
{
"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..."
}
]
}
]
}
}A complete reference config is at hooks/session-start.example.json.
claude --print "No tool calls. Summarize what's in my pulse."If Claude describes your current state without running any tools, you're warm-started.
Full install walkthrough: docs/installation.md.
examples/minimal/— bare-minimum setup for the first-time user. One journal file, one status file, done in 3 minutes.
More examples coming. Want to contribute one? Open a PR.
Q: How is this different from Mem0, Letta, or Zep? Those are memory backends with vector or graph retrieval. They extract facts from conversations and query them later. claude-codestart does no extraction, no retrieval, and has no database — it just concatenates your existing state files into a markdown snapshot and injects it. If you already have source-of-truth files (and you should), claude-codestart is the shortest path from those files to Claude's context window. It is complementary to memory backends, not a replacement.
Q: Does this work with claude --agent <name> sessions?
Yes. The hook fires on every session start regardless of agent. Your custom agent loads on top of the pulse, not instead of it. You get both the personality of the agent and the live state of your world.
Q: What happens if my state files are huge? Your generator is your responsibility — trim what you inject. We recommend a soft cap of ~25,000 tokens (~100 KB of markdown). Beyond that you're eating into Claude's working context for actual conversation. Full guidance in docs/architecture.md.
Q: What if I want multi-user / SaaS? Out of scope for v0.0.1. claude-codestart is single-user by design. For multi-tenant systems, each user runs their own generator and their own hook.
Q: Doesn't the hook rebuild PULSE.md on every session start? Isn't that wasteful?
Yes and no. It's wasteful if your generator is slow. If your generator is ~200ms of bash and jq (the common case), it's free. The benefit — fresh state on every wake — massively outweighs the cost. If you need more, add a cron job that rebuilds in the background and have the hook just cat the file.
Q: Why not just a vector DB? We wrote a whole document on this: docs/architecture.md. Short version: your state is already in files. Embeddings add opacity. Traceability matters. Claude is already good at reading markdown. Simple wins.
v0.0.1 — experimental / early adopters.
This is the shape of the idea. It works. It's already being used daily. But the API (the structure of the template script, the config format) may change before v0.1.0 based on community feedback. Pin commits, not tags, if you want stability through this phase.
Issues, PRs, examples, and "I used this for X" stories all welcome. No contribution guide yet — just open a PR and we'll talk.
MIT. See LICENSE.
Born from a private session-context injection system built by @rudymartinezai for his personal health tracking agent. Open-sourced under CodeBloodedAI so everyone else in the Claude Code ecosystem can stop doing cold starts.
The architecture owes a debt to Andrej Karpathy's LLM-maintained personal wiki pattern — markdown-first, human-readable, no black boxes.
End cold starts. Ship warm.