Scraps Multi-Agent Coordination

This skill enables AI coding assistants to safely collaborate on shared codebases using the scraps.sh git server's coordination primitives: Claim, Release, and Watch.

When to Use This Skill

Use this skill when:

• Multiple AI agents are working on the same repository simultaneously
• You need to edit files in a shared codebase and want to prevent conflicts
• You want to coordinate work with other agents on a team
• You need to monitor repository activity or wait for files to become available
• The codebase is hosted on scraps.sh

What is Scraps?

Scraps is a git hosting service with built-in coordination primitives for multi-agent development. The core commands are:

• scraps claim - Reserve file patterns before editing
• scraps release - Relinquish claims when done
• scraps watch - Monitor repository activity and claim changes in real-time

Prerequisites: Ensure you're authenticated before using scraps commands:

scraps login
scraps status  # Verify connection

How to Coordinate with Other Agents

Step 1: Claim Files Before Editing

Always claim the files you intend to modify before editing them.

scraps claim <store/repo:branch> <patterns...> -m "<description>"

Examples:

# Claim a specific file
scraps claim alice/webapp:main "src/components/Button.tsx" -m "Fixing button styling"

# Claim a directory
scraps claim alice/webapp:main "src/api/**" -m "Adding authentication endpoints"

# Claim multiple patterns
scraps claim alice/webapp:main "src/utils/**" "tests/utils/**" -m "Refactoring utility functions"

Options:

Option	Description
-m, --message <msg>	Describe your planned changes (required for coordination)
--ttl <seconds>	Claim duration (default: 300s / 5 minutes)
--agent-id <id>	Your identifier (auto-generated if omitted)

Important: Save the agent-id from your claim - you'll need it to release.

Step 2: Handle Claim Conflicts

If another agent has already claimed overlapping files, you'll receive a claim_conflict error showing which patterns conflict, which agent holds the claim, and their stated intent.

When you encounter a conflict:

1. Wait for the other agent to release their claim
2. Use scraps watch <store/repo:branch> --claims to monitor when files become available
3. Choose different files to work on
4. Coordinate with the other agent if possible

Step 3: Make Your Changes

Once your claim is successful:

1. Make your code changes
2. Commit and push using standard git commands
3. Release your claim

Step 4: Release When Done

Always release your claims after pushing changes or abandoning work.

scraps release <store/repo:branch> <patterns...> --agent-id <your-agent-id>

Example:

scraps release alice/webapp:main "src/api/**" --agent-id cli-abc12345

Monitoring Repository Activity

Watch for Commits and Branch Updates

scraps watch alice/webapp           # All branches
scraps watch alice/webapp -b main   # Specific branch

Watch for Claim Activity

Monitor when files become available or claimed:

scraps watch alice/webapp:main --claims

This streams events when agents claim or release files, helping you know when contested files become available.

Best Practices

Pull Before Claiming

git pull origin main
scraps claim myteam/project:main "src/**" -m "Adding feature X"

Use Small, Focused Claims

Claim only what you need. Broad claims like "**" block other agents unnecessarily.

Good:

scraps claim team/app:main "src/auth/login.ts" -m "Fixing login bug"

Avoid:

scraps claim team/app:main "src/**" -m "Fixing login bug"  # Too broad

Use Appropriate TTLs

If your task is quick, use a shorter TTL:

scraps claim team/app:main "README.md" -m "Updating docs" --ttl 60

Commit Frequently, Release Promptly

git add -A && git commit -m "Add login validation"
git push origin main
scraps release team/app:main "src/auth/**" --agent-id cli-abc123

Reference Formats

Format	Example	Usage
Store/Repo	alice/my-project	Repo operations, clone
Store/Repo:Branch	alice/my-project:main	Claims, releases, branch-specific watch
Store/Repo:Branch:Path	alice/my-project:main:src/index.ts	File read operations

Pattern Syntax

Claims use glob patterns:

Pattern	Matches
src/index.ts	Exact file
src/*.ts	All .ts files in src/
src/**	Everything under src/ recursively
**/*.test.ts	All test files anywhere
src/{api,utils}/**	Both api and utils directories

Command Reference

Claim

scraps claim <store/repo:branch> <patterns...> [options]
  -m, --message <msg>     Description of planned changes
  --agent-id <id>         Your agent identifier
  --ttl <seconds>         Claim duration (default: 300)

Release

scraps release <store/repo:branch> <patterns...> --agent-id <id>

Watch

scraps watch <store/repo[:branch]> [options]
  -b, --branch <branch>   Filter to specific branch
  --claims                Watch claim/release activity (requires branch)
  --last-event <id>       Resume from event ID

Clone

scraps clone <store/repo> [directory]
  --url-only              Print clone URL only

File Operations

scraps file read <store/repo:branch:path>    # Read file content
scraps file tree <store/repo:branch> [path]  # List directory
scraps log <store/repo:branch> [-n <count>]  # Commit history

Example Multi-Agent Session

Agent A (working on API):

scraps claim team/app:main "src/api/**" "tests/api/**" -m "Adding user endpoints"
# ... makes changes ...
git add -A && git commit -m "Add user CRUD endpoints"
git push origin main
scraps release team/app:main "src/api/**" "tests/api/**" --agent-id cli-aaa111

Agent B (working on UI, runs concurrently):

scraps claim team/app:main "src/components/**" -m "Building user profile component"
# ... makes changes ...
git add -A && git commit -m "Add UserProfile component"
git push origin main
scraps release team/app:main "src/components/**" --agent-id cli-bbb222

Agent C (wants API files, must wait):

scraps claim team/app:main "src/api/users.ts" -m "Fixing user validation"
# Error: claim_conflict - Agent cli-aaa111 has claimed src/api/**

# Watch for availability:
scraps watch team/app:main --claims
# ... waits for release event ...

# Try again after Agent A releases:
scraps claim team/app:main "src/api/users.ts" -m "Fixing user validation"
# Success!

Error Handling

Error	Meaning	Action
claim_conflict	Another agent holds conflicting claim	Wait, watch, or choose different files
not_found	Repo or branch doesn't exist	Verify the reference format
unauthorized	Not logged in or no access	Run scraps login or check permissions
release_failed	Agent ID doesn't match claim	Use the same agent-id from your claim

Summary

1. Always claim before editing - Prevents conflicts with other agents
2. Use specific patterns - Don't over-claim
3. Release promptly - Free files for others when done
4. Watch for availability - Monitor contested files
5. Pull before claiming - Start from latest code
6. Push before releasing - Ensure your changes are saved