Session Management

Complete guide to managing sessions and conversations.

Understanding Sessions and Conversations

Session (DAF Session)

A session represents one focused piece of work (typically one JIRA ticket) with:

Session name and ID
Goal/description
JIRA ticket link (optional)
Workspace (named workspace location - enables concurrent sessions)
Time tracking data (shared across all conversations)
Progress notes
Status (created, in_progress, paused, complete)
One or more conversations (one per project directory)

Conversation (Claude Code Conversation)

A conversation represents work in a specific project directory with:

Active conversation - Your current Claude Code conversation
- Claude Code conversation history
- Project path (repository directory)
- Git branch
- Claude session ID (UUID)
- Last active timestamp
Archived conversations - Previous Claude Code conversations in the same repository
- Full conversation history preserved
- Summary of what was accomplished
- Can be viewed with daf list

Key Points:

Multi-project sessions create ONE conversation with SHARED CONTEXT across all selected projects - enabling Claude to coordinate changes across repositories
Legacy sessions can have multiple separate conversations - one for each project (backward compatibility)
Each conversation can have multiple Claude Code sessions (active + archived) for starting fresh while preserving history

Session States

Sessions progress through these states:

created → in_progress → complete

Status values (as displayed in daf list and other commands):

created - Session exists but hasn't been opened yet
in_progress - Currently working on (or worked on recently)
paused - Session paused (time tracking stopped)
complete - Work finished, session archived

Note: Status values are shown as-is in all outputs and match the filter values used with --status flag.

Workspaces: Concurrent Multi-Branch Development

Workspaces enable you to work on the same project with different branches in parallel without conflicts. Each workspace is a named location (like VSCode workspaces) that can have its own active sessions.

What are Workspaces?

A workspace is a named directory where you organize repositories. Examples:

primary - Your main development workspace (e.g., ~/development)
product-a, product-b - Organize repositories by product (e.g., ~/development/product-a, ~/development/product-b)
feat-caching - Experimental caching feature branch (e.g., ~/work/caching)
client-acme, client-globex - Separate client codebases

Why Use Workspaces?

Concurrent Sessions on Same Project: Without workspaces, you can only have ONE active session per project directory at a time. With workspaces, you can work on the same project in different workspaces simultaneously:

# Terminal 1: Main development in primary workspace
daf new --name PROJ-123 -w primary --path ~/development/myproject
# Working on main branch with one conversation

# Terminal 2: Experimental work in different workspace
daf new --name PROJ-123 -w experiments --path ~/experiments/myproject
# Working on experimental branch with separate conversation
# No conflict! They're in different workspaces.

Key Benefits:

Work on main branch + experimental feature branch in parallel
Organize repos by product, team, or workflow
Sessions remember their workspace automatically
No conflicts between concurrent sessions

Workspace Selection Priority

When creating or opening sessions, workspace is resolved in this order:

-w, --workspace flag - Explicit workspace (highest priority)
Session stored workspace - Workspace from session creation
Default workspace - Workspace marked as default in config
Interactive prompt - Select from available workspaces

Examples:

# Priority 1: -w flag overrides everything
daf new --name "api-work" -w product-a     # Uses product-a workspace
daf open api-work -w primary               # Override to primary

# Priority 2: Session remembers workspace
daf new --name "feature" -w feat-caching   # Creates in feat-caching
daf open feature                           # Uses feat-caching (remembered)

# Priority 3: Default workspace (no -w, no stored workspace)
daf new --name "new-work"                  # Uses default workspace

Managing Workspaces

# List all workspaces (can run in Claude sessions)
daf workspace list

# Add workspace (run OUTSIDE Claude sessions)
daf workspace add product-a ~/repos/product-a
daf workspace add primary ~/development --default

# Remove workspace (run OUTSIDE Claude sessions)
daf workspace remove old-workspace

# Set default (run OUTSIDE Claude sessions)
# NOTE: For switching, use -w flag instead!
daf workspace set-default primary

Important: Use -w flag for switching between workspaces per-session. The set-default command is for permanent configuration changes, not for frequent switching.

See Configuration Guide - Workspaces for detailed workspace configuration.

Concurrent Sessions FAQ

Why can't I open 2 sessions on the same repository?

DevAIFlow prevents multiple concurrent sessions in the same repository within the same workspace to protect you from several issues:

