@hasna/skills 0.0.2

package/skills/skill-e2bswarm/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: skill-e2bswarm
+description: Spawn and manage E2B sandbox instances for parallel Claude Code task execution. Use when you need to run multiple tasks in parallel across isolated environments, distribute work across sandboxes, or execute tasks in clean environments.
+disable-model-invocation: true
+allowed-tools: Bash(bun:*), Bash(e2b:*), Read, Write
+---
+
+# E2B Swarm
+
+Spawn E2B sandbox instances in parallel to execute Claude Code tasks across isolated environments.
+
+## Installation
+
+```bash
+cd ~/.claude/skills/skill-e2bswarm && bun install
+```
+
+Or link from the repo:
+```bash
+ln -s ~/Workspace/dev/hasnaxyz/skill/skilldev/skill-e2bswarm ~/.claude/skills/skill-e2bswarm
+```
+
+## Commands
+
+### Spawn instances with tasks
+
+From a task list ID (loads from ~/.claude/tasks/<id>/):
+```bash
+skill-e2bswarm spawn \
+  --repo <github-url> \
+  --tasks <task-list-id> \
+  --instances <count>
+```
+
+From a local folder containing task JSON files:
+```bash
+skill-e2bswarm spawn \
+  --repo <github-url> \
+  --tasks-dir ./my-tasks/ \
+  --instances <count>
+```
+
+From inline JSON:
+```bash
+skill-e2bswarm spawn \
+  --repo <github-url> \
+  --tasks-json '[{"id":"1","subject":"Task 1","description":"Do something"}]' \
+  --instances <count>
+```
+
+From a JSON file:
+```bash
+skill-e2bswarm spawn \
+  --repo <github-url> \
+  --tasks-file ./tasks.json \
+  --instances <count>
+```
+
+### Check status
+```bash
+skill-e2bswarm status
+skill-e2bswarm status --instance <id>
+```
+
+### Collect results
+```bash
+skill-e2bswarm collect --output ./results
+```
+
+### Kill instances
+```bash
+skill-e2bswarm kill              # Kill all
+skill-e2bswarm kill --instance <id>  # Kill specific
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--repo, -r` | Git repository URL (required) |
+| `--tasks, -t` | Task list ID from ~/.claude/tasks/ |
+| `--tasks-dir` | Local folder containing task JSON files |
+| `--tasks-file` | Path to a JSON file with tasks array |
+| `--tasks-json` | Inline JSON array of tasks |
+| `--instances, -n` | Number of parallel instances (default: 1) |
+| `--prompt, -p` | Additional context/instructions for Claude |
+| `--branch, -b` | Git branch to clone |
+| `--distribute, -d` | Task distribution mode: all, round-robin, by-dependency |
+
+## Task Distribution Modes
+
+- **all**: Each instance receives all tasks (default)
+- **round-robin**: Tasks distributed evenly across instances
+- **by-dependency**: Tasks grouped by dependency chains
+
+## Environment Variables
+
+- `E2B_API_KEY`: Your E2B API key (required, add to ~/.secrets)
+
+## Examples
+
+Spawn 4 instances to work on videoben tasks in parallel:
+```bash
+skill-e2bswarm spawn \
+  --repo git@github.com:hasnastudio/iapp-videoben.git \
+  --tasks iapp-videoben-dev \
+  --instances 4 \
+  --distribute round-robin \
+  --prompt "Complete all assigned tasks, run tests before marking complete"
+```
+
+Run tasks from a local JSON file:
+```bash
+skill-e2bswarm spawn \
+  --repo git@github.com:org/repo.git \
+  --tasks-file ./sprint-tasks.json \
+  --instances 2
+```

package/skills/skill-e2bswarm/examples/tasks-example.json

