name	Claude Code X - Autonomous Execution Subagent
description	Execute Claude Code autonomously in the background for well-defined tasks, enabling parallel execution of up to 5 concurrent sessions while the user continues other work.
allowed-tools	Bash, Task, Edit, Read, Write, Grep, Glob

Claude Code X - Autonomous Execution Subagent

Type: Task Execution Agent Mode: Background Autonomous Version: 1.0.0

🎯 Purpose

Execute Claude Code autonomously in the background for well-defined tasks, enabling parallel execution of up to 5 concurrent sessions while the user continues other work.

🚀 When to Use This Skill

✅ Use When:

You have 3+ independent, well-defined tasks
Tasks don't require user interaction during execution
You want to maximize throughput with parallel execution
User can benefit from multitasking during execution
Tasks follow clear patterns (e.g., similar Issues)

❌ Don't Use When:

Task requires user decisions during execution
Requirements are unclear or exploratory
Task has complex dependencies on other running tasks
Immediate interactive feedback is needed

📋 Capabilities

Core Features

Parallel Execution: Run up to 5 Claude Code sessions concurrently
Session Management: JSON-based persistence and lifecycle tracking
Background Operation: Non-blocking, allows user to continue other work
Timeout Control: Configurable timeout (default 10 minutes)
Result Retrieval: Access full output logs after completion
Session Monitoring: Check status and progress in real-time

Session Lifecycle

Spawn: Create new background Claude Code session
Execute: Run task autonomously with specified tools
Monitor: Check status and output
Complete: Retrieve results and clean up

🛠️ Usage

Basic Execution

Please use the Claude Code X skill to execute the following task in the background:

"Implement logging for the authentication module in crates/miyabi-auth/src/lib.rs"

Parallel Batch Execution

Use Claude Code X to execute these 5 tasks in parallel:

1. Add logging to crates/miyabi-auth/src/lib.rs
2. Add logging to crates/miyabi-database/src/lib.rs
3. Add logging to crates/miyabi-api/src/lib.rs
4. Add logging to crates/miyabi-cache/src/lib.rs
5. Add logging to crates/miyabi-worker/src/lib.rs

Monitor their progress and report when all are complete.

With Custom Configuration

Use Claude Code X with:
- Timeout: 15 minutes
- Tools: Bash, Read, Write, Edit, Grep
- Task: "Refactor error handling in crates/miyabi-core/src/errors.rs"

🎬 Implementation Instructions

When this skill is invoked, execute the following steps:

Step 1: Validate Task

Check that the task is:

Well-defined with clear success criteria
Independent (no dependencies on user input)
Suitable for autonomous execution

If unclear, ask user for clarification before proceeding.

Step 2: Execute with Shell Script

Use the claude-code-x.sh shell script:

# Execute task
./.claude/commands/claude-code-x.sh exec "Task description here"

# Optional: Custom configuration
./.claude/commands/claude-code-x.sh exec "Task description" \
  --timeout 900 \
  --tools "Bash,Read,Write,Edit,Glob,Grep"

Step 3: Capture Session ID

The script will output:

✅ Session started successfully
🔗 Session ID: claude-code-x-20251027-123456-abc123
🔗 PID: 12345

Store this session ID for monitoring.

Step 4: Monitor Progress (Optional)

During execution, you can check status:

# Check status
./.claude/commands/claude-code-x.sh status claude-code-x-20251027-123456-abc123

# List all sessions
./.claude/commands/claude-code-x.sh sessions

Step 5: Retrieve Results

After completion, get full output:

./.claude/commands/claude-code-x.sh result claude-code-x-20251027-123456-abc123

Step 6: Report to User

Provide summary:

Session ID
Execution time
Exit code (0 = success)
Files modified
Any issues encountered

📊 Best Practices

Task Breakdown

Good Task:
"Add comprehensive logging to crates/miyabi-auth/src/lib.rs:
- Log all function entries/exits
- Log all errors with context
- Use tracing::info!, tracing::error!
- Include test coverage"

Bad Task:
"Fix the auth module" (too vague)
"Implement OAuth" (needs user decisions)

Parallel Execution Strategy

Pattern 1: Similar Tasks (Ideal)

Task 1: Add logging to module A
Task 2: Add logging to module B  
Task 3: Add logging to module C
Task 4: Add logging to module D
Task 5: Add logging to module E

→ All 5 tasks in parallel (max efficiency)

Pattern 2: Phased Execution (Good)

Phase 1 (parallel): Infrastructure setup tasks
  - Task 1: Create config struct
  - Task 2: Add database schema
  - Task 3: Implement Redis cache

Phase 2 (interactive): Critical logic (use regular Claude Code)

Phase 3 (parallel): Provider implementations
  - Task 4: Google provider
  - Task 5: GitHub provider
  - Task 6: Discord provider

Error Handling

If a session fails:

Check the log file for error details
Determine if it's retryable
Fix any issues (e.g., missing files)
Re-execute with corrected task description

🔍 Session Management Commands

List Active Sessions

./.claude/commands/claude-code-x.sh sessions

Check Session Status

./.claude/commands/claude-code-x.sh status <session-id>

Get Full Results

./.claude/commands/claude-code-x.sh result <session-id>

Kill Running Session

./.claude/commands/claude-code-x.sh kill <session-id>

Cleanup Old Sessions

./.claude/commands/claude-code-x.sh cleanup

⚙️ Configuration

Environment Variables

# Session directory (default: .ai/sessions/claude-code-x)
export CLAUDE_CODE_X_SESSION_DIR=".ai/sessions/claude-code-x"

# Log directory (default: $SESSION_DIR/logs)
export CLAUDE_CODE_X_LOG_DIR="$SESSION_DIR/logs"

# Max concurrent sessions (default: 5)
export CLAUDE_CODE_X_MAX_SESSIONS=5

# Default timeout in seconds (default: 600 = 10 minutes)
export CLAUDE_CODE_X_TIMEOUT=600

Default Tools

The following tools are enabled by default:

Bash (command execution)
Read (file reading)
Write (file writing)
Edit (file editing)
Glob (file pattern matching)
Grep (content search)

Permission Mode

Default: acceptEdits (auto-accept file edits)
Can be changed to ask for approval prompts

📈 Performance Characteristics

Speed

Overhead: ~2-3 seconds per session spawn
Execution: Similar to interactive Claude Code
Parallel: Up to 5x throughput with 5 concurrent sessions

Resource Usage

Memory: ~200MB per session
Disk: ~1MB per session log
CPU: Minimal (most time spent in AI inference)

Limits

Max Sessions: 5 concurrent (configurable)
Max Timeout: 10 minutes default (configurable up to 30 min)
Log Retention: Logs persist until manual cleanup

🎓 Examples

Example 1: Single Task

User Request: "Add logging to the auth module"

Agent Action:

./.claude/commands/claude-code-x.sh exec \
  "Add comprehensive logging to crates/miyabi-auth/src/lib.rs:
  - Log all function entries/exits with tracing::info!
  - Log all errors with tracing::error!
  - Include request IDs in log context
  - Add tests for logging behavior"

Agent Response:

✅ Started Claude Code X session: claude-code-x-20251027-100000-abc123
📝 Executing task in background (timeout: 10 minutes)
💡 Monitor with: /claude-code-x status claude-code-x-20251027-100000-abc123

I'll check back in 2 minutes to see progress.

Example 2: Parallel Batch

User Request: "Add logging to all 5 core modules"