1. Branch Switching Conflicts

If Session A is on feature-a and Session B tries to checkout feature-b in the same directory, git will either block the operation or force you to stash uncommitted work.

2. Uncommitted Work Loss

If Session A has uncommitted changes and Session B switches branches, you risk losing work or creating merge conflicts.

3. User Confusion

With 2 sessions active in the same directory, it's easy to:

Forget which branch you're on
Commit Session B's work to Session A's branch
Lose track of which session is active

4. Git State Corruption

Concurrent git operations (commits, checkouts, merges) in the same repository can corrupt git state, especially with file locks and race conditions.

5. Time Tracking Conflicts

Both sessions would try to track time in the same repository, creating metadata conflicts.

How do I work on the same project concurrently?

Use different workspaces! Workspaces provide complete isolation:

# Setup: Create workspaces
daf workspace add primary ~/development
daf workspace add experiments ~/experiments

# Terminal 1: Main development
daf new PROJ-123 -w primary --path ~/development/myproject
# Works on feature-a branch

# Terminal 2: Experimental feature (completely isolated)
daf new PROJ-456 -w experiments --path ~/experiments/myproject
# Works on feature-b branch - no conflicts!

Key Benefits:

Complete physical isolation (different directories)
No branch switching conflicts
No uncommitted work risks
No git state corruption
Clear separation of concerns

Use Cases:

Main branch + experimental feature branch
Different products in same codebase
Client-specific customizations
Testing vs production work

See Workspaces for complete documentation.

What if I don't want to use workspaces?

You must complete the active session first:

# Check which session is active
daf list --active

# Complete the active session
daf complete session-name

# Now create the new session
daf new PROJ-456 --path /path/to/repo

Or resume the existing session if that's what you intended:

daf open session-name

Working Across Multiple Repositories

Recommended: Use Multi-Project Sessions with Shared Context (New!)

The modern approach creates ONE conversation with SHARED CONTEXT across all selected projects. This enables Claude to:

Coordinate changes across multiple repositories
Update backend API and frontend client together
Maintain awareness of all project changes
Provide consistent implementations across projects

This is more powerful than separate conversations because Claude can see and reference all project code simultaneously.

Example: Multi-Project Session (Recommended)

# Create session with multiple projects at once
daf new --name "user-profile" --jira PROJ-12345 -w primary --projects backend-api,frontend-app,shared-lib

# System prompts for base branch per project:
#   backend-api: branch from main
#   frontend-app: branch from develop
#   shared-lib: branch from main

# Claude Code launches from workspace directory with ALL projects visible
# You can make changes across all projects in the same conversation!

# Example conversation:
You: "Update the API endpoint to return user profiles and modify the frontend to display them"
Claude:
  - Updates backend-api/src/api/users.py
  - Updates frontend-app/src/components/Profile.tsx
  - Updates shared-lib/types/user.ts
  # All changes coordinated with shared context!

# Complete session - creates separate PR/MR for each project
daf complete PROJ-12345
# → Creates PR for backend-api targeting main
# → Creates PR for frontend-app targeting develop
# → Creates PR for shared-lib targeting main

Result: One session (PROJ-12345) with ONE multi-project conversation:

PROJ-12345 (session)
  └─ Multi-Project Conversation (SHARED CONTEXT)
     ├─ backend-api (branch: feature/PROJ-12345)
     ├─ frontend-app (branch: feature/PROJ-12345)
     └─ shared-lib (branch: feature/PROJ-12345)

Benefits:

Shared context - Claude sees all projects simultaneously
Coordinated changes - Update API and client together
Unified time tracking across all repositories
Single JIRA ticket link
Individual PRs - Each project gets its own PR with correct base branch
Different base branches - Each project can target different branches (main, develop, etc.)

Creating Multi-Project Sessions

You can create a session with multiple projects from the start:

# Create session with multiple projects at once
daf new --name "user-profile" --jira PROJ-12345 -w primary --projects backend,frontend,shared

# This creates:
# - ONE conversation with SHARED CONTEXT across all projects
# - Separate git branches in each project (same branch name by default)
# - Each project can have different base branch (prompted per-project)
# - Claude Code launched from workspace root (sees all projects)

All projects share the same conversation with clear context in prompts (e.g., [backend] Creating branch...).

Architecture: Multi-Project vs Legacy Multi-Conversation

