Command: gears session

Create or open today's session file for documenting your development work.

Overview

The session command creates a daily session file in .gears/sessions/ using the format YYYY-MM-DD.md. Session files help you and AI agents track what was worked on each day, maintaining context and continuity across development sessions.

Syntax

run gears session

No flags or arguments required. The command automatically uses today's date.

What It Does

Running gears session:

Checks for a session file for today's date
If it doesn't exist, creates YYYY-MM-DD.md with a standard template
If it already exists, displays a confirmation message
Session files accumulate over time, creating a historical log of your project

Session File Template

Each new session file is created with this structure:

# Session: March 25, 2026

## Goals

_What do you plan to accomplish today?_

## Work Completed

-

## Decisions Made

-

## Problems Encountered

-

## Next Steps

-

## Notes

_Any additional context, links, or observations_

When to Use

Start of day: Create today's session file when beginning work

Working with AI Agents

Always ask your AI agent to run gears session at the start of each work session. The output:

Reminds the agent what session files are for
Shows the agent where daily work documentation lives
Teaches the agent to track progress and maintain context

Example:

❌ "Let's start working on the feature"
✅ "Run gears session to start today's work log, then let's begin"

This creates a historical record that helps the agent understand project evolution and previous decisions.

Context switching: Before starting work on a different project
After breaks: When resuming work after time away
Before AI sessions: Give AI agents current context to work from

Examples

Create Today's Session

$ gears session
Checking .gears/sessions/2026-03-25.md...
Creating session template...
Added standard sections: Goals, Work Completed, Decisions Made, Next Steps
[OK] Session file ready: .gears/sessions/2026-03-25.md

File Already Exists

$ gears session
Session file already exists: .gears/sessions/2026-03-25.md

The command won't overwrite existing session files, protecting your work.

Typical Session File Content

# Session: March 25, 2026

## Goals

- Implement user authentication system
- Fix bug in file upload component
- Update documentation for auth flow

## Work Completed

- ✅ Added login and registration pages
- ✅ Integrated Laravel Sanctum for API authentication
- ✅ Created AuthController with login/logout methods
- ✅ Fixed file upload validation issue (files > 10MB now work)
- ✅ Updated API documentation with new auth endpoints

## Decisions Made

- Using Sanctum over Passport for simpler API token management
- Storing auth tokens in httpOnly cookies for security
- File uploads limited to 20MB (was 10MB)

## Problems Encountered

- Cookie-based auth not working in dev environment → Fixed by updating CORS config
- File validation broke for large files → Updated max_upload_size in php.ini

## Next Steps

- Add password reset functionality
- Implement email verification
- Write tests for auth flow
- Add rate limiting to login endpoint

## Notes

- Auth tokens expire after 24 hours
- Need to document token refresh flow for mobile apps
- Consider adding OAuth providers (Google, GitHub) in future

Purpose and Benefits

For Developers

Daily log: Track what you accomplished each day
Decision history: Remember why you made specific choices
Problem tracking: Document issues and their solutions
Continuity: Easily pick up where you left off

For AI Agents

Context awareness: Understand recent project history
Decision context: Know what's already been tried
Problem patterns: Learn from past issues
Work prioritization: See what's already done vs. remaining

For Teams

Transparency: Team members can see what others are working on
Knowledge sharing: Solutions to problems are documented
Onboarding: New team members can read session history
Retrospectives: Review what was accomplished over time

Common Workflows

Daily Development Routine

# Morning: Start your day
gears session          # Create today's session
# Fill in "Goals" section

# During work: Update as you go
# Add completed items to "Work Completed"
# Document decisions in "Decisions Made"

# End of day: Review and plan
# Update "Next Steps" for tomorrow
gears sync push        # Backup to cloud

Collaborative Project

# Team member A (morning)
gears session
gears sync pull       # See what teammates worked on yesterday
# Read recent sessions to understand project state

# Team member A (end of day)
gears session         # Update today's session
gears sync push       # Share progress with team

# Team member B (next day)
gears sync pull       # Gets team member A's session updates
gears session         # Create own session file

Long-Term Project Tracking

# View all sessions
ls .gears/sessions/

# Output:
# 2026-03-01.md
# 2026-03-02.md
# 2026-03-05.md  (no work on 3rd, 4th)
# 2026-03-25.md

# Search across sessions
grep -r "authentication" .gears/sessions/

# Find when a decision was made
grep -r "Using Sanctum" .gears/sessions/

Session File Organization

File Naming

Files are always named YYYY-MM-DD.md:

.gears/sessions/
├── 2026-01-15.md
├── 2026-01-16.md
├── 2026-01-22.md  (gaps are fine - no work on those days)
├── 2026-02-03.md
└── 2026-03-25.md

Retention

Session files accumulate indefinitely. They should be:

✅ Committed to version control
✅ Synced to mygears.dev via gears sync push
✅ Kept as permanent project history

Archiving (Optional)

For long-running projects with hundreds of sessions:

# Create archive directory
mkdir .gears/sessions/archive

# Move old sessions (example: older than 6 months)
mv .gears/sessions/2025-*.md .gears/sessions/archive/

Best Practices

What to Document

Do document:

✅ Features implemented
✅ Bugs fixed
✅ Decisions made and why
✅ Problems encountered and solutions
✅ Things learned
✅ Next steps and TODOs

Don't document:

❌ Sensitive data (passwords, keys, secrets)
❌ Detailed code snippets (use ADRs for that)
❌ Customer-specific information
❌ Unrelated personal notes

Writing Style

Be concise: Bullet points over paragraphs
Be specific: "Fixed login redirect bug" not "Fixed bug"
Include context: Link to issues, PRs, ADRs when relevant
Update incrementally: Add notes throughout the day, not just at the end

Integration with AI

When working with AI agents:

Reference current session: "See today's session file for context"
Update after AI work: Document what the AI helped accomplish
Link decisions: "Documented in 2026-03-25.md under Decisions Made"

Troubleshooting

Cannot Create Session File

Problem: Permission denied when creating session file

Error: Permission denied: .gears/sessions/2026-03-25.md

Solution: Check directory permissions:

chmod -R u+w .gears/sessions/

Wrong Date

Problem: Session file created with wrong date (timezone issue)

Solution: Session files use your system's local time. Check your system date:

# Unix/Mac
date

# Windows
echo %date%

# If wrong, update system timezone settings

File Not Syncing

Problem: Session files not appearing in mygears.dev after sync push

Solution:

Ensure you're authenticated: gears auth
Check file exists locally: ls .gears/sessions/
Try force push: gears sync push --force
Check mygears.dev file manager

Related Commands

gears init - Creates the sessions/ directory
gears sync push - Upload session files to cloud
gears sync pull - Download session files from cloud
gears story - Create feature specifications

Next Steps

After creating a session file:

Fill in Goals: Start your day by writing what you plan to accomplish
Update continuously: Add to the file as you work
Reference in commits: Link to session files in commit messages
Sync regularly: Run gears sync push to backup your sessions

← Command: auth | Command: story →