Skip to main content
The Sessions API tracks metadata for each coding session, including edit counts, corrections, and prompts. Use it to analyze productivity patterns and session quality.

​
Session Interface

export interface Session {
  id: string;                    // Session identifier (e.g., CLAUDE_SESSION_ID)
  project: string | null;        // Project name
  started_at: string;            // ISO 8601 timestamp
  ended_at: string | null;       // ISO 8601 timestamp (null if active)
  edit_count: number;            // Number of Edit/Write tool uses
  corrections_count: number;     // Number of corrections made
  prompts_count: number;         // Number of user prompts
}
Session IDs should be unique per session. Use process.env.CLAUDE_SESSION_ID in Claude Code or generate your own UUID.

​
Store Methods

​
startSession

​
id
string
required
Unique session identifier. Use CLAUDE_SESSION_ID or generate a UUID.
​
project
string | undefined
Project name for this session. Omit for sessions without a project context.
​
return
Session
The created session with started_at auto-populated.
If a session with the same ID already exists, this is a no-op (uses INSERT OR IGNORE).
import { createStore } from 'pro-workflow';

const store = createStore();
const sessionId = process.env.CLAUDE_SESSION_ID || `session-${Date.now()}`;

const session = store.startSession(sessionId, 'my-app');
console.log(`Session started at ${session.started_at}`);

store.close();

​
endSession

​
id
string
required
Session ID to end. Sets ended_at to current timestamp.
​
return
void
No return value. The session is marked as ended.
store.endSession(sessionId);
console.log('Session ended');
Call this in a SessionEnd hook or /wrap-up command to track session duration.

​
getSession

​
id
string
required
Session ID to retrieve.
​
return
Session | undefined
The session if found, otherwise undefined.
const session = store.getSession(sessionId);
if (session) {
  console.log(`Edits: ${session.edit_count}`);
  console.log(`Corrections: ${session.corrections_count}`);
}

​
updateSessionCounts

​
id
string
required
Session ID to update.
​
edits
number
default:"0"
Number of edits to add to edit_count.
​
corrections
number
default:"0"
Number of corrections to add to corrections_count.
​
prompts
number
default:"0"
Number of prompts to add to prompts_count.
​
return
void
No return value. Counts are incremented atomically.
This method adds to existing counts. It does not set absolute values.
const store = createStore();
const sessionId = process.env.CLAUDE_SESSION_ID;

// After an edit
store.updateSessionCounts(sessionId, 1, 0, 0);

// After a correction
store.updateSessionCounts(sessionId, 0, 1, 0);

// After a user prompt
store.updateSessionCounts(sessionId, 0, 0, 1);

store.close();

​
getRecentSessions

​
limit
number
default:"10"
Maximum number of sessions to return.
​
return
Session[]
Array of sessions sorted by started_at DESC (most recent first).
const recentSessions = store.getRecentSessions(5);

for (const session of recentSessions) {
  console.log(`${session.id}: ${session.edit_count} edits, ${session.corrections_count} corrections`);
}

​
Analytics Queries

Use the store API or raw SQL for custom analytics. 
import { createStore } from 'pro-workflow';

const store = createStore();

const result = store.db.prepare(`
  SELECT AVG(edit_count) as avg_edits
  FROM sessions
  WHERE ended_at IS NOT NULL
`).get() as { avg_edits: number };

console.log(`Average edits per session: ${result.avg_edits.toFixed(1)}`);
store.close();

​
Integration Examples

hooks/session-start.sh
#!/bin/bash
# Track session start

SESSION_ID="$CLAUDE_SESSION_ID"
PROJECT_NAME=$(basename "$PWD")

node -e "
const { createStore } = require('pro-workflow');
const store = createStore();
store.startSession('$SESSION_ID', '$PROJECT_NAME');
store.close();
"
hooks/post-tool-use.sh
#!/bin/bash
# Track edits and corrections

TOOL_NAME="$1"
OUTPUT="$2"
SESSION_ID="$CLAUDE_SESSION_ID"

if [[ "$TOOL_NAME" == "Edit" ]] || [[ "$TOOL_NAME" == "Write" ]]; then
  node -e "
  const { createStore } = require('pro-workflow');
  const store = createStore();
  store.updateSessionCounts('$SESSION_ID', 1, 0, 0);
  store.close();
  "
fi

if [[ "$OUTPUT" == *"[LEARN]"* ]]; then
  node -e "
  const { createStore } = require('pro-workflow');
  const store = createStore();
  store.updateSessionCounts('$SESSION_ID', 0, 1, 0);
  store.close();
  "
fi
hooks/session-end.sh
#!/bin/bash
# Track session end and show summary

SESSION_ID="$CLAUDE_SESSION_ID"

node -e "
const { createStore } = require('pro-workflow');
const store = createStore();

const session = store.getSession('$SESSION_ID');
if (session) {
  console.log('\\nSession Summary:');
  console.log('  Edits: ' + session.edit_count);
  console.log('  Corrections: ' + session.corrections_count);
  console.log('  Prompts: ' + session.prompts_count);
  
  const rate = session.edit_count > 0
    ? (session.corrections_count / session.edit_count * 100).toFixed(1)
    : 0;
  console.log('  Correction rate: ' + rate + '%');
}

store.endSession('$SESSION_ID');
store.close();
"

​
Next Steps

Learnings API

Store corrections from sessions

Agents

Use session memory in agents

Commands

Build session-aware commands

Insights Skill

Visualize session analytics

Build docs developers (and LLMs) love

Get started for freeTalk to us