--session-id Option

Overview

The --session-id option allows you to specify a custom identifier for your Qwen Code session. This makes it easier to organize, track, and resume specific conversations, especially for long-running projects or specific features.

Syntax

qwen --session-id <your-custom-id>

Basic Usage

Create Named Session

qwen --session-id feature-authentication

This creates a session with ID feature-authentication instead of a random UUID.

Resume Named Session

# Later, resume by name
qwen --resume feature-authentication

Much easier than remembering a1b2c3d4-e5f6-7890-abcd-ef1234567890!

Benefits

Easy Identification

# Random IDs (hard to remember)
qwen
Session ID: f3d2e1c4-b5a6-7890-dcba-ef1234567890

# Named IDs (easy to remember)
qwen --session-id fix-login-bug
Session ID: fix-login-bug

Organized Workflows

# Organize by feature
qwen --session-id feature-notifications
qwen --session-id feature-payments
qwen --session-id feature-analytics

# Organize by task type
qwen --session-id refactor-auth-module
qwen --session-id add-unit-tests
qwen --session-id update-dependencies

Team Collaboration

# Shared session names
qwen --session-id sprint-23-api-work
qwen --session-id hotfix-prod-issue-456
qwen --session-id onboarding-new-dev

CI/CD Integration

# Predictable session IDs
qwen --session-id "ci-build-${BUILD_NUMBER}"
qwen --session-id "pr-${PR_NUMBER}-review"

Naming Conventions

By Feature

qwen --session-id feature-user-profiles
qwen --session-id feature-social-login
qwen --session-id feature-email-notifications

By Bug Number

qwen --session-id bug-123-memory-leak
qwen --session-id bug-456-cors-error
qwen --session-id hotfix-789-crash

By Task

qwen --session-id refactor-database-layer
qwen --session-id migrate-to-typescript
qwen --session-id add-api-documentation

By Date

qwen --session-id "2024-03-10-sprint-planning"
qwen --session-id "2024-03-11-code-review"
qwen --session-id "2024-03-12-bug-fixing"

By Project Phase

qwen --session-id mvp-development
qwen --session-id beta-testing-fixes
qwen --session-id production-optimization

Use Cases

Feature Development

# Start feature work
qwen --session-id feature-oauth
> Implement OAuth authentication

# Next day, continue
qwen --resume feature-oauth
> Add OAuth providers

# Days later, finalize
qwen --resume feature-oauth
> Write tests for OAuth

Bug Fixing

# Track bug investigation
qwen --session-id bug-401-login-fails
> Investigate login failure

# Continue investigation
qwen --resume bug-401-login-fails
> Test potential fixes

# Implement fix
qwen --resume bug-401-login-fails
> Implement the fix

Code Reviews

# Review PR
qwen --session-id pr-123-review
> Review changes in PR #123

# Follow-up
qwen --resume pr-123-review
> Check if feedback was addressed

Learning Sessions

# Learning new tech
qwen --session-id learning-graphql
> Help me learn GraphQL

# Continue learning
qwen --resume learning-graphql
> Now explain GraphQL subscriptions

Session Validation

Valid Session IDs

✅ Alphanumeric characters: feature-auth
✅ Hyphens: fix-bug-123
✅ Underscores: feature_oauth
✅ UUIDs: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Invalid Session IDs

❌ Spaces: feature auth (use feature-auth)
❌ Special chars: feature@auth (use feature-auth)
❌ Empty string: "" (must provide ID)

Validation Rules

# Valid
qwen --session-id feature-123
qwen --session-id ABC_def_456
qwen --session-id my-cool-feature

# Invalid (will show error)
qwen --session-id "my feature"  # Spaces not allowed
qwen --session-id "feature@123"  # @ not allowed

Combining with Other Options

With Prompts

qwen --session-id task-123 --prompt "Start implementing feature"

With YOLO Mode

qwen --session-id automated-fixes --yolo --prompt "Fix all linting errors"

With Models

qwen --session-id complex-refactor --model qwen-coder-plus

With Output Format

qwen --session-id ci-build --prompt "Run tests" --output-format json

Session Persistence

Sessions with custom IDs are stored in:

~/.qwen/sessions/<project-hash>/
  ├── feature-auth.json
  ├── bug-123.json
  └── refactor-db.json

List Your Sessions

# View all session IDs
ls ~/.qwen/sessions/<project-hash>/

# Or use resume picker
qwen --resume

Session Metadata

# View session info
cat ~/.qwen/sessions/<project-hash>/feature-auth.json | jq '{
  sessionId,
  startTime,
  messageCount: (.messages | length),
  totalTokens: .usage.totalTokens
}'

Automation Examples

CI/CD Build Session

# .github/workflows/ai-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: AI Review
        env:
          DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
        run: |
          qwen --session-id "pr-${{ github.event.pull_request.number }}" \
               --prompt "Review the changes" \
               --output-format json

Daily Standup

#!/bin/bash
# daily-standup.sh

DATE=$(date +%Y-%m-%d)
SESSION="standup-$DATE"

qwen --session-id "$SESSION" --prompt "
Review git commits from today and summarize:
- What was accomplished
- What's in progress  
- Any blockers
"

