npm package: @resonancelabs/intent-cli
Description: AI-powered CLI agent wrapper that provides HTTP control over Claude Code and other AI coding assistants
Author: Resonance Labs AI
Latest version: 0.0.9

# Intent - AI-Powered CLI Agent Wrapper

[![npm version](https://badge.fury.io/js/%40resonancelabs%2Fintent.svg)](https://badge.fury.io/js/%40resonancelabs%2Fintent)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful Node.js service that provides HTTP control over Claude Code and other AI coding assistants through a simple REST API. Features advanced Git-based reference management for safe, auditable AI code executions.

## Quick Install

```bash
# Install globally
npm install -g @resonancelabs/intent

# Start the agent wrapper (includes setup checks)
intent

# Or with custom options
intent --port 8080 --workspace ~/my-projects
```

## Overview

Transform your Claude Code CLI into a programmable web service. Execute AI coding tasks remotely, manage version-controlled project references, and integrate AI assistance into your existing workflows - all while maintaining complete audit trails and execution safety.

### Key Features

🤖 **AI Agent Control** - HTTP API for Claude Code and Gemini CLI  
📁 **Reference Management** - Git-based project isolation and version control  
🔒 **Execution Safety** - Isolated workspaces prevent unintended changes  
📊 **Complete Audit Trail** - Track every change with preserved execution branches  
🚀 **Real-time Streaming** - Live execution logs and progress updates  
🔄 **Conflict-free Operations** - Multiple concurrent executions supported  
🛠 **Manual Integration** - Review and merge AI changes when ready  
💬 **Conversation Continuation** - Resume AI conversations with Claude's `-c` flag  
📂 **Execution File API** - Browse and read files from execution workspaces  
🔧 **Workspace Persistence** - Preserved workspaces for debugging and continuation  

## Architecture

```
Your Web App  ←→  CLI Agent Wrapper  ←→  Claude Code CLI
     │                    │                    │
     │            Git Reference Mgmt      Your Local
     │            Execution Isolation     Claude Auth
     │            Audit Trail            & Max Plan
     └─── HTTP API ────────────────────────────┘
```

The wrapper creates isolated Git workspaces for each execution, preserving your original code while tracking all AI changes in separate branches for complete audit trails.

## Installation & Setup

### Prerequisites

- Node.js 18+
- Git
- Claude Code CLI installed and authenticated

### Global Installation (Recommended)

```bash
# Install globally
npm install -g @resonancelabs/intent

# Start the agent wrapper (includes system checks and setup)
intent

# Or with custom options
intent --port 8080 --debug --workspace /path/to/workspace

# Check system requirements only (don't start server)
intent --setup-only
```

### Local Development

```bash
# Clone the repository
git clone https://github.com/resonancelabsai/intent.git
cd intent

# Install dependencies
npm install

# Start with default workspace
npm start

# Or specify custom options
npm start -- --workspace /path/to/your/workspace --port 8080
```

### Command Options

```bash
intent --help                    # Show all available options
intent                           # Start with system checks and setup
intent update                    # Update to latest version
intent --port 3010               # Custom port (default: 3010)
intent --debug                   # Enable debug logging
intent --verbose                 # Enable verbose logging with process output
intent --workspace /custom/path  # Custom workspace directory
intent --setup-only              # Check system requirements only
intent --skip-checks             # Skip system checks and start immediately
intent --skip-update-check       # Skip automatic update check
```

### First API Call

```bash
# Create a simple project
curl -X POST http://localhost:3010/execute \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "claude",
    "prompt": "Create a README.md file with project documentation",
    "refs": {
      "create": ["my-project"]
    }
  }'
```

### Troubleshooting Setup

If you encounter issues during startup:

**Claude Code not installed:**
```bash
npm install -g @anthropic-ai/claude-code
```

**Check system requirements only:**
```bash
intent --setup-only
```

**Skip checks if everything is working:**
```bash
intent --skip-checks
```

**Port already in use:**
```bash
intent --port 8080  # Use different port
```

## 🔄 Automatic Updates

Intent automatically checks for updates and keeps you on the latest version:

### **Automatic Update Checking**
- Intent checks for updates every 24 hours on startup
- Shows notification when newer version is available
- Non-intrusive - won't interrupt your workflow

### **Manual Updates**
```bash
intent update           # Check and update to latest version
intent update --force   # Update without confirmation prompt
```

### **Update Notifications**
When a new version is available, you'll see:
```
📦 UPDATE AVAILABLE
Current: 1.0.0 → Latest: 1.0.1
Run 'intent update' to upgrade
```

### **Skip Update Checks**
```bash
intent --skip-update-check  # Skip automatic update check on startup
```

## Use Cases & Integration Examples

### 1. Code Review Assistant

**Scenario**: Integrate AI code review into your GitHub workflow

```javascript
// In your web app
async function reviewPullRequest(prFiles) {
  // Create reference from PR files
  const reviewRef = await createRefFromFiles('pr-review', prFiles);
  
  // Execute AI review
  const response = await fetch('http://localhost:3010/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent: 'claude',
      prompt: 'Review this code for bugs, security issues, and best practices. Provide specific feedback.',
      refs: {
        read: ['pr-review'],
        create: ['review-report']
      }
    })
  });
  
  const { executionId } = await response.json();
  
  // Stream results to your UI
  const eventSource = new EventSource(`http://localhost:3010/logs/${executionId}/stream`);
  eventSource.onmessage = (event) => {
    updateReviewUI(JSON.parse(event.data));
  };
  
  // Get final review when complete
  const reviewFiles = await getExecutionResults(executionId, 'review-report');
  return reviewFiles;
}
```

### 2. Documentation Generator

**Scenario**: Automatically generate docs for your codebase

```javascript
// Generate API documentation
async function generateAPIDocs(sourceCode) {
  const execution = await fetch('http://localhost:3010/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent: 'claude',
      prompt: `Generate comprehensive API documentation including:
        - Endpoint descriptions
        - Request/response schemas  
        - Code examples
        - OpenAPI specification`,
      refs: {
        read: ['source-code'],
        create: ['api-docs', 'openapi-spec']
      }
    })
  });
  
  // Monitor progress and get results
  return await handleExecution(execution.executionId);
}
```

### 3. Code Migration Tool

**Scenario**: Migrate legacy code to new frameworks

```javascript
// Migrate jQuery to React
async function migrateToReact(legacyProject) {
  const migration = await fetch('http://localhost:3010/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent: 'claude',
      prompt: `Migrate this jQuery application to modern React:
        - Convert jQuery selectors to React components
        - Implement state management
        - Add TypeScript types
        - Preserve all functionality`,
      refs: {
        read: ['legacy-jquery-app'],
        create: ['react-migration']
      }
    })
  });
  
  // Review changes before applying
  const diffUrl = `http://localhost:3010/refs/react-migration/diff?from=main&to=exec-${migration.executionId}`;
  const changes = await fetch(diffUrl).then(r => r.json());
  
  // Apply changes when ready
  if (userApproves(changes)) {
    await mergeChanges('react-migration', migration.executionId);
  }
}
```

### 4. Test Generator

**Scenario**: Generate comprehensive test suites

```javascript
// Auto-generate tests for your functions
async function generateTests(sourceFiles) {
  return await fetch('http://localhost:3010/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent: 'claude',
      prompt: `Generate comprehensive test suites:
        - Unit tests for all functions
        - Integration tests for APIs
        - Edge case coverage
        - Mocking strategies`,
      refs: {
        read: ['source-code'],
        mutate: ['test-suite'] // Add to existing test directory
      }
    })
  });
}
```

### 5. Security Audit

**Scenario**: Automated security analysis

```javascript
// Security audit with remediation
async function securityAudit(codebase) {
  const audit = await fetch('http://localhost:3000/execute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent: 'claude',
      prompt: `Perform security audit and create fixes:
        - Identify vulnerabilities
        - SQL injection prevention
        - XSS protection
        - Authentication issues
        - Generate secure code alternatives`,
      refs: {
        read: ['codebase'],
        create: ['security-report', 'security-fixes']
      }
    })
  });
  
  // Review security findings
  const report = await getExecutionResults(audit.executionId, 'security-report');
  const fixes = await getExecutionResults(audit.executionId, 'security-fixes');
  
  return { report, fixes };
}
```

## Reference Management

### Creating References

```javascript
// Option 1: Let AI create new projects
{
  "refs": {
    "create": ["new-project"]
  }
}

