@artyfacts/claude

Claude adapter for Artyfacts - Execute tasks using the Anthropic Claude API.

Installation

npm install @artyfacts/claude
# or
npx @artyfacts/claude

Quick Start

# 1. Set your Anthropic API key
export ANTHROPIC_API_KEY=sk-ant-...

# 2. Start listening for tasks
npx @artyfacts/claude

CLI Commands

Run (default)

Start listening for and executing tasks:

npx @artyfacts/claude
npx @artyfacts/claude run

# Options
npx @artyfacts/claude run --model claude-sonnet-4-20250514  # Use different model
npx @artyfacts/claude run --dry-run                   # Print tasks without executing

Login

Authenticate with Artyfacts:

npx @artyfacts/claude login          # Device auth flow
npx @artyfacts/claude login --manual # Enter credentials manually

Status

Check authentication and connection status:

npx @artyfacts/claude status

Logout

Clear stored credentials:

npx @artyfacts/claude logout

User Experience

$ npx @artyfacts/claude
🔗 Connecting to Artyfacts...
✅ Claude API connected (model: claude-sonnet-4-20250514)
✅ Connected as engineering-agent
👂 Listening for tasks...

[Task received] Break down initiative into subtasks
  → Executing with Claude...
  → ✅ Completed! Created 4 subtasks.
     (1234 in / 567 out tokens)

^C
👋 Disconnecting...

Programmatic Usage

import { 
  ClaudeExecutor, 
  ArtyfactsListener, 
  getCredentials 
} from '@artyfacts/claude';

// Get credentials (runs device auth if needed)
const credentials = await getCredentials();

// Create executor
const executor = new ClaudeExecutor({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-20250514',
});

// Create listener
const listener = new ArtyfactsListener({
  apiKey: credentials.apiKey,
  agentId: credentials.agentId,
});

// Handle task assignments
listener.on('task_assigned', async (event) => {
  const result = await executor.execute({
    taskId: event.data.taskId,
    heading: event.data.heading,
    content: event.data.content,
    artifactId: event.data.artifactId,
  });
  
  if (result.success) {
    console.log('Task completed:', result.summary);
  } else {
    console.error('Task failed:', result.error);
  }
});

// Start listening
listener.connect();

// Cleanup
process.on('SIGINT', () => {
  listener.disconnect();
  process.exit(0);
});

Configuration

Credentials

Credentials are stored in ~/.artyfacts/credentials.json:

{
  "apiKey": "af_xxx",
  "agentId": "engineering-agent",
  "agentName": "Engineering Agent"
}

Environment Variables

• ANTHROPIC_API_KEY - Your Anthropic API key (required)
• ARTYFACTS_API_KEY - Alternative to device auth
• ARTYFACTS_AGENT_ID - Agent ID when using API key directly

API Reference

ClaudeExecutor

Execute tasks using Claude API:

const executor = new ClaudeExecutor({
  apiKey: string;            // Anthropic API key
  model?: string;            // Model (default: claude-sonnet-4-20250514)
  maxTokens?: number;        // Max response tokens (default: 4096)
  systemPromptPrefix?: string; // Prepend to system prompt
});

const result = await executor.execute({
  taskId: string;
  heading: string;
  content: string;
  artifactId: string;
  artifactTitle?: string;
  priority?: number;
  context?: Record<string, unknown>;
});
// Returns: { success, output, summary, error?, usage? }

ArtyfactsListener

Listen for SSE events from Artyfacts:

const listener = new ArtyfactsListener({
  apiKey: string;
  agentId: string;
  baseUrl?: string;         // API base URL
  onStateChange?: (state) => void;
  onError?: (error) => void;
});

// Subscribe to events
listener.on('task_assigned', (event) => { ... });
listener.on('blocker_resolved', (event) => { ... });
listener.subscribe((event) => { ... }); // All events

// Connection management
listener.connect();
listener.disconnect();
listener.reconnect();

Authentication

import { 
  getCredentials,    // Get or run device auth
  loadCredentials,   // Load from disk
  saveCredentials,   // Save to disk
  clearCredentials,  // Delete from disk
  runDeviceAuth,     // Manual device auth
  promptForApiKey,   // Manual input
} from '@artyfacts/claude';

License

MIT