Workspace Git Foundation - User Guide

What is a Workspace?

A Workspace in Refresh Agents is an isolated Git environment that allows you to work on multiple features simultaneously without conflicts. Each workspace has its own:

• Dedicated Git branch - Your feature branch isolated from main
• Separate worktree - Physical directory isolation
• Independent state - Branch status, PR tracking, conflict management
• Auto-recovery - Automatic restoration if the workspace is missing

Why Use Workspaces?

Traditional Git Workflow Problems

# Problem: Switching branches loses uncommitted work
git checkout main
# Error: Your local changes would be overwritten

# Problem: Stashing is tedious
git stash
git checkout main
# ... do something
git checkout feature-branch
git stash pop

Workspace Solution

# ✅ Each workspace is independent
Workspace A: feature/authentication (uncommitted changes preserved)
Workspace B: feature/dashboard (working in parallel)
Workspace C: bugfix/login-error (hotfix without context switching)

Quick Start

Step 1: Create a New Chat

1. Open Refresh Agents
2. Click "New Chat" in the sidebar
3. Select your project folder

Step 2: Workspace Auto-Creation

When you create a chat, Refresh automatically:

1. ✅ Creates a workspace record
2. ✅ Generates a unique branch name (e.g., feature/chat-abc123)
3. ✅ Creates a Git worktree in .worktrees/ directory
4. ✅ Sets up the target branch (default: main)

Step 3: Start Coding

Your workspace is ready! You can now:

• ✅ Make changes without affecting other workspaces
• ✅ Commit and push independently
• ✅ Create pull requests
• ✅ Resolve conflicts in isolation

Workspace Status Bar

At the top of your chat, you'll see the workspace status:

┌─────────────────────────────────────────────────┐
│ 🌿 feature/chat-abc123  │  ↑2 ↓1 ●3  │  PR #42 │
└─────────────────────────────────────────────────┘

• 🌿 Branch name - Your current feature branch
• ↑2 - 2 commits ahead of target branch
• ↓1 - 1 commit behind target branch
• ●3 - 3 uncommitted changes
• PR #42 - Associated pull request

Key Features

Automatic Recommendations

The workspace automatically suggests the next action:

• Uncommitted changes? → "Commit Changes"
• Ahead of remote? → "Push to Remote"
• Behind target branch? → "Sync with Remote"
• Ready for PR? → "Create Pull Request"

Multi-Repo Support

A workspace can contain multiple repositories:

Workspace A
├─ Repo: frontend (feature/new-ui)
├─ Repo: backend (feature/new-api)
└─ Repo: shared (feature/types)

Automatic Cleanup

Workspaces are automatically garbage collected after 72 hours of inactivity:

• Active workspaces: Kept indefinitely
• Pinned workspaces: Kept for 7 days
• Archived workspaces: Cleaned up after 1 hour

Next Steps

• Managing Git Branches - Learn how to sync, push, and pull
• Resolving Conflicts - Step-by-step conflict resolution
• Creating Pull Requests - Auto-generate PRs with smart descriptions
• Troubleshooting - Common issues and solutions

Getting Help

• Documentation: https://refresh-agents.com/docs
• Discord: https://discord.gg/refresh-agents
• Email: [email protected]