NEW: Multi-Project Sessions (Recommended)

ONE conversation with SHARED CONTEXT across all projects
Claude sees all project code simultaneously
Can coordinate changes across repositories (e.g., update API + client together)
Launched from workspace root directory
Each project has its own git branch
daf complete creates separate PR for each project

LEGACY: Multi-Conversation Sessions (Backward Compatibility)

Multiple separate conversations - one per repository
Each conversation is isolated (no shared context)
Must switch between conversations to work on different projects
Launched from individual project directories
Kept for backward compatibility with existing sessions

When to use each:

Use multi-project when you need to coordinate changes across repositories
Legacy multi-conversation is automatically used for existing sessions

Managing Projects in Sessions

Add Projects to Existing Session

Add one or more projects after creating a session:

# Add single project
daf session add-project PROJ-12345 backend-api -w primary

# Add multiple projects at once
daf session add-project PROJ-12345 --projects frontend,docs -w primary

# Add with specific branch name
daf session add-project PROJ-12345 mobile-app -w primary --branch feature/mobile

What happens:

Validates workspace and project paths
Sets up git branches (reuses session branch or asks once)
Adds projects to the multi-project conversation
Shows [project-name] prefix in all prompts for clarity
Skips projects that already exist in session
Note: Projects are added to the existing shared conversation, not as separate conversations

Alternative via open:

# Add projects when opening session
daf open PROJ-12345 -w primary --projects backend,frontend

