@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

``bash


Install globally

npm install -g @saeed42/worktree-worker

Or add to your project

npm install @saeed42/worktree-worker
`

Quick Start

$3

`bash


Set environment variables

export WORKER_TOKEN=your-secret-token
export PORT=8787

Run the service

worktree-worker
`

$3

Add to your package.json:

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

Or run directly:

`bash
npx @saeed42/worktree-worker
`

$3

`typescript
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

$3

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

$3

| 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 |

$3

| 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

$3

`bash
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"
}'
`

$3

`bash
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:

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

$3

`bash
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": "agent@origin.ai"
}
}'
`

$3

`bash
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

`bash


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

`bash


Build and publish to npm


npm publish --access public
``

License

MIT