Session Management¶

Sessions represent continuous work periods. They create breadcrumbs that help the next agent (or human) pick up exactly where you left off.

Why Sessions Matter¶

In multi-context-window agent workflows, each new session starts fresh. Without session artifacts:

Context from previous work is lost
Agents don't know what was accomplished
Handoffs between sessions are chaotic

Sessions solve this by recording:

Focus: What you intended to work on
Accomplishments: What was actually done
Blockers: What prevented progress
Next Steps: What should happen next

Starting a Session¶

Begin a session with a clear focus:

klondike session start --focus "F001 - User authentication"

This command:

Checks git status (if in a repo)
Validates artifact integrity
Records the session start time
Sets the focus area

Session Start Output¶

🔍 Checking git status...
   ✅ Working directory clean

🔍 Validating artifacts...
   ✅ Artifacts validated

🚀 Session 3 Started
   Focus: F001 - User authentication

📊 Project Status: 2/5 features (40%)

💡 Tip: Use 'klondike feature start <ID>' to mark a feature as in-progress

During a Session¶

Check Status Anytime¶

klondike status

Shows:

Project completion percentage
Feature breakdown
Current session info

Work on Features¶

# Start working on a feature
klondike feature start F001

# When done, verify it
klondike feature verify F001 --evidence "tests/auth.test.js"

Regenerate Progress File¶

If you need to update the progress markdown:

klondike progress

Ending a Session¶

When you're done working:

klondike session end \
  --summary "Completed login form with validation" \
  --completed "Login UI,Form validation,API integration" \
  --next "Add forgot password,Add remember me"

End Session Options¶

Option	Description	Example
`--summary`	What was accomplished	`"Completed login flow"`
`--completed`	Completed items (comma-separated)	`"Item 1,Item 2"`
`--blockers`	Issues encountered	`"API rate limiting"`
`--next`	Recommended next steps (comma-separated)	`"Step 1,Step 2"`
`--auto-commit`	Auto-commit changes	Flag

Auto-Commit¶

Use --auto-commit to automatically commit artifact changes:

klondike session end \
  --summary "Done for today" \
  --auto-commit

This commits:

Updated .klondike/agent-progress.json
Regenerated agent-progress.md
Any feature status changes

The Session Workflow¶

sequenceDiagram
    participant Agent
    participant Klondike
    participant Git

    Agent->>Klondike: session start --focus "F001"
    Klondike->>Git: Check status
    Klondike->>Klondike: Validate artifacts
    Klondike-->>Agent: Session started

    loop During Session
        Agent->>Klondike: feature start F001
        Agent->>Agent: Write code
        Agent->>Git: Commit changes
        Agent->>Klondike: feature verify F001
    end

    Agent->>Klondike: session end --summary "..."
    Klondike->>Klondike: Update artifacts
    Klondike->>Klondike: Regenerate progress.md
    Klondike-->>Agent: Session ended

Session Best Practices¶

Start Every Session Right¶

Run klondike status to see project state
Run klondike validate to check artifacts
Review recent git commits
Run klondike session start with clear focus

During the Session¶

Focus on one feature at a time
Commit early and often
Test as you go, not at the end
If blocked, use klondike feature block

End Every Session Clean¶

Ensure all changes are committed
Verify completed features with evidence
Run klondike session end with summary
Leave code in a mergeable state

Never Do This

Leave code in a broken state
End without summarizing work
Skip verification for "completed" features
Leave uncommitted changes

Viewing Progress¶

Status Command¶

Quick overview:

klondike status

Progress File¶

The agent-progress.md file is auto-generated from session data. View it anytime:

cat agent-progress.md

Stakeholder Report¶

Generate a report for non-technical stakeholders:

klondike report
klondike report --format plain
klondike report --output report.md --details

Session Data¶

Session data is stored in .klondike/agent-progress.json. This file is managed by Klondike - don't edit it directly.

The agent-progress.md file is regenerated automatically from this JSON whenever:

A session ends
You run klondike progress
You run klondike session end