AgileFlow

/session:init

PreviousNext

Initialize session harness with test verification

/session:init

Initialize or verify the session management system. This command sets up the session tracking infrastructure.

Quick Start

/agileflow:session:init

What It Does

  1. Creates .agileflow/sessions/ directory if missing
  2. Initializes registry.json with schema
  3. Registers the current directory as a session
  4. Creates a lock file with current process ID
  5. Displays session status

Example Output

First Time Setup

✓ Session initialized

  Session ID: 1
  Path: /home/user/myproject
  Branch: main

No other active sessions detected.

Already Initialized

✓ Session already active

  Session ID: 1
  Path: /home/user/myproject
  Branch: main

Other Sessions Active

✓ Session initialized

  Session ID: 1 (current)
  Path: /home/user/myproject
  Branch: main

⚠️ 2 other session(s) active in this repo.
   Run /agileflow:session:status to see all sessions.
   Run /agileflow:session:new to create isolated workspace.

When Is It Called?

Automatic (Recommended)

The SessionStart hook calls this automatically when Claude Code starts:

// .claude/settings.json
{
  "hooks": {
    "SessionStart": {
      "command": "node scripts/agileflow-welcome.js"
    }
  }
}

The welcome script registers the session and displays status.

Manual

Run manually to:

  • Verify session system is working
  • Re-register after system issues
  • Debug session problems
/agileflow:session:init

Files Created

Registry File

.agileflow/sessions/registry.json:

{
  "schema_version": "1.0.0",
  "next_id": 2,
  "project_name": "myproject",
  "sessions": {
    "1": {
      "path": "/home/user/myproject",
      "branch": "main",
      "created": "2025-12-26T10:00:00Z",
      "is_main": true
    }
  }
}

Lock File

.agileflow/sessions/1.lock:

pid=12345
started=1703588400

Troubleshooting

Session Not Detecting

# Check if registry exists
ls .agileflow/sessions/
 
# Re-initialize
/agileflow:session:init

Stale Lock Warning

If you see stale locks, the init command cleans them up:

✓ Session initialized
  Cleaned 1 stale session(s)

Permission Issues

Ensure you have write access to .agileflow/:

ls -la .agileflow/
# Should show your user as owner

Integration with Welcome Script

The AgileFlow welcome script includes session detection:

╭──────────────────────┬────────────────────────────────────╮
│ agileflow v2.53.0   main (cc45511)                        │
├──────────────────────┼────────────────────────────────────┤
│ Sessions             │ ✓ Session 1 (only)                 │
╰──────────────────────┴────────────────────────────────────╯

Or with conflicts:

│ Sessions             │ ⚠️ 2 other active                   │

⚠️  Other Claude session(s) active in this repo.

Related Commands