// Option 2: Upload existing code as reference
const formData = new FormData();
formData.append('files', fileBlob, 'src/app.js');
await fetch('http://localhost:3000/refs/my-project/upload', {
  method: 'POST',
  body: formData
});
```

### Managing Execution Results

```javascript
// List all references
const refs = await fetch('http://localhost:3000/refs').then(r => r.json());

// View execution branches (audit trail)
const branches = await fetch('http://localhost:3000/refs/my-project/branches').then(r => r.json());

// Compare AI changes with original
const diff = await fetch('http://localhost:3000/refs/my-project/diff?from=exec-123&to=main').then(r => r.json());

// Merge when ready
await fetch('http://localhost:3000/refs/my-project/merge', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    sourceBranch: 'exec-123',
    targetBranch: 'main',
    strategy: 'merge'
  })
});
```

## Integration Patterns

### React Hook Example

```javascript
import { useState, useEffect } from 'react';

export function useClaudeExecution() {
  const [executions, setExecutions] = useState({});
  
  const executeTask = async (prompt, refs) => {
    const response = await fetch('http://localhost:3000/execute', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ agent: 'claude', prompt, refs })
    });
    
    const { executionId } = await response.json();
    
    // Stream updates
    const eventSource = new EventSource(`http://localhost:3000/logs/${executionId}/stream`);
    eventSource.onmessage = (event) => {
      const update = JSON.parse(event.data);
      setExecutions(prev => ({
        ...prev,
        [executionId]: update
      }));
    };
    
    return executionId;
  };
  
  return { executions, executeTask };
}
```

### Python Integration

```python
import requests
import json