@@ -0,0 +1,38 @@
+[
+  {
+    "id": "1",
+    "subject": "Setup project structure",
+    "description": "Create the basic project structure with src/, tests/, and config files.\n\n**Files to create:**\n- src/index.ts\n- tests/index.test.ts\n- tsconfig.json\n\n**Acceptance criteria:**\n- All files exist\n- TypeScript compiles without errors",
+    "activeForm": "Setting up project structure",
+    "status": "pending",
+    "blocks": ["2", "3"],
+    "blockedBy": []
+  },
+  {
+    "id": "2",
+    "subject": "Implement core functionality",
+    "description": "Implement the main feature in src/index.ts.\n\n**Requirements:**\n- Export a main function\n- Handle errors gracefully\n- Add logging\n\n**Acceptance criteria:**\n- Function works as expected\n- Errors are caught and logged",
+    "activeForm": "Implementing core functionality",
+    "status": "pending",
+    "blocks": ["4"],
+    "blockedBy": ["1"]
+  },
+  {
+    "id": "3",
+    "subject": "Write unit tests",
+    "description": "Write comprehensive unit tests for the core functionality.\n\n**Test cases:**\n- Happy path\n- Error handling\n- Edge cases\n\n**Acceptance criteria:**\n- All tests pass\n- Coverage > 80%",
+    "activeForm": "Writing unit tests",
+    "status": "pending",
+    "blocks": ["4"],
+    "blockedBy": ["1"]
+  },
+  {
+    "id": "4",
+    "subject": "Add documentation",
+    "description": "Add README and inline documentation.\n\n**Documentation:**\n- README.md with usage examples\n- JSDoc comments on exported functions\n\n**Acceptance criteria:**\n- README is clear and complete\n- All exports have documentation",
+    "activeForm": "Adding documentation",
+    "status": "pending",
+    "blocks": [],
+    "blockedBy": ["2", "3"]
+  }
+]

package/skills/skill-e2bswarm/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hasnaxyz/skill-e2bswarm",
+  "version": "0.4.1",
+  "description": "Spawn E2B sandbox instances for parallel Claude Code task execution",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "skill-e2bswarm": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "SKILL.md",
+    "README.md",
+    "templates",
+    "examples"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch src/index.ts",
+    "build": "bun build src/index.ts --outdir dist --target bun --minify && chmod +x dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "link": "ln -sf $(pwd) ~/.claude/skills/skill-e2bswarm",
+    "link:global": "bun link"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "e2b": "^1.0.5",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "e2b",
+    "claude-code",
+    "claude",
+    "sandbox",
+    "parallel-execution",
+    "task-runner",
+    "ai-agent",
+    "swarm"
+  ],
+  "author": "hasnaxyz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hasnaxyz/skill-e2bswarm.git"
+  },
+  "homepage": "https://github.com/hasnaxyz/skill-e2bswarm#readme",
+  "bugs": {
+    "url": "https://github.com/hasnaxyz/skill-e2bswarm/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "restricted"
+  }
+}

package/skills/skill-e2bswarm/src/commands/collect.ts

