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"

Agent Action:

Launch 5 parallel sessions

./.claude/commands/claude-code-x.sh exec "Add logging to crates/miyabi-auth/src/lib.rs" ./.claude/commands/claude-code-x.sh exec "Add logging to crates/miyabi-database/src/lib.rs" ./.claude/commands/claude-code-x.sh exec "Add logging to crates/miyabi-api/src/lib.rs" ./.claude/commands/claude-code-x.sh exec "Add logging to crates/miyabi-cache/src/lib.rs" ./.claude/commands/claude-code-x.sh exec "Add logging to crates/miyabi-worker/src/lib.rs"

Agent Response:

✅ Started 5 parallel Claude Code X sessions:

1. claude-code-x-20251027-100000-abc123 (auth)
2. claude-code-x-20251027-100015-def456 (database)
3. claude-code-x-20251027-100030-ghi789 (api)
4. claude-code-x-20251027-100045-jkl012 (cache)
5. claude-code-x-20251027-100100-mno345 (worker)

Estimated completion: ~5 minutes I'll monitor progress and report when all complete.

Example 3: Phased Hybrid

User Request: "Implement OAuth 2.0 authentication"

Agent Action (Pattern 3: Hybrid Orchestration):

Phase 1: Planning (Interactive)

• Breaking down OAuth into discrete tasks...

Phase 2: Infrastructure (Claude Code X - Parallel)

• Spawning 3 sessions for config, DB, Redis...

Phase 3: Core Flow (Interactive)

• Implementing security-critical OAuth flow interactively...

Phase 4: Providers (Claude Code X - Parallel)

• Spawning 3 sessions for Google, GitHub, Discord providers...

Phase 5: Testing (Interactive)

• Reviewing all code and creating integration tests...

Result: 42 minutes (30% faster than all-interactive)

🔗 Related Documentation

• Implementation: CLAUDE_CODE_X_IMPLEMENTATION_GUIDE.md

• Workflow: OPTIMAL_MIYABI_WORKFLOW_WITH_CODEX_CLAUDE.md

• Pattern 3 Example: PATTERN3_HYBRID_EXAMPLE.md

• Command Reference: .claude/commands/claude-code-x.md

🐛 Troubleshooting

Session Won't Start

Error: Maximum concurrent sessions (5) reached

Solution:

List active sessions

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

Kill inactive sessions or wait for completion

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

Or cleanup old sessions

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

Session Timeout

Error: Session times out before completion

Solution:

Increase timeout for complex tasks

./.claude/commands/claude-code-x.sh exec "Complex task" --timeout 1200

Session Fails

Check logs:

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

Common issues:

• Missing files → Add file creation to task description

• Dependency errors → Ensure dependencies are available

• Unclear task → Make task description more specific

📊 Success Metrics

Track these metrics to evaluate Claude Code X effectiveness:

• Time Savings: Compare total execution time vs sequential

• Success Rate: Percentage of sessions completing successfully

• Parallelization Factor: Average concurrent sessions used

• Task Clarity: Percentage requiring clarification before execution

Target Metrics:

• Time Savings: >25%

• Success Rate: >90%

• Parallelization: 3-5 concurrent sessions

• Task Clarity: <10% requiring clarification

Version: 1.0.0 Created: 2025-10-27 Author: Claude Code (Sonnet 4.5) Status: ✅ Production Ready