CoStar Server Executor

A TypeScript implementation of autonomous AI agent patterns, cloned from OpenClaw and enhanced with built-in tools from ProjectX.

Overview

CoStar Server Executor is a 24/7 autonomous agent framework that:

• ✅ Executes tasks using Claude AI (Anthropic API)
• ✅ Has access to 32 powerful tools (file operations, web, email, calendar, maps, and more)
• ✅ Supports modular skills using the AgentSkills.io standard
• ✅ Runs heartbeat checks for proactive monitoring
• ✅ Stores memory and context in Supabase
• ✅ Can be used as a CLI tool or TypeScript library

Features

Core Capabilities

• Agentic Execution Loop: Multi-turn conversations with tool use
• 32 Built-in Tools: File ops, shell execution, web search/fetch, browser automation, memory, email, calendar, maps, image/video generation, and more
• Skills System: AgentSkills.io compatible framework for modular capabilities
• Workspace Context: Loads context from AGENTS.md, MEMORY.md, USER.md, PROJECTS.md
• Heartbeat Checks: Proactive monitoring using HEARTBEAT.md instructions
• Supabase Integration: Persistent memory and data storage

Tool Categories (32 tools)

File Operations (5 tools)

• read - Read file contents
• write - Write file contents
• edit - Edit file with search/replace
• grep - Search file contents
• glob - Find files by pattern

Execution Tools (2 tools)

• exec - Execute shell commands with PTY support
• process - Manage shell command sessions

Web Tools (3 tools)

• web_search - Search the web using Brave Search API
• web_fetch - Fetch and extract web page content
• browser - Control headless Chromium browser

Agent Tools (5 tools)

• memory - Store and recall information in Supabase
• message - Send messages to the user
• image - Analyze images using GPT-4V
• tts - Text-to-speech using OpenAI TTS
• session_status - Get current session information

Email Tools (4 tools)

• search_emails - Search Gmail messages
• send_email - Send plain-text or HTML email via Gmail (is_html: true renders the body as HTML)
• read_email - Read specific email by ID
• read_email_thread - Read entire email thread

The mobile email flow uses write_email_draft followed by user confirmation and send_email_draft; passing is_html: true preserves rendered HTML through that draft workflow.

Calendar Tools (4 tools)

• get_calendar_events - List calendar events
• create_calendar_event - Create new event
• update_calendar_event - Update existing event
• delete_calendar_event - Delete event by ID

Google Maps Tools (3 tools)

• google_maps_search - Search nearby places
• google_maps_directions - Get turn-by-turn directions
• geocode - Convert address to coordinates

Utility Tools (3 tools)

• generate_image - Generate images using AI (Gemini Imagen 4)
• generate_video - Generate videos using AI (Google Veo 3.1)
• fetch_api_data - Make HTTP requests to external APIs

Installation

# Clone the repository
git clone <your-repo-url>
cd costar-server-executor

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
nano .env

# Build the project
npm run build

Configuration

Required Environment Variables

# Anthropic API Key
ANTHROPIC_API_KEY=sk-ant-...

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Optional Environment Variables

See .env.example for all available configuration options including:

• Agent configuration (model, max tokens, temperature)
• Tool API keys (OpenAI, Brave Search, Google services)
• Workspace directory
• Skills directories
• Disabled tools

Usage

CLI Usage

# Execute a task
npm start "Search for recent news about AI"

# Or after building
node dist/index.js "Send an email to [email protected] about the meeting"

# Execute heartbeat check
npm start -- --heartbeat

# Show help
npm start -- --help

Library Usage

import { createAgent, executeTask, executeHeartbeat } from "costar-server-executor";

// Execute a task
const response = await executeTask("What's the weather in San Francisco?");
console.log(response);

// Or create and manage agent directly
const agent = await createAgent();
const result = await agent.executeTurn("Search for latest AI news", {
  maxTurns: 25,
  onToolCall: (toolName, toolCallId) => {
    console.log(`Tool: ${toolName}`);
  },
  onResponse: (text) => {
    console.log(`Response: ${text}`);
  },
});

