agents-manager

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

• Server Actions (src/actions/): Type-safe backend API for task management
• Data Store (src/lib/store.ts): In-memory data management (can be replaced with a database)
• Git Manager (src/lib/git-utils.ts): Repository cloning and management utilities
• Claude Code Manager (src/lib/claude-code.ts): Integration with Claude Code SDK
• Custom Elements (src/components/): Interactive UI components
• 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

• Clone and navigate to the agents-manager package:

  cd packages/agents-manager
  

• Install dependencies:

  pnpm install
  

• Create environment file:

  cp .env.example .env
  

• 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

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

Starting a Task

• Click "Start Task" on any pending task
• 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

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

Interacting with Claude Code

• Open a running task's detail page to access the chat interface
• Send messages to provide additional context or guidance
• View Claude's progress through the message history
• 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:

• Anthropic API (recommended):

  ANTHROPIC_API_KEY=your_key_here
  

• AWS Bedrock:

  CLAUDE_CODE_USE_BEDROCK=1
  # Configure AWS credentials
  

• 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

• Follow the existing code structure and patterns
• Use TypeScript for type safety
• Test Server Actions thoroughly
• Ensure Custom Elements are properly registered
• Update documentation for new features

License

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