@saeed42/worktree-worker

Git worktree management service for AI agent trials. Runs as an npm package in CodeSandbox or any Node.js environment.

Security

GitHub tokens are NEVER persisted to disk. All authenticated operations require the token to be passed in the request body. This is critical for sandbox environments where credentials should not be stored.

Installation

# Install globally
npm install -g @saeed42/worktree-worker

# Or add to your project
npm install @saeed42/worktree-worker

Quick Start

Run as CLI

# Set environment variables
export WORKER_TOKEN=your-secret-token
export PORT=8787

# Run the service
worktree-worker

Run in CodeSandbox

Add to your package.json:

{
  "dependencies": {
    "@saeed42/worktree-worker": "^1.0.0"
  },
  "scripts": {
    "worktree-worker": "worktree-worker"
  }
}

Or run directly:

npx @saeed42/worktree-worker

Run Programmatically

import { app } from '@saeed42/worktree-worker';

// The app is a Hono instance
// You can extend it or use it as middleware

Architecture

/project/
├── sandbox/              # BASE_WORKSPACE_DIR - Main repo clone
└── workspaces/
    └── trials/           # TRIALS_WORKSPACE_DIR - Worktrees
        ├── feature-auth-a1b2c3d4/
        ├── fix-bug-xyz-5e6f7g8h/
        └── ...

API Endpoints

Health Checks

| Endpoint | Description | |----------|-------------| | GET /health | Basic health check | | GET /health/ready | Readiness check | | GET /health/live | Liveness check |

Repository Management

| Endpoint | Description | |----------|-------------| | POST /v1/repo/init | Clone repository | | POST /v1/repo/update | Fetch/pull latest | | GET /v1/repo/status | Get repo status | | GET /v1/repo/branches | List branches |

Worktree Management

| Endpoint | Description | |----------|-------------| | POST /v1/trials/:trialId/worktree/reset | Create/reset worktree | | DELETE /v1/trials/:trialId/worktree | Delete worktree | | GET /v1/trials/:trialId/worktree/status | Get status | | GET /v1/trials/:trialId/worktree/diff | Get diff | | POST /v1/trials/:trialId/worktree/commit | Commit changes | | POST /v1/trials/:trialId/worktree/push | Push to remote |

Configuration

| Variable | Default | Description | |----------|---------|-------------| | PORT | 8787 | HTTP server port | | NODE_ENV | development | Environment mode | | WORKER_TOKEN | `` | Auth token (empty = no auth) | | BASE_WORKSPACE_DIR | /project/sandbox | Main repo path | | TRIALS_WORKSPACE_DIR | /project/workspaces/trials | Worktrees path | | DEFAULT_BRANCH | main | Default base branch | | GIT_TIMEOUT_MS | 60000 | Git timeout | | CLEANUP_AFTER_HOURS | 24 | Stale worktree cleanup |

Usage Examples

Initialize Repository

curl -X POST http://localhost:8787/v1/repo/init \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/owner/repo",
    "branch": "main",
    "githubToken": "ghp_xxx"
  }'

Create Worktree

curl -X POST http://localhost:8787/v1/trials/abc123/worktree/reset \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "baseBranch": "main",
    "trialBranch": "feature/my-feature",
    "githubToken": "ghp_xxx"
  }'

Note: githubToken is required for private repositories. The token is used inline and never stored on disk.

Response:

{
  "success": true,
  "data": {
    "worktreePath": "/project/workspaces/trials/feature-my-feature-abc12345",
    "branch": "feature/my-feature",
    "headSha": "a1b2c3d4e5f6..."
  }
}

Commit Changes

curl -X POST http://localhost:8787/v1/trials/abc123/worktree/commit \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "feat: implement auth",
    "author": {
      "name": "AI Agent",
      "email": "[email protected]"
    }
  }'

Push Changes

curl -X POST http://localhost:8787/v1/trials/abc123/worktree/push \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "githubToken": "ghp_xxx",
    "force": false
  }'

Note: githubToken is required for push operations. The token is used inline and never stored on disk.

Development

# Clone the repo
cd worker-service-node

# Install dependencies
npm install

# Run in dev mode (with watch)
npm run dev

# Type check
npm run typecheck

# Build
npm run build

# Run production build
npm start

Publishing

# Build and publish to npm
npm publish --access public

License

MIT