Skip to content

Commit e31d5fe

Browse files
stevengonsalvezstevengonsalvez
committed
feat: add async agent spawning with git worktree isolation
Add /spawn-agent command: - Spawns agents (codex, aider, claude) in isolated tmux sessions - Git worktree support for parallel development - Optional handover document passing (--with-handover) - Isolated branches: agent/agent-{timestamp} - Session metadata tracking in ~/.claude/agents/ - Monitoring pane with real-time output Enhance /handover command: - Add --agent-spawn mode for passing context to agents - Two modes: standard (human) vs agent-spawn (task-focused) - Saves to both primary and backup locations - Programmatic timestamp generation Add git-worktree-utils.sh (claude-code-4.5/utils/ and claude-code/utils/): - create_agent_worktree: Creates isolated workspace - cleanup_agent_worktree: Removes worktree and branch - list_agent_worktrees: Shows all active worktrees - merge_agent_work: Integrates agent branch - CLI interface for manual management
1 parent c41f05f commit e31d5fe

File tree

6 files changed

+1018
-72
lines changed

6 files changed

+1018
-72
lines changed

‎claude-code-4.5/commands/handover.md‎

Lines changed: 164 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,187 @@
1-
# Handover Command
1+
# /handover - Generate Session Handover Document
22

3-
Use this command to generate a session handover document when transferring work to another team member or continuing work in a new session.
3+
Generate a handover document for transferring work to another developer or spawning an async agent.
44

55
## Usage
66

