start-session

name	start-session
description	Use when user says "let's get started", "where are we", or at beginning of a session. Reads project context from CLAUDE.md, checks git status and recent commits, and provides orientation for the session. Works across all repo types (code, research, mixed).

Session Start

Orient at the beginning of a work session. Execute these steps directly (do NOT spawn a subagent — you have the session context, a subagent does not).

Steps

0. Read project instructions

Check CLAUDE.md for ## Session Wrap-up, ## Deployment, sync commands, or similar sections. Note any sync/pull commands — you'll run them in Step 1.

1. Sync from remote

If CLAUDE.md documents a sync or pull command (rsync, git pull, etc.), run it now. If nothing is documented, skip this step.

2. Detect repo type

CLAUDE.md is already loaded into conversation context — don't re-read it. Detect repo type from type: declaration in CLAUDE.md or infer from contents (package.json = code, mostly .md = research). Only read agents.md or README.md if CLAUDE.md is missing or lacks project context.

3. Check git state

git fetch --prune 2>/dev/null
git status --short
git branch --show-current
git log --oneline -5

After fetching, check if the current branch is behind the remote:

git rev-list --count HEAD..@{u} 2>/dev/null

If behind, note it in the summary so the user can decide whether to pull.

Also list any remote-only branches (excluding main/master) if they exist:

git branch -r --no-merged HEAD 2>/dev/null | grep -v HEAD | grep -v 'main$' | grep -v 'master$' | head -5

Check for forgotten stashes from previous sessions:

git stash list 2>/dev/null | head -5

If stashes exist, list them in the summary so the user can decide whether to pop or drop them.

3b. Check worktrees

If the repo uses git worktrees (common for experiment frameworks):

git worktree list 2>/dev/null

If multiple worktrees exist, list them in the summary. This surfaces sibling experiments or feature branches the user may have been working on.

4. Check for existing plans

Look for files in .claude/plans/. If any exist, list them with a one-line summary. These may represent in-progress work from previous sessions.

5. Check for running background processes

Flag any relevant background processes (pm2, nohup jobs, screen sessions, drip campaigns). These may be left over from a previous session or actively running.

5b. Check agent-inbox for pending handoffs

Some projects use an _agent-inbox/ handoff pattern — sandboxed/container agents drop tasks there for the host Claude Code session to execute (things they can't do: deploy, touch host, run pm2, edit .env, etc.).

1. Locate the inbox. Check _agent-inbox/ in the current repo. Also check any related-repo path referenced by CLAUDE.md (e.g., a ## Related Repository section with a "Local path:" line). Auto-memory may also record an inbox path — use it if the current CLAUDE.md points there.
2. Pull before listing so items are fresh: cd <inbox-repo> && git pull.
3. List pending items. .md files directly in _agent-inbox/ that are NOT in the done/ subfolder, excluding README.md (that's the inbox's own readme, not an instruction).
4. Surface each pending item in the orientation with filename + a one-line summary (first heading or first non-empty line). These are tasks waiting for execution.
5. Do not auto-execute. Let the user decide whether to process them this session — some may be stale, superseded, or lower priority than the user's current goal.

Completion convention (for when the user chooses to process): move the file to done/ via git mv and commit the move to the inbox repo. Run any deploy command documented in the instruction.

6. Parse roadmap sections

From CLAUDE.md, extract — skip any that don't exist:

• ## Current Focus — Suggested starting point for the session
• ## Roadmap — Count total vs completed items, list next 2-3 incomplete items
• ## Session Log — Most recent entry (what was completed, what was next)

6b. Flag stale session log entries

If any session log entries are older than 30 days, flag them for archiving. Suggest the user move old entries to a separate file (e.g., docs/session-archive.md) or delete them to keep CLAUDE.md concise.

7. Output orientation summary

Provide a structured summary including: project purpose, current branch, uncommitted changes, upstream status, recent commits, current focus, roadmap progress, last session summary, existing plans, and any running background processes.

Adapt for repo type:

• Code repos (default): Focus on git state, plans, running services
• Research repos: Include document structure, recently edited files, where writing left off
• Mixed: Combine both

Structure checks

After the orientation, note any missing infrastructure as suggestions (don't block on them):

1. No CLAUDE.md — Offer to create one with project description, roadmap sections, and current focus placeholder. Ask: "What is this project for? (one sentence)"

2. CLAUDE.md exists but missing roadmap sections — Suggest adding ## Current Focus, ## Roadmap, and ## Session Log. These enable progress tracking and /wrap-up-session integration.

Notes

• Pairs with /wrap-up-session which writes the same roadmap sections this skill reads
• The skill is a checklist — defer to project CLAUDE.md for project-specific details (sync commands, deploy targets, branch strategy)
• If plans exist in .claude/plans/, flag stale ones (>30 days) for cleanup