Failed Kickstart Locks Up CC

[Tswiggs]

cc-sessions Version

0.3.6

Installation Method

npm/npx (JavaScript)

Operating System

Windows 11

Shell/Terminal

PowerShell

IDE/Environment

Cursor

Bug Description

SessionStart Hook Blocks Text Input After New Session Starts

Bug Description

The kickstart_session_start.js hook prevents any text from being entered after a new Claude Code session starts in the cc-sessions repository. The hook intercepts every session start and displays kickstart onboarding instructions, blocking normal Claude interaction.

Environment

• cc-sessions version: 0.3.6
• Platform: Windows (win32)
• Location: C:\Projects\cc-sessions

Expected Behavior

After starting a new Claude Code session, users should be able to immediately interact with Claude and enter text/commands normally.

Actual Behavior

When a new session starts, the SessionStart hook outputs kickstart instructions telling users to "Just say 'kickstart' and press enter to begin", preventing any normal interaction with Claude.

Root Cause Analysis with Evidence

1. Hook Configuration

The .claude/settings.json file has a SessionStart hook configured (lines 43-53):

"SessionStart": [
  {
    "matcher": "startup|clear",
    "hooks": [
      {
        "type": "command",
        "command": "node \"%CLAUDE_PROJECT_DIR%\\sessions\\hooks\\kickstart_session_start.js\""
      }
    ]
  }
]

2. Hook Implementation - No Progress Check

The kickstart_session_start.js hook has critical issues:

Lines 88-104 - Hook assumes kickstart should always run:

//!> 1. Load state and check kickstart metadata
const STATE = loadState();

// Get kickstart metadata (should ALWAYS exist if this hook is running)
const kickstartMeta = STATE.metadata?.kickstart;
if (!kickstartMeta) {
    // This is a BUG - fail loudly
    console.log(JSON.stringify({
        hookSpecificOutput: {
            hookEventName: 'SessionStart',
            additionalContext: 'ERROR: kickstart_session_start hook fired but no kickstart metadata found. This is an installer bug.'
        }
    }));
    process.exit(1);
}

Lines 117-133 - Always outputs blocking instructions:

//!> 2. Output deterministic instructions for Claude to begin kickstart via API
// Detect OS for correct sessions command
const isWindows = process.platform === "win32";
const sessionsCmd = isWindows ? "sessions/bin/sessions.bat" : "sessions/bin/sessions";

const beginCmd = mode === 'subagents' ? `${sessionsCmd} kickstart subagents` : `${sessionsCmd} kickstart full`;
let instructions = `Kickstart onboarding is enabled. Begin immediately by running:\n\n  ${beginCmd}\n\nThen, for each module chunk returned, follow all instructions completely. When finished with a chunk, run:\n\n  ${sessionsCmd} kickstart next\n\nRepeat until kickstart is complete.`;
// Add a clearly delineated user section to guide manual starts
instructions += `\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nUSER INSTRUCTIONS:\nJust say 'kickstart' and press enter to begin\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`;

console.log(JSON.stringify({
    hookSpecificOutput: {
        hookEventName: 'SessionStart',
        additionalContext: instructions
    }
}));
process.exit(0);

3. Current State Shows Kickstart Already in Progress

From sessions-state.json (lines 75-98):

"metadata": {
  "kickstart": {
    "mode": "full",
    "sequence": [
      "01-discussion.md",
      "02-implementation.md",
      "03-tasks-overview.md",
      "04-task-creation.md",
      // ... more modules
    ],
    "current_index": 3,
    "completed": [
      "01-discussion.md",
      "02-implementation.md",
      "03-tasks-overview.md"
    ],
    "last_active": "2025-10-29T19:35:11.265Z"
  }
}

Evidence of the problem:

• current_index: 3 means the user is on the 4th module (04-task-creation.md)
• Three modules already completed
• last_active shows recent activity (today)
• Despite this progress, the hook still blocks every session with "Just say 'kickstart' and press enter"

4. Active Todos Show Work in Progress

From sessions-state.json (lines 22-48):