@@ -0,0 +1,135 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import ora from 'ora';
+import { E2BSwarm } from '../lib/e2b';
+import { loadConfig, loadState } from '../lib/config';
+import { logger } from '../lib/logger';
+import { paths } from '../lib/paths';
+import type { CollectOptions } from '../types';
+
+export async function collect(options: CollectOptions) {
+  const spinner = ora('Loading state...').start();
+
+  try {
+    const config = await loadConfig();
+    const state = await loadState();
+
+    if (state.instances.length === 0) {
+      spinner.fail('No instances found');
+      return;
+    }
+
+    const swarm = new E2BSwarm(config);
+
+    // Filter instances
+    const instances = options.instance
+      ? state.instances.filter(i => i.id.startsWith(options.instance!))
+      : state.instances.filter(i => i.status === 'completed' || i.status === 'running');
+
+    if (instances.length === 0) {
+      spinner.fail('No completed instances to collect from');
+      logger.info('Use `skill-e2bswarm status` to check instance status');
+      return;
+    }
+
+    spinner.text = `Found ${instances.length} instances to collect from`;
+
+    // Use provided output dir or default to skill exports directory
+    const outputDir = options.output || paths.getExportDir('collect');
+    await mkdir(outputDir, { recursive: true });
+    spinner.succeed(`Output directory: ${outputDir}`);
+
+    logger.header('Collecting Results');
+
+    const results: Array<{
+      instanceId: string;
+      status: string;
+      tasks: number;
+      completed: number;
+      outputFile: string;
+    }> = [];
+
+    for (const instance of instances) {
+      const shortId = instance.id.slice(0, 8);
+      spinner.start(`[${shortId}] Collecting...`);
+
+      try {
+        if (instance.status === 'running') {
+          // Update status first
+          const updated = await swarm.checkInstance(instance);
+          Object.assign(instance, updated);
+        }
+
+        if (instance.sandboxId) {
+          const collected = await swarm.collectResults(instance);
+
+          // Write results to file
+          const outputFile = join(outputDir, `${shortId}-results.json`);
+          const resultData = {
+            instanceId: instance.id,
+            sandboxId: instance.sandboxId,
+            template: instance.template,
+            source: instance.source,
+            sourceType: instance.sourceType,
+            status: instance.status,
+            startedAt: instance.startedAt,
+            completedAt: instance.completedAt,
+            duration: instance.completedAt
+              ? new Date(instance.completedAt).getTime() - new Date(instance.startedAt).getTime()
+              : null,
+            tasks: collected.tasks,
+            output: collected.output,
+            logs: collected.logs,
+          };
+
+          await Bun.write(outputFile, JSON.stringify(resultData, null, 2));
+
+          // Also copy to instance export dir if it exists
+          if (instance.exportDir) {
+            await mkdir(instance.exportDir, { recursive: true });
+            await Bun.write(join(instance.exportDir, 'results.json'), JSON.stringify(resultData, null, 2));
+          }
+
+          const completedTasks = collected.tasks.filter(t => t.status === 'completed').length;
+          results.push({
+            instanceId: shortId,
+            status: instance.status,
+            tasks: collected.tasks.length,
+            completed: completedTasks,
+            outputFile,
+          });
+
+          spinner.succeed(`[${shortId}] Collected ${completedTasks}/${collected.tasks.length} tasks`);
+        } else {
+          spinner.warn(`[${shortId}] No sandbox ID, skipping`);
+        }
+      } catch (error) {
+        spinner.warn(`[${shortId}] Failed: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+
+    // Write summary
+    const summaryFile = join(outputDir, 'summary.json');
+    const summary = {
+      collectedAt: new Date().toISOString(),
+      outputDir,
+      totalInstances: results.length,
+      totalTasks: results.reduce((sum, r) => sum + r.tasks, 0),
+      completedTasks: results.reduce((sum, r) => sum + r.completed, 0),
+      instances: results,
+    };
+
+    await Bun.write(summaryFile, JSON.stringify(summary, null, 2));
+
+    logger.header('Summary');
+    logger.info(`Instances collected: ${results.length}`);
+    logger.info(`Total tasks: ${summary.totalTasks}`);
+    logger.info(`Completed tasks: ${summary.completedTasks}`);
+    logger.info(`Results saved to: ${outputDir}`);
+
+  } catch (error) {
+    spinner.fail('Failed');
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/skills/skill-e2bswarm/src/commands/install.ts

@@ -0,0 +1,164 @@
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { logger } from '../lib/logger';
+
+type Platform = 'claude' | 'codex';
+
+function getSkillsDir(platform: Platform, local: boolean): string {
+  if (local) {
+    return platform === 'claude' ? '.claude/skills' : '.codex/skills';
+  }
+  const home = homedir();
+  return platform === 'claude'
+    ? join(home, '.claude', 'skills')
+    : join(home, '.codex', 'skills');
+}
+
+async function ensureDir(dir: string): Promise<void> {
+  await mkdir(dir, { recursive: true });
+}
+
+async function getSkillMdContent(): Promise<string> {
+  // Try to read from the package's SKILL.md first
+  const possiblePaths = [
+    join(__dirname, '..', '..', 'SKILL.md'),
+    join(__dirname, '..', '..', '..', 'SKILL.md'),
+    join(process.cwd(), 'SKILL.md'),
+  ];
+
+  for (const path of possiblePaths) {
+    try {
+      return await readFile(path, 'utf-8');
+    } catch {
+      // Try next path
+    }
+  }
+
+  // Fallback to embedded content
+  return `---
+name: skill-e2bswarm
+description: Spawn and manage E2B sandbox instances for parallel Claude Code task execution. Use when you need to run multiple tasks in parallel across isolated environments, distribute work across sandboxes, or execute tasks in clean environments.
+disable-model-invocation: true
+allowed-tools: Bash(bun:*), Bash(e2b:*), Read, Write
+---
+
+# E2B Swarm
+
+Spawn E2B sandbox instances in parallel to execute Claude Code tasks across isolated environments.
+
+## CLI Usage
+
+\`\`\`bash
+# Spawn instances with tasks from a task list
+skill-e2bswarm spawn --repo <github-url> --tasks <task-list-id> --instances <count>
+
+# Spawn from a local directory
+skill-e2bswarm spawn --local ./my-project --tasks <task-list-id> --instances 3
+
+# Check status
+skill-e2bswarm status
+
+# Collect results
+skill-e2bswarm collect --output ./results
+
+# Kill instances
+skill-e2bswarm kill
+\`\`\`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| \`spawn\` | Spawn E2B instances with tasks |
+| \`status\` | Check instance status |
+| \`collect\` | Collect results from instances |
+| \`kill\` | Kill running instances |
+| \`sync\` | Sync changes back to GitHub |
+| \`clean\` | Clean up state file |
+| \`info\` | Show skill data directory paths |
+
+## Options (spawn)
+
+| Option | Description |
+|--------|-------------|
+| \`-r, --repo <url>\` | Git repository URL to clone |
+| \`-l, --local <path>\` | Local directory to upload |
+| \`-t, --tasks <id>\` | Task list ID from ~/.claude/tasks/ |
+| \`-n, --instances <count>\` | Number of parallel instances |
+| \`-d, --distribute <mode>\` | Distribution: all, round-robin, by-dependency |
+| \`--auto-commit\` | Auto commit changes |
+| \`--auto-push\` | Auto push changes |
+| \`--create-pr\` | Create pull request |
+
+## Data Directories
+
+- **exports/** - Collected results and artifacts
+- **logs/** - Execution logs
+- **cache/** - Temporary data
+- **config/** - Skill configuration
+
+## Requirements
+
+- \`E2B_API_KEY\` in \`~/.secrets\` - Required for E2B sandboxes
+- Bun runtime with \`skill-e2bswarm\` installed globally
+
+## Install CLI
+
+\`\`\`bash
+bun add -g @hasnaxyz/skill-e2bswarm
+\`\`\`
+`;
+}
+
+export async function install(options: {
+  claude?: boolean;
+  codex?: boolean;
+  local?: boolean;
+}): Promise<void> {
+  if (!options.claude && !options.codex) {
+    logger.error('Please specify --claude or --codex');
+    process.exit(1);
+  }
+
+  const skillName = 'skill-e2bswarm';
+  const platforms: Platform[] = [];
+  if (options.claude) platforms.push('claude');
+  if (options.codex) platforms.push('codex');
+
+  const skillMdContent = await getSkillMdContent();
+
+  for (const platform of platforms) {
+    const baseDir = getSkillsDir(platform, options.local || false);
+    const skillDir = join(baseDir, skillName);
+
+    logger.info(`Installing skill to ${platform === 'claude' ? 'Claude Code' : 'Codex'}...`);
+
+    try {
+      // Create skill directory structure
+      await ensureDir(skillDir);
+      await ensureDir(join(skillDir, 'exports'));
+      await ensureDir(join(skillDir, 'uploads'));
+      await ensureDir(join(skillDir, 'logs'));
+
+      // Write SKILL.md
+      const skillMdPath = join(skillDir, 'SKILL.md');
+      await writeFile(skillMdPath, skillMdContent, 'utf-8');
+
+      logger.success(`Installed to ${skillDir}`);
+
+      console.log();
+      console.log('Created structure:');
+      console.log(`  ${skillDir}/`);
+      console.log('  ├── SKILL.md');
+      console.log('  ├── exports/');
+      console.log('  ├── uploads/');
+      console.log('  └── logs/');
+      console.log();
+      console.log(`Invoke with: /${skillName}`);
+    } catch (error) {
+      logger.error(`Install failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+      process.exit(1);
+    }
+  }
+}

package/skills/skill-e2bswarm/src/commands/kill.ts

@@ -0,0 +1,62 @@
+import ora from 'ora';
+import { E2BSwarm } from '../lib/e2b';
+import { loadConfig, loadState, saveState } from '../lib/config';
+import { logger } from '../lib/logger';
+import type { KillOptions } from '../types';
+
+export async function kill(options: KillOptions) {
+  const spinner = ora('Loading state...').start();
+
+  try {
+    const config = await loadConfig();
+    const state = await loadState();
+
+    if (state.instances.length === 0) {
+      spinner.info('No instances found');
+      return;
+    }
+
+    const swarm = new E2BSwarm(config);
+
+    // Filter instances to kill
+    let instances = state.instances.filter(
+      i => i.status === 'running' || i.status === 'starting' || i.status === 'setting-up' || i.status === 'cloning'
+    );
+
+    if (options.instance) {
+      instances = instances.filter(i => i.id.startsWith(options.instance!));
+    }
+
+    if (instances.length === 0) {
+      spinner.info('No running instances to kill');
+      return;
+    }
+
+    spinner.succeed(`Found ${instances.length} instances to kill`);
+
+    logger.header('Killing Instances');
+
+    for (const instance of instances) {
+      const shortId = instance.id.slice(0, 8);
+      spinner.start(`[${shortId}] Killing...`);
+
+      try {
+        await swarm.kill(instance);
+        spinner.succeed(`[${shortId}] Killed`);
+      } catch (error) {
+        spinner.warn(`[${shortId}] Failed: ${error instanceof Error ? error.message : error}`);
+      }
+    }
+
+    // Update state
+    await saveState(state);
+
+    logger.header('Summary');
+    logger.info(`Killed ${instances.length} instances`);
+
+  } catch (error) {
+    spinner.fail('Failed');
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}