7-
```
8-
/handover [optional-notes]
7+
```bash
8+
/handover # Standard handover
9+
/handover "notes about current work" # With notes
10+
/handover --agent-spawn "task desc" # For spawning agent
911
```
1012

11-
## Description
13+
## Modes
1214

13-
This command generates a comprehensive handover document that includes:
15+
### Standard Handover (default)
1416

15-
- Current session health status
17+
For transferring work to another human or resuming later:
18+
- Current session health
1619
- Task progress and todos
17-
- Technical context and working files
18-
- Instructions for resuming work
19-
- Any blockers or important notes
20+
- Technical context
21+
- Resumption instructions
2022

21-
## Example
23+
### Agent Spawn Mode (`--agent-spawn`)
2224

25+
For passing context to spawned agents:
26+
- Focused on task context
27+
- Technical stack details
28+
- Success criteria
29+
- Files to modify
30+
31+
## Implementation
32+
33+
### Detect Mode
34+
35+
```bash
36+
MODE="standard"
37+
AGENT_TASK=""
38+
NOTES="${1:-}"
39+
40+
if [[ "$1" == "--agent-spawn" ]]; then
41+
MODE="agent"
42+
AGENT_TASK="${2:-}"
43+
shift 2
44+
fi
2345
```
24-
/handover Working on authentication refactor, need to complete OAuth integration
46+
47+
### Generate Timestamp
48+
49+
```bash
50+
TIMESTAMP=$(date +"%Y-%m-%d-%H-%M-%S")
51+
DISPLAY_TIME=$(date +"%Y-%m-%d %H:%M:%S")
52+
FILENAME="handover-${TIMESTAMP}.md"
53+
PRIMARY_LOCATION="${TOOL_DIR}/session/${FILENAME}"
54+
BACKUP_LOCATION="./${FILENAME}"
55+
56+
mkdir -p "${TOOL_DIR}/session"
2557
```
2658

27-
## Output Location
59+
### Standard Handover Content
60+
61+
```markdown
62+
# Handover Document
63+
64+
**Generated**: ${DISPLAY_TIME}
65+
**Session**: $(tmux display-message -p '#S' 2>/dev/null || echo 'unknown')
66+
67+
## Current Work
68+
69+
[Describe what you're working on]
70+
71+
## Task Progress
72+
73+
[List todos and completion status]
74+
75+
## Technical Context
76+
77+
**Current Branch**: $(git branch --show-current)
78+
**Last Commit**: $(git log -1 --oneline)
79+
**Modified Files**:
80+
$(git status --short)
81+
82+
## Resumption Instructions
83+
84+
1. Review changes: git diff
85+
2. Continue work on [specific task]
86+
3. Test with: [test command]
87+
88+
## Notes
89+
90+
${NOTES}
91+
```
92+
93+
### Agent Spawn Handover Content
94+
95+
```markdown
96+
# Agent Handover - ${AGENT_TASK}
97+
98+
**Generated**: ${DISPLAY_TIME}
99+
**Parent Session**: $(tmux display-message -p '#S' 2>/dev/null || echo 'unknown')
100+
**Agent Task**: ${AGENT_TASK}
101+
102+
## Context Summary
103+
104+
**Current Work**: [What's in progress]
105+
**Current Branch**: $(git branch --show-current)
106+
**Last Commit**: $(git log -1 --oneline)
107+
108+
## Task Details
109+
110+
**Agent Mission**: ${AGENT_TASK}
111+
112+
**Requirements**:
113+
- [List specific requirements]
114+
- [What needs to be done]
115+
116+
**Success Criteria**:
117+
- [How to know when done]
118+
119+
## Technical Context
120+
121+
**Stack**: [Technology stack]
122+
**Key Files**:
123+
$(git status --short)
124+
125+
**Modified Recently**:
126+
$(git log --name-only -5 --oneline)
28127

29-
The handover document MUST be saved to:
30-
- **Primary Location**: `.{{TOOL_DIR}}/session/handover-{{TIMESTAMP}}.md`
31-
- **Backup Location**: `./handover-{{TIMESTAMP}}.md` (project root)
128+
## Instructions for Agent
32129

33-
## File Naming Convention
130+
1. Review current implementation
131+
2. Make specified changes
132+
3. Add/update tests
133+
4. Verify all tests pass
134+
5. Commit with clear message
34135

35-
Use this format: `handover-YYYY-MM-DD-HH-MM-SS.md`
136+
## References
36137

37-
Example: `handover-2024-01-15-14-30-45.md`
138+
**Documentation**: [Links to relevant docs]
139+
**Related Work**: [Related PRs/issues]
140+
```
141+
142+
### Save Document
38143

39-
**CRITICAL**: Always obtain the timestamp programmatically:
40144
```bash
41-
# Generate timestamp - NEVER type dates manually
42-
TIMESTAMP=$(date +"%Y-%m-%d-%H-%M-%S")
43-
FILENAME="handover-${TIMESTAMP}.md"
145+
# Generate appropriate content based on MODE
146+
if [ "$MODE" = "agent" ]; then
147+
# Generate agent handover content
148+
CONTENT="[Agent handover content from above]"
149+
else
150+
# Generate standard handover content
151+
CONTENT="[Standard handover content from above]"
152+
fi
153+
154+
# Save to primary location
155+
echo "$CONTENT" > "$PRIMARY_LOCATION"
156+
157+
# Save backup
158+
echo "$CONTENT" > "$BACKUP_LOCATION"
159+
160+
echo "✅ Handover document generated"
161+
echo ""
162+
echo "Primary: $PRIMARY_LOCATION"
163+
echo "Backup: $BACKUP_LOCATION"
164+
echo ""
44165
```
45166

46-
## Implementation
167+
## Output Location
168+
169+
**Primary**: `${TOOL_DIR}/session/handover-{timestamp}.md`
170+
**Backup**: `./handover-{timestamp}.md`
171+
172+
## Integration with spawn-agent
173+
174+
The `/spawn-agent` command automatically calls `/handover --agent-spawn` when `--with-handover` flag is used:
175+
176+
```bash
177+
/spawn-agent codex "refactor auth" --with-handover
178+
# Internally calls: /handover --agent-spawn "refactor auth"
179+
# Copies handover to agent worktree as .agent-handover.md
180+
```
181+
182+
## Notes
47183

48-
1. **ALWAYS** get the current timestamp using `date` command:
49-
```bash
50-
date +"%Y-%m-%d %H:%M:%S" # For document header
51-
date +"%Y-%m-%d-%H-%M-%S" # For filename
52-
```
53-
2. Generate handover using `{{HOME_TOOL_DIR}}/templates/handover-template.md`
54-
3. Replace all `{{VARIABLE}}` placeholders with actual values
55-
4. Save to BOTH locations (primary and backup)
56-
5. Display the full file path to the user for reference
57-
6. Verify the date in the filename matches the date in the document header
58-
59-
The handover document will be saved as a markdown file and can be used to seamlessly continue work in a new session.
184+
- Always uses programmatic timestamps (never manual)
185+
- Saves to both primary and backup locations
186+
- Agent mode focuses on task context, not session health
187+
- Standard mode includes full session state

0 commit comments

Comments
 (0)