Claude Code Agents Manager

A modern web application built with Astro that allows you to create and manage AI-powered coding tasks using Claude Code SDK. Each task automatically clones a repository instance, initializes it, and lets Claude Code implement your requirements while providing a real-time chat interface to interact with the AI agent.

Features

• 🚀 Task Creation: Create coding tasks with natural language descriptions
• 🔄 Automatic Repository Cloning: Each task gets its own isolated repository instance
• 🤖 Claude Code Integration: Leverage Anthropic's Claude Code SDK for AI-powered development
• 💬 Real-time Chat Interface: Interact with Claude Code through a modern chat UI
• 📊 Task Management: Monitor task progress, view messages, and manage multiple tasks
• 🎨 Modern UI: Beautiful, responsive interface with real-time updates
• ⚡ Server Actions: Type-safe backend operations using Astro's Server Actions
• 🏗️ Custom Elements: Client-side interactivity using modern web standards

Architecture

Tech Stack

• Frontend: Astro 5.x with Server Actions
• Backend: Node.js with Astro's Node adapter
• AI Integration: Anthropic Claude Code SDK
• Repository Management: Git automation with Node.js child processes
• Styling: Custom CSS with modern design patterns
• Client Interactivity: Custom Elements (Web Components)

Key Components

1. Server Actions (src/actions/): Type-safe backend API for task management
2. Data Store (src/lib/store.ts): In-memory data management (can be replaced with a database)
3. Git Manager (src/lib/git-utils.ts): Repository cloning and management utilities
4. Claude Code Manager (src/lib/claude-code.ts): Integration with Claude Code SDK
5. Custom Elements (src/components/): Interactive UI components
6. Pages: Main dashboard and task detail views

Setup

Prerequisites

• Node.js 18+ or Bun
• pnpm (recommended) or npm
• Git
• Anthropic API key (or AWS Bedrock/Google Vertex AI credentials)

Installation

1. Clone and navigate to the agents-manager package:

   cd packages/agents-manager

2. Install dependencies:

   pnpm install

3. Create environment file:

   cp .env.example .env

4. Configure your environment variables in .env:

   # Required: Anthropic API Key
   ANTHROPIC_API_KEY=your_anthropic_api_key_here
      
   # Required: Source repository URL (the repo to clone for each task)
   SOURCE_REPO_URL=https://github.com/your-username/your-repo.git
      
   # Optional: Custom paths
   REPO_INSTANCES_PATH=./repo-instances
   PORT=4000
   HOST=localhost

Development

Start the development server:

pnpm dev

The application will be available at http://localhost:4000.

Production

Build and start the production server:

pnpm build
pnpm preview

Usage

Creating a Task

1. Navigate to the homepage where you'll see the task creation form
2. Enter a task title (e.g., "Add dark mode to the playground")
3. Provide a detailed description of what you want Claude Code to implement
4. Click "Create Task" to create the task (it will be in "pending" status)

Starting a Task

1. Click "Start Task" on any pending task
2. The system will:
   • Clone a fresh instance of your repository
   • Install dependencies (supports both npm and pnpm workspaces)
   • Initialize a Claude Code session with your task description
   • Begin AI-powered development

Monitoring Progress

1. View the task list to see all tasks and their current status
2. Click "View Details" on running or completed tasks to see the chat interface
3. Monitor real-time messages between you and Claude Code
4. View repository status including branch information and changed files

Interacting with Claude Code

1. Open a running task's detail page to access the chat interface
2. Send messages to provide additional context or guidance
3. View Claude's progress through the message history
4. Stop or delete tasks as needed

Task Lifecycle

pending → cloning → running → completed/failed

• Pending: Task created but not yet started
• Cloning: Repository being cloned and initialized
• Running: Claude Code is actively working on the task
• Completed: Task finished successfully
• Failed: Task encountered an error

API Reference

The application uses Astro Server Actions for type-safe backend operations:

Available Actions

• createTask({ title, description }) - Create a new task
• startTask({ taskId }) - Start a pending task
• continueSession({ taskId, message }) - Send message to Claude Code
• stopSession({ taskId }) - Stop a running task
• deleteTask({ taskId }) - Delete a task and cleanup resources
• getTasks({}) - Get all tasks
• getTask({ taskId }) - Get task details with messages
• getTaskUpdates({ taskId, lastMessageId? }) - Poll for new messages

Configuration

Repository Settings

Configure the source repository URL in your .env file. Each task will clone this repository into an isolated directory under REPO_INSTANCES_PATH.

Claude Code Options

The Claude Code integration supports various options:

• Max Turns: Maximum number of AI turns per session
• Working Directory: Each task runs in its own repository instance
• Abort Control: Tasks can be stopped gracefully

Authentication Options

The application supports multiple Claude Code authentication methods:

1. Anthropic API (recommended):

   ANTHROPIC_API_KEY=your_key_here

2. AWS Bedrock:

   CLAUDE_CODE_USE_BEDROCK=1
   # Configure AWS credentials

3. Google Vertex AI:

   CLAUDE_CODE_USE_VERTEX=1
   # Configure Google Cloud credentials

Deployment

Using the Node Adapter

The application is configured with Astro's Node adapter for deployment to any Node.js-compatible platform:

pnpm build
node dist/server/entry.mjs

Environment Variables for Production

Ensure these environment variables are set in production:

• ANTHROPIC_API_KEY (or alternative auth method)
• SOURCE_REPO_URL
• REPO_INSTANCES_PATH (should be persistent storage)

Limitations

• In-Memory Storage: Current implementation uses in-memory storage. For production, replace the data store with a database
• Repository Cleanup: Completed task repositories are not automatically cleaned up (implement cleanup policies as needed)
• Concurrent Limits: No built-in limits on concurrent tasks (implement rate limiting as needed)
• Authentication: No user authentication system (add as needed for multi-user scenarios)

Contributing

1. Follow the existing code structure and patterns
2. Use TypeScript for type safety
3. Test Server Actions thoroughly
4. Ensure Custom Elements are properly registered
5. Update documentation for new features

License

This project is part of the larger Zai repository. See the main repository for license information.