"todos": {
  "active": [
    {
      "content": "Create task file from template with appropriate priority, type, and structure",
      "status": "completed",
      "activeForm": "Creating task file from template"
    },
    {
      "content": "Run context-gathering agent to create context manifest",
      "status": "in_progress",
      "activeForm": "Running context-gathering agent"
    }
    // ... more todos
  ]
}

This proves the user is actively working on tasks, but the SessionStart hook ignores this state.

The Problem

The hook is designed for initial onboarding but fires on EVERY session start, not just when kickstart needs to begin. It doesn't check:

• Whether kickstart instructions were already shown
• Whether kickstart is already in progress
• Whether the user wants to continue with kickstart or work normally

Reproduction Steps

1. Install cc-sessions version 0.3.6 with kickstart mode enabled
2. Progress through some kickstart modules (get to index 3 or beyond)
3. Start a new Claude Code session in the project directory
4. Observe that you cannot enter any text except responding to the kickstart prompt

Suggested Fixes

Fix 1: Add State Check (Recommended)

Modify kickstart_session_start.js to check if kickstart is already in progress:

// Check if we've already shown instructions recently
const kickstartMeta = STATE.metadata?.kickstart;
if (kickstartMeta?.last_shown) {
  const lastShown = new Date(kickstartMeta.last_shown);
  const hoursSinceShown = (Date.now() - lastShown.getTime()) / (1000 * 60 * 60);
  if (hoursSinceShown < 1) {
    // Skip if shown within last hour
    process.exit(0);
  }
}

Fix 2: Use Session-Based Triggering

Only show kickstart instructions on the first session or when explicitly requested, not on every session start.

Fix 3: Add Disable Flag

Add a configuration option to disable the SessionStart hook after initial setup:

if (kickstartMeta?.onboarding_complete) {
  process.exit(0);
}

Workaround for Users

Temporary Fix #1: Remove SessionStart Hook

Edit .claude/settings.json and remove lines 43-53 (the entire SessionStart section).

Temporary Fix #2: Clear Kickstart Metadata

node -e "const fs = require('fs'); const path = 'C:\\Projects\\cc-sessions\\sessions\\sessions-state.json'; const state = JSON.parse(fs.readFileSync(path)); delete state.metadata.kickstart; fs.writeFileSync(path, JSON.stringify(state, null, 2));"

Temporary Fix #3: Comment Out Hook

Rename or comment out the hook file to prevent it from running:

mv sessions/hooks/kickstart_session_start.js sessions/hooks/kickstart_session_start.js.disabled

Impact

• Severity: High - Completely blocks normal Claude Code usage
• Affected Users: Anyone using cc-sessions with kickstart mode enabled
• Workaround Available: Yes, multiple options provided above

Additional Context

The hook appears to be well-intentioned for onboarding but lacks session state management. It assumes every session start is a fresh onboarding attempt, which causes issues for users who have already started the kickstart process or want to use Claude Code normally while kickstart is installed.

Files Involved

• .claude/settings.json (lines 43-53)
• sessions/hooks/kickstart_session_start.js (entire file, especially lines 88-133)
• sessions/sessions-state.json (metadata.kickstart section)
• sessions/hooks/shared_state.js (state management functions)

Steps to Reproduce

Reproduction Steps

1. Install cc-sessions version 0.3.6 with kickstart mode enabled
2. Progress through some kickstart modules (get to index 3 or beyond)
3. Start a new Claude Code session in the project directory
4. Observe that you cannot enter any text except responding to the kickstart prompt

Expected Behavior

No response

Error Messages

Additional Context

No response

[patHyatt]

@Tswiggs Wonderful writeup. Came here to see if anyone else was experience similar and found this.

[satoastshi]

in general, Kickstart is a one time disposable... kickstart...

that is, it runs, and the last command it runs is sessions/bin/sessions kickstart complete

this command deletes kickstart_session_start and deletes kickstar_ from the hook file path, leaving just session_start (the permanent startup hook for sessions).

Just run sessions/bin/sessions kickstart complete from your repo root