class ClaudeWrapper:
    def __init__(self, base_url="http://localhost:3000"):
        self.base_url = base_url
    
    def execute_task(self, prompt, refs):
        response = requests.post(f"{self.base_url}/execute", json={
            "agent": "claude",
            "prompt": prompt,
            "refs": refs
        })
        return response.json()["executionId"]
    
    def get_results(self, execution_id, ref_id):
        response = requests.get(f"{self.base_url}/refs/{ref_id}/files")
        return response.json()
    
    def stream_logs(self, execution_id):
        response = requests.get(
            f"{self.base_url}/logs/{execution_id}/stream",
            stream=True
        )
        for line in response.iter_lines():
            if line:
                yield json.loads(line)

# Usage
claude = ClaudeWrapper()
execution_id = claude.execute_task(
    "Refactor this code for better performance",
    {"mutate": ["my-project"]}
)

for log in claude.stream_logs(execution_id):
    print(f"Status: {log.get('status', 'unknown')}")
```

## Configuration

### Workspace Setup

```bash
# Default: ./workspace
npm start

# Custom workspace location
npm start -- --workspace /data/ai-projects

# Custom port
npm start -- --port 8080

# Environment variables
WORKSPACE_DIR=/data/ai-projects
PORT=8080
npm start
```

### Reference Management

The system automatically creates this structure:

```
workspace/
├── refs/                    # Your project references
│   ├── my-project/
│   │   ├── main branch     # Original code (never modified)
│   │   └── exec-* branches # AI execution results
├── .execution/             # Temporary workspaces (auto-cleaned)
└── data/                   # Execution history and audit logs
```

## API Reference

### Core Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/execute` | POST | Start AI execution |
| `/status/:id` | GET | Check execution status |
| `/logs/:id/stream` | GET | Stream real-time logs |
| `/refs` | GET | List all references |
| `/refs/:id/files` | GET | Browse reference files |
| `/refs/:id/merge` | POST | Merge AI changes |
| `/refs/:id/diff` | GET | Compare branches |

See [API Documentation](docs/reference-management-system.md) for complete endpoint details.

## Benefits for Web Applications

### 🔐 **Use Your Existing Claude Plan**
- Leverages your local Claude Code authentication
- No need for separate API keys or subscriptions
- Uses your existing usage limits and features

### 🏠 **Complete Local Control**
- All code stays on your machine
- No data sent to third-party services
- Full audit trail of all changes

### 🔍 **Safe AI Execution**
- Original code never modified
- All changes in separate branches
- Review before applying any changes

### 📈 **Scalable Integration**
- REST API fits any tech stack
- Real-time streaming for live updates
- Concurrent execution support

### 🎯 **Production Ready**
- Comprehensive error handling
- Performance monitoring
- Resource management
- Automatic cleanup

## Advanced Usage

### Batch Processing

```javascript
// Process multiple files simultaneously
const executions = await Promise.all([
  executeTask("Optimize for performance", {mutate: ["frontend"]}),
  executeTask("Add error handling", {mutate: ["backend"]}),
  executeTask("Generate tests", {read: ["utils"], create: ["test-suite"]})
]);
```

### Workflow Automation

```javascript
// Chain AI tasks
async function fullStackDevelopment(requirements) {
  // 1. Generate backend API
  const backendId = await executeTask(
    `Create REST API for: ${requirements}`,
    {create: ["api-server"]}
  );
  
  await waitForCompletion(backendId);
  
  // 2. Generate frontend using the API
  const frontendId = await executeTask(
    "Create React frontend that uses this API",
    {read: ["api-server"], create: ["web-app"]}
  );
  
  // 3. Generate integration tests
  const testsId = await executeTask(
    "Create e2e tests for the full stack",
    {read: ["api-server", "web-app"], create: ["e2e-tests"]}
  );
  
  return { backendId, frontendId, testsId };
}
```

## Troubleshooting

### Common Issues

**Claude Code not found**
```bash
# Ensure Claude Code is installed and in PATH
which claude_code_cli
# Install if needed: https://claude.ai/code
```

**Permission errors**
```bash
# Check workspace permissions
ls -la workspace/
# Fix if needed
sudo chown -R $USER workspace/
```

**Port already in use**
```bash
# Use different port
npm start -- --port 8080
```

### Monitoring

```bash
# Check execution status
curl http://localhost:3000/status/exec-123

# View audit trail
curl http://localhost:3000/monitoring/audit/exec-123

# System metrics
curl http://localhost:3000/monitoring/metrics
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add comprehensive tests
4. Update documentation
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Transform your Claude Code into a powerful web service. Start building AI-powered applications today!**