This adds the projects and exits (doesn't launch Claude Code).

Remove Projects from Session

Remove a project when it's no longer needed:

# Remove project (with confirmation)
daf session remove-project PROJ-12345 old-service

# Remove without confirmation
daf session remove-project PROJ-12345 legacy-api --force

What happens:

Shows project details (branch, path, messages)
Prompts for confirmation (unless --force)
Removes the project from the multi-project conversation
Shows remaining projects
Note: Removes the project from the shared conversation's projects dict

Common Workflows

Start single, expand later:

# Day 1: Start with backend
daf new PROJ-123 backend-api -w primary

# Day 2: Add frontend
daf session add-project PROJ-123 frontend-app -w primary
daf open PROJ-123 --path frontend-app

# Day 3: Add shared library
daf session add-project PROJ-123 shared-lib -w primary

Create multi-project from start:

daf new PROJ-123 -w primary --projects backend,frontend,shared
daf open PROJ-123 --path backend  # Work on specific project

Expand via open:

daf sync PROJ-123  # Existing session from JIRA
daf open PROJ-123 -w primary --projects backend,frontend,docs

Clean up:

daf session remove-project PROJ-123 old-service
daf session remove-project PROJ-123 legacy-api --force

Understanding the Relationship

JIRA Ticket: PROJ-12345
       ↓
Session: PROJ-12345 (one session per ticket)
       ├─ Conversation: backend-api
       │  ├─ Repository: /workspace/backend-api
       │  ├─ Branch: feature/PROJ-12345
       │  ├─ Active Claude session (current work)
       │  └─ Archived Claude sessions (history)
       │
       └─ Conversation: frontend-app
          ├─ Repository: /workspace/frontend-app
          ├─ Branch: feature/PROJ-12345-ui
          ├─ Active Claude session (current work)
          └─ Archived Claude sessions (history)

Important:

1 JIRA ticket = 1 Session
1 Project directory = 1 Conversation (with active + archived Claude sessions)
Each conversation has its own git branch and own Claude Code history
Time tracking is shared across all conversations in the session

Starting Fresh: Archiving Conversations

Sometimes you need to start a fresh Claude Code conversation while preserving your previous work. This is useful when:

The conversation history gets too long (causing 413 errors)
You want to take a different approach but keep the old one for reference
You've completed one part and want a clean slate for the next

Archive and Start Fresh

# Open session and archive current conversation
daf open PROJ-12345 --new-conversation

# This will:
# 1. Archive your current Claude Code conversation
# 2. Create a new Claude Code session with fresh history
# 3. Preserve all your previous conversation history

What gets preserved:

All previous conversation history (.jsonl files)
Git branch and commits
Summary of what was accomplished

What's new:

Fresh Claude Code conversation (new UUID)
Empty conversation history (clean start)
Same project, same branch

View Conversation History

See all conversations (active + archived) for a session:

daf list PROJ-12345

Example output:

Session: PROJ-12345
Conversations (2 repositories):

#1 backend-api (active)
  Claude Session: a7b3c4d5-1234-...
  Branch: feature/PROJ-12345
  Messages: 45
  Created: 2026-01-15 09:30
  Last Active: 2026-01-21 14:30

  Archived (1):
    UUID: f8e9d0a1-5678-...
    Summary: Initial implementation of user auth
    Messages: 123
    Created: 2026-01-10 10:00
    Archived: 2026-01-15 09:30

#2 frontend-app (active)
  Claude Session: b8c4d5e6-2345-...
  Branch: feature/PROJ-12345-ui
  Messages: 28
  Created: 2026-01-18 11:00
  Last Active: 2026-01-20 16:45

Use Cases:

Review what was tried before
Reference previous approaches
Understand conversation progression
Verify nothing was lost

Checking Active Conversation

Use daf active to see which conversation is currently active:

daf active

# Output when working in backend-api:
┌─ ▶ Currently Active ───────────────────────────────┐
│ DAF Session: PROJ-12345 (#1)                         │
│ JIRA: PROJ-12345                                    │
│ Conversation: backend-api                          │
│ Project: /workspace/backend-api                    │
│ Goal: Add user profile API and UI                 │
│ Branch: feature/PROJ-12345                          │
│ Time (this session): 1h 23m                        │
│ Status: in_progress                                │
│                                                     │
│ Other conversations in this session:               │
│   • frontend-app (branch: feature/PROJ-12345-ui)    │
└────────────────────────────────────────────────────┘

Key features:

Shows current conversation's project and branch
Lists other conversations with their branches
Displays session-level time tracking
Helps prevent working in wrong project

Visual Indicators in `daf list`

Active conversations are marked with ▶ symbol:

Status      Name              JIRA       Summary              Working Dir    Time
▶ 🚧        PROJ-12345 (#1)   PROJ-12345  User profile work    backend-api    3h 45m
  🆕        PROJ-12346 (#1)   PROJ-12346  Fix login bug        frontend       0h 0m

The ▶ indicator shows which conversation is currently open in Claude Code.

Creating Sessions

Recommended: Sync from JIRA (JIRA Users)

The easiest way to create sessions is to sync from JIRA:

# Sync all assigned tickets in current sprint
daf sync --sprint current

# Or sync all assigned tickets
daf sync

This automatically creates sessions for all your JIRA tickets. No need to manually create sessions!

See the JIRA Integration Guide for complete sync documentation.

Basic Session (No JIRA)

For personal experiments or work not tied to a ticket:

daf new --name "redis-test" --goal "Test Redis caching approach"

Session with JIRA (Manual Creation)

If you need to manually create a JIRA-linked session (less common):

daf new --jira PROJ-12345 --goal "Implement backup feature"

You'll be prompted for the session name:

Session name [PROJ-12345]:

Press Enter to use the JIRA key, or type a custom name.

Note: For most workflows, use daf sync instead of manually creating sessions.

Session with Specific Path

daf new --name "api-test" --goal "Test new endpoint" --path /Users/you/projects/backend

Override automatic repository detection.

Session in Specific Workspace

# Create in named workspace
daf new --name "feature-work" --goal "Implement caching" -w feat-caching

# Create in product workspace
daf new --name "api-update" --goal "Update API" -w product-a

# Uses default workspace if -w not specified
daf new --name "regular-work" --goal "Regular development"

The -w (or --workspace) flag selects which workspace to use. Sessions remember their workspace for automatic reuse on reopen.

Session from Template

daf new --name "new-feature" --goal "Build API" --template my-backend-template

Reuse configuration from a saved template.

Session Metadata

Each session stores:

Core Metadata

name - Session name (identifier)
session_id - Unique numeric ID within the session
goal - What you're trying to accomplish
status - created, in_progress, or complete
workspace_name - Workspace where this session runs (enables concurrent sessions)
working_directory - Repository name (e.g., "backend-api")
project_path - Full path to repository
branch - Git branch name
ai_agent_session_id - UUID for Claude Code conversation

JIRA Metadata (Optional)

issue_key - JIRA ticket key (e.g., "PROJ-12345")
jira_summary - Ticket title/summary
jira_status - Ticket status
jira_assignee - Who it's assigned to
sprint - Sprint name/ID

Tracking Metadata

created_at - When session was created
updated_at - Last modified time
work_sessions - List of start/stop times
total_time_seconds - Total time spent
tags - Custom tags for organization

Stored Data

Each session has a directory at $DEVAIFLOW_HOME/sessions/{SESSION-NAME}/:

metadata.json - All metadata above
notes.md - Progress notes
memory.md - Context hints (optional)

Opening Sessions

Open by Name

daf open redis-test

Open by JIRA Key

daf open PROJ-12345

Open with Workspace Override

# Override session's stored workspace
daf open PROJ-12345 -w primary

# Switch to different workspace temporarily
daf open feature-work -w experiments

The -w flag overrides the workspace stored in the session. Sessions remember their workspace from creation, but you can override it when opening.

What Happens When Opening

First Time (New Session):
- Generates Claude session UUID
- Creates git branch (if configured)
- Sends initial prompt to Claude with goal
- Starts time tracking
- Sets status to in_progress
Resuming Existing Session:
- Loads Claude conversation from UUID
- Checks out git branch
- Resumes time tracking
- Updates updated_at timestamp
Orphaned Session (UUID exists but file missing):
- Detects missing conversation file
- Generates new UUID
- Treats as first-time launch
- User sees explanation message

Initial Prompt

When creating a session, Claude receives:

Work on: PROJ-12345: Implement backup feature

Please start by reading the following context files if they exist:
- AGENTS.md (agent-specific instructions)
- CLAUDE.md (project guidelines and standards)

Also read the JIRA ticket: jira issue view PROJ-12345

This ensures Claude has full context before starting work.

Listing Sessions

All Sessions

daf list

Output:

Sessions (5):

📋 backup (#1, #2)
   🎯 Implement backup feature
   🔗 PROJ-12345
   📁 backend-api, frontend-app
   📊 in_progress
   ⏱️  3h 45m

📋 redis-test (#1)
   🎯 Test Redis caching approach
   📁 experiments
   📊 complete
   ⏱️  1h 20m

Active Sessions Only

daf list --active

Shows only sessions with status in_progress.

Filter by Repository

daf list --working-directory backend-api

Shows only sessions in the specified repository.

Filter by Sprint

daf list --sprint "2025-01"

Shows only sessions in the specified sprint.

Filter by Status

daf list --status complete

Shows sessions with specific status. Valid values: created, in_progress, paused, complete.

You can filter by multiple statuses:

daf list --status in_progress,paused

Progress Notes

Tip: daf note now works inside Claude Code! Add notes anytime to track progress and document decisions. Use /daf-notes to view all notes.

Add a Note (Local Only)

daf note backup "Implemented upload endpoint"

Saved to $DEVAIFLOW_HOME/sessions/backup/notes.md:

## 2025-11-20 14:30:00

Implemented upload endpoint

Add Note and Sync to JIRA

daf note backup "Backend complete, ready for review" --jira

This:

Saves note locally (always happens)
Adds note as JIRA comment (if linked and JIRA CLI available)

If JIRA sync fails, note is still saved locally.

Note on Most Recent Session

daf note "Quick update on current work"

Uses the most recently updated session.

View Notes

Notes are stored in markdown format:

cat $DEVAIFLOW_HOME/sessions/backup/notes.md

Session Summaries

Quick Summary (Local Mode)

daf summary backup

Output:

Session: backup (#1)
Goal: Implement backup feature
JIRA: PROJ-12345 - "Customer backup and restore"
Status: in_progress
Time: 3h 45m (5 work sessions)

Files Created: 12
Files Modified: 8
Commands Run: 24
Notes: 6

Fast, offline, statistical summary.

Detailed Summary

daf summary backup --detail

Shows full file lists and commands.

AI-Powered Summary

daf summary backup --ai-summary

Uses Claude API to generate intelligent natural language summary:

Session: backup (#1)

Summary:
Implemented a comprehensive backup system for customer data. Created new
backup service with upload endpoint, S3 integration, and encryption. Added
validation for backup metadata and implemented retry logic for failed uploads.
Still need to add restore functionality and write tests.

Key Accomplishments:
- Backup upload API endpoint with authentication
- S3 bucket integration with encryption
- Metadata validation and storage
- Error handling and retry logic

Next Steps:
- Implement restore endpoint
- Add comprehensive test coverage
- Update documentation

Completing Sessions

Basic Completion

daf complete backup

Prompts:

Mark session as complete?
Generate AI summary? (if configured)
Add summary to JIRA? (if linked)
Transition JIRA ticket? (if configured)

Complete with Status Transition

daf complete backup --status "Code Review"

Marks complete and transitions JIRA ticket to "Code Review" state.

What Happens on Completion

Status Update: Session status → complete
Time Tracking: Stops active time tracking
AI Summary (optional): Generates summary of work done
JIRA Comment (optional): Adds summary to JIRA ticket
JIRA Transition (optional): Moves ticket to new status

Deleting Sessions

Delete Single Session

daf delete backup

Prompts for confirmation:

Delete session 'backup' (#1)?
This will remove all session data including notes and metadata.
Conversation history in Claude will NOT be deleted.

Continue? [y/N]:

Delete Without Confirmation

daf delete backup --force

Delete All Sessions

daf delete --all

Complete reset - deletes all sessions. Prompts for confirmation.

Delete All Without Confirmation

daf delete --all --force

What Gets Deleted

Session metadata ($DEVAIFLOW_HOME/sessions/{NAME}/)
Progress notes
Memory files
Session entry in sessions.json

What is NOT deleted:

Claude Code conversation files (~/.claude/projects/...)
Git branches
JIRA tickets

Searching Sessions

Search by Keyword

daf search "backup"

Searches in:

Session names
Goals
JIRA summaries
Progress notes

Search with Filters

daf search "api" --working-directory backend-api
daf search "bug" --tag urgent

Time Tracking

View Time for Session

daf time backup

Output:

Time Tracking for: backup (#1)

Work Sessions:
  1. 2025-11-20 09:00:00 → 11:30:00  (2h 30m)
  2. 2025-11-20 14:00:00 → 15:15:00  (1h 15m)
  3. (active) 16:00:00 → now         (45m)

Total Time: 4h 30m
Status: in_progress

Pause Time Tracking

daf pause backup

Stops the active work session without closing Claude Code.

Resume Time Tracking

daf resume backup

Starts a new work session.

How Time Tracking Works

Automatic Start: When daf open launches Claude Code
Automatic Stop: When Claude Code exits (captured via process monitoring)
Manual Control: Use daf pause and daf resume for breaks

Time data stored in work_sessions array:

{
  "work_sessions": [
    {
      "start": "2025-11-20T09:00:00",
      "end": "2025-11-20T11:30:00"
    }
  ]
}

Linking JIRA Tickets

Link JIRA to Existing Session

daf link backup --jira PROJ-12345

This:

Validates JIRA ticket exists
Fetches ticket metadata
Links ticket to session
Updates all conversations in the session

Unlink JIRA

daf unlink backup

Removes JIRA association but keeps session data.

Session Templates

Save Session as Template

daf template save backup my-backend-template

Creates reusable template with:

Working directory pattern
Git branch pattern
Tags
JIRA key pattern (optional)

List Templates

daf template list

Use Template

daf new --name "new-api" --goal "Build endpoint" --template my-backend-template

Applies template configuration to new session.

Delete Template

daf template delete my-backend-template

Orphaned Sessions

What Are Orphaned Sessions?

Sessions where:

ai_agent_session_id is set
But conversation file doesn't exist at ~/.claude/projects/.../

This happens when:

Session creation interrupted
Claude Code crashed
Conversation files manually deleted

Detecting Orphaned Sessions

daf maintenance cleanup-sessions --dry-run

Output:

Found 2 orphaned session(s):

Session             Session ID  JIRA      Missing UUID      Status
backup (#1)         1           PROJ-12345 4ff5a139...       in_progress
test (#1)           1           -         8ab2c4e7...       created

Cleaning Up Orphaned Sessions

daf maintenance cleanup-sessions

This:

Clears orphaned ai_agent_session_id from metadata
Next daf open will generate new UUID
No session data lost

Automatic Fix on Open

When you run daf open on an orphaned session:

⚠ Conversation file not found for session 4ff5a139-113d-4e5a-abf1-92873fd96b7a
This can happen if the session was interrupted or Claude Code failed to start.

First-time launch for session: backup
Generated new session ID: 7c8d9e0f-1234-5678-9abc-def012345678

The orphan is automatically fixed.

Best Practices

1. Use Descriptive Names

Good:

daf new --name "user-auth-api" --goal "Implement OAuth2"

Bad:

daf new --name "test123" --goal "stuff"

2. Add Notes Regularly

Document progress as you work:

daf note "Completed login endpoint"
daf note "Found bug in token refresh, fixing"
daf note "Ready for code review"

3. Complete Sessions When Done

Don't leave sessions in in_progress forever:

daf complete user-auth-api

4. Use Multi-Project Sessions for Multi-Repo Work

Keep related work organized with shared context:

# Create one session with all related projects
daf new PROJ-12345 -w primary --projects backend,frontend,infrastructure
# → ONE conversation with SHARED CONTEXT across all three projects
# → Claude can coordinate changes across all repositories

5. Clean Up Old Sessions

Periodically review and delete completed work:

daf list --status complete
daf delete old-session-1
daf delete old-session-2

Or export them first:

daf export old-session-1 old-session-2 --output archive.tar.gz
daf delete old-session-1 old-session-2 --force

6. Use Templates for Consistency

Save successful session configs:

daf template save successful-project my-template
daf new --name "next-project" --goal "..." --template my-template

7. Leverage AI Summaries

Before completing, check progress:

daf summary backup --ai-summary

Use for completion:

daf complete backup  # Will offer AI summary

Troubleshooting

Session Won't Open

Problem: "No conversation found with session ID: ..."

Solution: Session is orphaned. Either:

# Automatic fix - just open it
daf open session-name

# Or manual cleanup
daf maintenance cleanup-sessions
daf open session-name

Multiple Sessions When Opening

Problem: Prompted to select from multiple conversations

Cause: Session has multiple conversations (by design for multi-repo work)

Solution: Select the one you want to work on, or use specific conversation:

daf open session-name  # Interactive selection

Can't Find Session

Problem: "Session 'name' not found"

Solution:

# List all sessions
daf list --all

# Search for it
daf search "keyword"

# Check by JIRA key
daf list | grep PROJ-12345

Time Tracking Not Working

Problem: Time doesn't update

Cause: Process monitoring may have failed

Solution:

# Manual pause/resume
daf pause session-name
daf resume session-name

Next Steps

JIRA Integration - Learn JIRA workflows
Configuration Reference - Configure session behavior
Commands Reference - All available commands

FilesExpand file tree

session-management.md

Latest commit

History

session-management.md

File metadata and controls

Session Management

Understanding Sessions and Conversations

Session (DAF Session)

Conversation (Claude Code Conversation)

Session States

Workspaces: Concurrent Multi-Branch Development

What are Workspaces?

Why Use Workspaces?

Workspace Selection Priority

Managing Workspaces

Concurrent Sessions FAQ

Why can't I open 2 sessions on the same repository?

How do I work on the same project concurrently?

What if I don't want to use workspaces?

Working Across Multiple Repositories

Example: Multi-Project Session (Recommended)

Creating Multi-Project Sessions

Architecture: Multi-Project vs Legacy Multi-Conversation

Managing Projects in Sessions

Add Projects to Existing Session

Remove Projects from Session

Common Workflows

Understanding the Relationship

Starting Fresh: Archiving Conversations

Archive and Start Fresh

View Conversation History

Checking Active Conversation

Visual Indicators in daf list

Creating Sessions

Recommended: Sync from JIRA (JIRA Users)

Basic Session (No JIRA)

Session with JIRA (Manual Creation)

Session with Specific Path

Session in Specific Workspace

Session from Template

Session Metadata

Core Metadata

JIRA Metadata (Optional)

Tracking Metadata

Stored Data

Opening Sessions

Open by Name

Open by JIRA Key

Open with Workspace Override

What Happens When Opening

Initial Prompt

Listing Sessions

All Sessions

Active Sessions Only

Filter by Repository

Filter by Sprint

Filter by Status

Progress Notes

Add a Note (Local Only)

Add Note and Sync to JIRA

Note on Most Recent Session

View Notes

Session Summaries

Quick Summary (Local Mode)

Detailed Summary

AI-Powered Summary

Completing Sessions

Basic Completion

Complete with Status Transition

What Happens on Completion

Deleting Sessions

Delete Single Session

Delete Without Confirmation

Delete All Sessions

Delete All Without Confirmation

What Gets Deleted

Searching Sessions

Search by Keyword

Search with Filters

Visual Indicators in `daf list`