Temporal Orchestrator

A TypeScript-based orchestration service using Temporal for managing AI agents and automated workflows.

Features

• Temporal Workflows: Reliable, durable workflow execution
• GitHub Integration: Automated repository maintenance and webhook processing
• Claude AI Integration: Execute Claude commands in isolated Docker containers
• Scheduled Workflows: Cron-based scheduling for recurring tasks
• TypeScript: Full type safety with strict mode enabled
• Modern Tooling: ESLint, Prettier, Husky pre-commit hooks

Architecture

├── src/
│   ├── activities/      # Temporal activities (GitHub, Claude integrations)
│   ├── workflows/       # Temporal workflow definitions
│   ├── workers/         # Worker processes
│   ├── client/          # Temporal client utilities
│   ├── schedules/       # Schedule management
│   ├── api/            # REST API endpoints
│   └── utils/          # Shared utilities
├── config/             # Configuration files
│   └── schedules.yml   # Scheduled workflow definitions
└── test/              # Test files

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• GitHub Personal Access Token
• Anthropic API Key (for Claude integration)

Setup

1. Clone the repository:

git clone https://github.com/intelligence-assist/temporal-orchestrator.git
cd temporal-orchestrator

2. Install dependencies:

npm install

3. Copy environment variables:

cp .env.example .env
# Edit .env with your tokens

4. Start Temporal server:

docker compose up -d temporal temporal-ui postgresql

5. Build the project:

npm run build

Running

Development Mode

Start the API server:

npm run dev

Start the workers:

npm run worker:dev

Production Mode

docker compose up -d

Workflows

GitHub Maintenance Workflows

• updateOrganizationReadme: Updates organization README with repository stats
• performHealthCheck: Checks repository health and creates issues for problems

Claude Webhook Workflow

• processGitHubWebhook: Processes GitHub webhook events and executes Claude commands

API Endpoints

• POST /api/orchestrate - Start a workflow
• POST /api/webhook/github - GitHub webhook endpoint
• GET /api/schedules - List scheduled workflows
• POST /api/schedules/reload - Reload schedule configuration
• GET /health - Health check

Scheduled Workflows

Configure scheduled workflows in config/schedules.yml:

schedules:
  - id: update-org-readme
    workflow: updateOrganizationReadme
    cronExpression: "0 0 * * MON"  # Every Monday
    enabled: true
    args:
      organization: "intelligence-assist"
      token: "${GITHUB_TOKEN}"

Development

Linting and Formatting

npm run lint        # Fix linting issues
npm run format      # Format code with Prettier
npm run typecheck   # Type check without building

Testing

npm test                # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Generate coverage report

GitHub Repository Setup

1. Create a new repository in the intelligence-assist organization:

gh repo create intelligence-assist/temporal-orchestrator \
  --public \
  --description "Temporal-based orchestration service for AI agents" \
  --clone

2. Push the code:

git add .
git commit -m "Initial commit: Temporal orchestrator with TypeScript"
git push -u origin main

Monitoring

Access Temporal UI at http://localhost:8088 to monitor workflows, view execution history, and debug issues.

License

MIT