Feature: Expose session ID as $CLAUDE_SESSION_ID environment variable

[praveenaki]

Problem

Claude Code agents have no way to programmatically determine their own session ID. This matters when:

1. Session mining — An agent wants to query its own session history (e.g., via a SQLite index of sessions) but doesn't know which session ID to filter by
2. Parallel sessions — Multiple Claude Code sessions can run simultaneously in the same project directory, so heuristics like "most recently modified JSONL file" are non-deterministic
3. Resumed sessions — When a session resumes after context loss (e.g., failed compaction), the agent needs to recover its own history

What we tried (all failed)

Approach	Why it fails
ls -lt ~/.claude/projects/*/*.jsonl | head -1	Race condition with parallel sessions
lsof -p $PPID | grep jsonl	Claude Code uses open/append/close — no persistent file handle
$CLAUDE_SESSION_ID env var	Doesn't exist
Scanning conversation text for a session ID	Could be ANY session ID, not necessarily the current one

Current workaround

Ask the user to run /status and paste the session ID. Works, but breaks autonomous workflows.

Proposed Solution

Expose the session ID as an environment variable available to all child processes (Bash tool, MCP servers, etc.):

echo $CLAUDE_SESSION_ID
# → 4721a313-bd20-426e-b9c5-24ebcb598a52

This would be analogous to how CLAUDECODE=1 and CLAUDE_CODE_ENTRYPOINT=cli are already exposed.

[github-actions]

Found 3 possible duplicate issues:

1. Feature Request: Expose session ID programmatically #20132
2. [Feature Request] Expose Session Metadata via Environment Variables and API #17188
3. [FEATURE] Expose CLAUDE_SESSION_ID to Bash commands and Claude's context #18629

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[praveenaki]

Adds new use cases for the need so love to keep it open and merged by the team.

[techjoec]

Workaround: Get your session ID via a SessionStart hook

Claude Code hooks receive session_id in their stdin JSON — you just need to feed it back. This gives you $CLAUDE_CODE_SESSION_ID in both the conversation context and the shell environment.

---

Setup (2 files)

Step 1 — Create the hook script

Save this as ~/.local/bin/claude-session-id-hook (or anywhere on your PATH):

#!/usr/bin/env bash
INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')

# Inject into conversation context so the model can see it
jq -n --arg ctx "CLAUDE_CODE_SESSION_ID=$SESSION_ID" \
    '{ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: $ctx } }'

# Inject into shell environment so Bash tool calls can use it
# Guard: each session gets its own env file — skip if already written (resume/continue)
if [ -n "$CLAUDE_ENV_FILE" ] && ! grep -q "CLAUDE_CODE_SESSION_ID" "$CLAUDE_ENV_FILE" 2>/dev/null; then
    echo "export CLAUDE_CODE_SESSION_ID=\"$SESSION_ID\"" > "$CLAUDE_ENV_FILE"
fi

Then: chmod +x ~/.local/bin/claude-session-id-hook

Step 2 — Register the hook

Add to your ~/.claude/settings.json (merge into existing hooks if you have them):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude-session-id-hook",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

---

Verify it works

Start a new Claude Code session, then run:

!echo $CLAUDE_CODE_SESSION_ID

You should get a UUID like a4b692e2-9095-43e4-849d-385e9e454782.

You can also ask Claude: "What is your CLAUDE_CODE_SESSION_ID from your system reminder?" — it will be able to read it directly from its context.

---

How it works

Channel	Mechanism	Available to
Conversation context	hookSpecificOutput.additionalContext	The model (system reminder)
Shell environment	$CLAUDE_ENV_FILE	Bash tool calls (echo $CLAUDE_CODE_SESSION_ID)

Edge cases handled

Scenario	Behavior
Resumed/continued session	Same env file path — grep guard skips the write
Forked session	New session ID, new env file — writes fresh
Parallel sessions	Each session invokes its own hook with its own stdin JSON
Subagents	Get the session ID via their parent's context (add a SubagentStart hook entry with the same script if you want it explicitly)

Requirements

• jq installed
• Claude Code with hooks support

[igorgesso]

please!!!!!