Feature Tracking

#!/bin/bash
# track-feature.sh

FEATURE_NAME=$1
SESSION="feature-${FEATURE_NAME}"

qwen --session-id "$SESSION" --prompt "
Track progress on feature: $FEATURE_NAME
- List completed tasks
- List remaining tasks
- Estimate completion
"

Test Session

# Create test session
qwen --session-id test-session --sandbox

# Experiment safely
> Try risky operations

# Don't worry about breaking things
# It's isolated in the test session

Best Practices

Use Descriptive Names

Make session IDs self-explanatory:

# Bad
qwen --session-id s1
qwen --session-id temp
qwen --session-id test

# Good
qwen --session-id implement-user-auth
qwen --session-id fix-payment-bug
qwen --session-id refactor-api-layer

Follow Naming Convention

Be consistent across your team:

# Team convention: type-description-number
qwen --session-id feature-oauth-123
qwen --session-id bug-login-456
qwen --session-id refactor-db-789

Keep IDs Short But Clear

Balance brevity with clarity:

# Too long
qwen --session-id implement-the-new-user-authentication-system-with-oauth

# Too short
qwen --session-id auth

# Just right
qwen --session-id feature-oauth-auth

Include Context

Add relevant context to IDs:

# Include issue number
qwen --session-id bug-gh-123

# Include date for time-sensitive tasks
qwen --session-id hotfix-2024-03-10

# Include sprint for sprint work
qwen --session-id sprint-23-api

Session ID vs Resume

Use —session-id When:

✅ Creating a new session with a specific name
✅ You know the name you want to use
✅ Organizing work by feature or task
✅ CI/CD and automation

Use —resume When:

✅ Continuing existing session
✅ Don’t remember the exact ID
✅ Want to browse available sessions

Example Workflow

# Day 1: Create named session
qwen --session-id feature-notifications
> Implement notification system

# Day 2: Resume by name
qwen --resume feature-notifications
> Continue with email notifications

# Day 3: Resume by name
qwen --resume feature-notifications
> Add push notifications

Troubleshooting

Session ID Already Exists

If you use an existing session ID:

qwen --session-id feature-auth
# Continues existing 'feature-auth' session

To start fresh:

# Delete old session
rm ~/.qwen/sessions/<project-hash>/feature-auth.json

# Start new session
qwen --session-id feature-auth

Invalid Session ID Format

Error: Invalid session ID format

Solution:

# Fix special characters
qwen --session-id "feature@auth"  # ❌
qwen --session-id "feature-auth"   # ✅

# Remove spaces
qwen --session-id "feature auth"   # ❌
qwen --session-id "feature-auth"   # ✅

Can’t Find Custom Session

If you can’t find your named session:

# List all sessions
ls ~/.qwen/sessions/<project-hash>/

# Search for session
find ~/.qwen/sessions -name '*feature*'

# Use session picker
qwen --resume

Advanced Usage

Dynamic Session IDs

#!/bin/bash
# Generate session IDs dynamically

BRANCH=$(git branch --show-current)
qwen --session-id "work-${BRANCH}"

# Automatically ties sessions to Git branches

Session Templates

#!/bin/bash
# Create session from template

TEMPLATE=$1
NAME=$2

case $TEMPLATE in
  feature)
    qwen --session-id "feature-${NAME}"
    ;;
  bug)
    qwen --session-id "bug-${NAME}"
    ;;
  refactor)
    qwen --session-id "refactor-${NAME}"
    ;;
esac

# Usage: ./create-session.sh feature oauth

Session Namespaces

# Organize by namespace
qwen --session-id "frontend:feature-ui"
qwen --session-id "backend:feature-api"
qwen --session-id "infra:setup-ci"

# Easy to filter
ls ~/.qwen/sessions/<project-hash>/ | grep frontend:

--resume Option

Resume previous sessions

--continue Option

Continue most recent session

Session Management

Complete guide to sessions

Workflow Organization

Organizing your AI workflow

Documentation Index

​Overview

​Syntax

​Basic Usage

​Create Named Session

​Resume Named Session

​Benefits

​Easy Identification

​Organized Workflows

​Team Collaboration

​CI/CD Integration

​Naming Conventions

​By Feature

​By Bug Number

​By Task

​By Date

​By Project Phase

​Use Cases

​Feature Development

​Bug Fixing

​Code Reviews

​Learning Sessions

​Session Validation

​Valid Session IDs

​Invalid Session IDs

​Validation Rules

​Combining with Other Options

​With Prompts

​With YOLO Mode

​With Models

​With Output Format

​Session Persistence

​List Your Sessions

​Session Metadata

​Automation Examples

​CI/CD Build Session

​Daily Standup

​Feature Tracking

​Test Session

​Best Practices

​Session ID vs Resume

​Use —session-id When:

​Use —resume When:

​Example Workflow

​Troubleshooting

​Session ID Already Exists

​Invalid Session ID Format

​Can’t Find Custom Session

​Advanced Usage

​Dynamic Session IDs

​Session Templates

​Session Namespaces

​See Also