Intent - AI-Powered CLI Agent Wrapper

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

# 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)

# 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

# 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

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

# 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:

npm install -g @anthropic-ai/claude-code

Check system requirements only:

intent --setup-only

Skip checks if everything is working:

intent --skip-checks

Port already in use:

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

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

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

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

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

# 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 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

// 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

// 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

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

Permission errors

# Check workspace permissions
ls -la workspace/
# Fix if needed
sudo chown -R $USER workspace/

Port already in use

# Use different port
npm start -- --port 8080

Monitoring

# 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 file for details.

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