console.log(result.response);

Workspace Files

Create a workspace/ directory with the following markdown files to provide context to the agent:

• AGENTS.md - Autonomy grants and permissions
• MEMORY.md - Agent's persistent memory
• USER.md - User profile and preferences
• PROJECTS.md - Active coding projects
• HEARTBEAT.md - Instructions for heartbeat checks
• CRON.md - Scheduled tasks

Example workspace/AGENTS.md:

# Autonomy Grants

You are authorized to:
- Search the web for information
- Read and analyze files in the workspace
- Send emails on behalf of the user
- Create calendar events
- Execute shell commands (non-destructive)

Do NOT:
- Delete important files without confirmation
- Send emails to unknown recipients
- Make financial transactions

Skills

The executor supports AgentSkills.io compatible skills. Bundled skills include:

• /commit - Create git commits with proper formatting (Conventional Commits)
• /test - Run tests with common frameworks (Jest, Vitest, Pytest, etc.)
• /review-pr - Review GitHub pull requests

Creating Custom Skills

Create a SKILL.md file in workspace/skills/ or any directory specified in SKILLS_EXTRA_DIRS:

---
name: my-skill
description: What this skill does
metadata:
  emoji: "🚀"
  requires:
    bins: ["binary-name"]
    env: ["API_KEY"]
  install:
    - kind: brew
      formula: package-name
---

# Skill Instructions

Detailed markdown instructions for the agent...

See SKILLS_SYSTEM.md for complete documentation.

API Keys Required

Core Functionality

• ANTHROPIC_API_KEY - For Claude AI agent execution
• SUPABASE_URL + SUPABASE_SERVICE_KEY - For memory storage

Optional Tools

• OPENAI_API_KEY - For image analysis (GPT-4V) and TTS
• BRAVE_SEARCH_API_KEY - For web search
• GEMINI_API_KEY - For image/video generation (Gemini Imagen 4, Veo 3.1)
• GOOGLE_MAPS_API_KEY - For maps, geocoding, and directions
• GOOGLE_SERVICE_ACCOUNT_JSON - For Gmail and Calendar access

Development

# Run in development mode with auto-reload
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

Architecture

src/
├── agent/              # Agent execution loop
│   ├── agent.ts        # Main Agent class
│   ├── context-loader.ts  # Workspace file loader
│   └── tool-executor.ts   # Tool execution handler
├── config/             # Configuration management
│   ├── types.ts        # Config type definitions
│   └── config.ts       # Config loader and validator
├── skills/             # Skills system
│   ├── types.ts        # Skill type definitions
│   ├── loader.ts       # SKILL.md parser
│   ├── status.ts       # Requirement validation
│   └── manager.ts      # SkillsManager API
├── tools/              # Tool implementations
│   ├── built-in-tools.ts  # Built-in tools (email, calendar, maps, etc.)
│   ├── web-search.ts   # Web search tool
│   ├── browser.ts      # Browser automation tool
│   ├── memory.ts       # Memory tool
│   └── ...             # Other tools
├── types/              # Type definitions
│   └── tool.ts         # Tool types
├── utils/              # Utility functions
│   └── tool-helpers.ts # Tool helper functions
└── index.ts            # Main entry point

Documentation

• TOOLS_IMPLEMENTATION.md - Complete documentation of all 32 tools
• SKILLS_SYSTEM.md - Skills system documentation and best practices
• .env.example - Environment configuration template

Credits

• OpenClaw - Original architecture and patterns (@badlogic)
• ProjectX - Built-in tools reference implementation (Dart/Flutter)
• @mariozechner/pi-coding-agent - File operation tools
• AgentSkills.io - Skills format specification

License

MIT

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• GitHub Issues: Create an issue
• Documentation: See TOOLS_IMPLEMENTATION.md and SKILLS_SYSTEM.md

CoStar Server Executor - Autonomous AI agents in TypeScript