AI Agents Integration

This guide provides instructions for AI coding agents (Cursor, Windsurf, Cline, Aider, Claude Code, etc.) on how to control DevAll using CLI commands. These commands allow agents to manage development services programmatically.

Two Ways to Integrate DevAll

There are two approaches to integrating DevAll with AI coding agents:

1. Simple Approach: AGENTS.md or CLAUDE.md Files (Recommended)

Best for: Most projects, quick setup, no additional configuration needed

Add DevAll instructions directly to your project’s AGENTS.md or CLAUDE.md file. This is simpler than MCP integration and works with all AI coding agents that read these instruction files.

Skip to the copyable instructions block

2. Advanced Approach: MCP Integration

Best for: Claude Code users who want deep integration with function calling

Use DevAll’s Model Context Protocol (MCP) server for richer integration. This allows Claude Code to call DevAll functions directly without running CLI commands.

See the Claude Code Integration guide for MCP setup.

Overview

DevAll provides a comprehensive CLI that AI agents can use to:

• Start, stop, and restart development services
• Monitor service status and health
• View and analyze service logs
• Manage configuration
• Check system resources
• Expose services via ngrok tunnels

Prerequisites

For AI agents to use DevAll commands:

1. DevAll must be running: Start the DevAll server first

   npx devall

2. Run CLI commands in a separate terminal: Most commands require the server to be running

3. Use full command paths: Always use npx devall or full path to ensure availability

Adding to AGENTS.md or CLAUDE.md

The simplest way to integrate DevAll with AI agents is to add instructions to your project’s AGENTS.md or CLAUDE.md file. AI coding agents automatically read these files to understand project-specific commands and workflows.

Copy and paste this block into your AGENTS.md or CLAUDE.md file:

# DevAll Service Management

This project uses DevAll for service orchestration. DevAll must be running before using these commands.

## Starting DevAll

```bash
# Start DevAll dashboard (in a separate terminal)
npx devall

Essential DevAll Commands

List all configured services

npx devall list

Start a service

npx devall start <service-name>

Stop a service

npx devall stop <service-name>

Restart a service

npx devall restart <service-name>

Restart all services

npx devall restart --all

Check service status

npx devall status <service-name>

View service logs (last 100 lines)

npx devall logs <service-name>

View service logs (specific number of lines)

npx devall logs <service-name> 50

View only error logs

npx devall errors <service-name>

Check system health

npx devall health

View configuration

npx devall config

Check port usage

npx devall ports

DevAll CLI Best Practices

1. Always list services first: Use npx devall list to get exact service names
2. Check status before starting: Run npx devall status <service> to avoid starting already-running services
3. Output is JSON by default: Parse the JSON output for reliable automation
4. DevAll server must be running: All commands except --help require the DevAll dashboard to be running
5. Wait after state changes: After starting/stopping services, wait 2-3 seconds before checking status

Common DevAll Workflows

Starting development

npx devall list                    # See available services
npx devall start frontend          # Start frontend
npx devall start backend           # Start backend
npx devall status frontend         # Verify it's running

Debugging a service

npx devall status backend          # Check status
npx devall logs backend 100        # View recent logs
npx devall errors backend          # Check for errors
npx devall restart backend         # Restart if needed

After config changes

npx devall validate                # Validate configuration
npx devall restart --all           # Restart all services
npx devall health                  # Verify all are running

Troubleshooting DevAll

• “DevAll server is not running”: Start DevAll in a separate terminal with npx devall
• “Service not found”: Run npx devall list to see exact service names
• “Port already in use”: Run npx devall ports to check port conflicts
• Service won’t start: Check npx devall errors <service> and npx devall logs <service>

Additional Resources

For more DevAll commands and advanced usage, see: DevAll Documentation

**Note:** This block works for both `AGENTS.md` and `CLAUDE.md` files. Both are widely supported by AI coding assistants.

## Command Reference

### Service Management

#### List All Services

Get a list of all configured service names:

```bash
npx devall list

Output format: JSON array of service names

Example output:

["frontend", "backend", "database", "api-gateway"]

Agent usage:

• Use this to discover available services
• Reference these exact names in other commands

Get Service Status

Check if a service is running:

npx devall status <service-name>

Examples:

npx devall status frontend
npx devall status backend

Output: JSON object with status information

Example output:

{
  "name": "frontend",
  "status": "running",
  "port": 3000,
  "pid": 12345,
  "uptime": "5m 23s"
}

Status values:

• running: Service is active
• stopped: Service is not running
• starting: Service is starting up
• crashed: Service has crashed
• error: Service encountered an error

Start a Service

Start a stopped service:

npx devall start <service-name>

Examples:

npx devall start frontend
npx devall start backend

Agent usage:

• Always check status first to avoid starting already-running services
• Wait a few seconds after starting before checking status
• Handle errors if service fails to start

Stop a Service

Stop a running service:

npx devall stop <service-name>

Examples:

npx devall stop frontend
npx devall stop backend

Agent usage:

• Verify service is running before attempting to stop
• Use for graceful shutdown
• Check status after stopping to confirm

Restart a Service

Restart a service (stop then start):

npx devall restart <service-name>

Examples:

npx devall restart frontend
npx devall restart backend

Restart all services:

npx devall restart --all

Agent usage:

• Use after configuration changes
• Use when a service is misbehaving
• More reliable than manual stop+start

Logs and Debugging

View Service Logs

Get recent log output from a service:

npx devall logs <service-name> [lines]

Examples:

# Last 100 lines (default)
npx devall logs frontend

# Last 50 lines
npx devall logs frontend 50

# Last 200 lines
npx devall logs backend 200

Agent usage:

• Use to diagnose issues
• Look for errors, warnings, stack traces
• Check startup messages
• Default is 100 lines if not specified

Follow Logs (Real-time)

Watch logs in real-time:

npx devall logs <service-name> --follow

Examples:

npx devall logs frontend --follow
npx devall logs api-gateway -f

Agent usage:

• Use when debugging active issues
• Stop with Ctrl+C when done
• Not recommended for automated scripts

View Error Logs

Get only error log lines:

npx devall errors <service-name> [lines]

Examples:

npx devall errors frontend
npx devall errors backend 50

Agent usage:

• Quick way to find errors
• Filters for error-level logs only
• Use for quick health checks

Configuration

View Configuration

Get the current configuration:

# View all configuration
npx devall config

# View specific service config
npx devall config <service-name>

Examples:

npx devall config
npx devall config frontend

Output: JSON object with configuration

Agent usage:

• Check service settings
• Verify port assignments
• Understand service dependencies

Validate Configuration

Check if configuration file is valid:

npx devall validate

Agent usage:

• Run after modifying config files
• Catches syntax errors
• Ensures required fields are present

Health and Monitoring

Health Check

Check overall system health:

# Check all services
npx devall health

# Check specific service
npx devall health <service-name>

Examples:

npx devall health
npx devall health frontend

Output: Health status for services

Agent usage:

• Quick health overview
• Check if services are responding
• Verify system is operational

System Information

Get detailed system and service information:

# All system info
npx devall info

# Specific service info
npx devall info <service-name>

Examples:

npx devall info
npx devall info frontend

Output: Detailed system metrics

Agent usage:

• Check resource usage
• Monitor memory consumption
• Verify CPU usage
• Check disk space

Port Usage

View which ports are in use:

npx devall ports

With process details:

npx devall ports --process

Output: List of ports and services

Agent usage:

• Diagnose port conflicts
• Verify services are listening
• Check for unexpected processes

Process List

View all running DevAll processes:

npx devall processes

Agent usage:

• See all managed processes
• Check PIDs
• Monitor resource usage per process

Tunneling (Ngrok)

Expose a Service

Create a public ngrok tunnel:

npx devall expose <service-name>

Multiple services:

npx devall expose frontend backend

Examples:

npx devall expose frontend
npx devall expose api-gateway database

Agent usage:

• Share local development with others
• Test webhooks
• Demo features
• Requires ngrok installed

Stop Exposing

Stop the ngrok tunnel:

npx devall unexpose <service-name>

Examples:

npx devall unexpose frontend

Check Tunnel Status

Get ngrok tunnel URL:

npx devall tunnel <service-name>

Examples:

npx devall tunnel frontend

Output: Tunnel URL and status

Agent usage:

• Get public URL
• Verify tunnel is active
• Share URL with team

Output Formats

DevAll CLI supports multiple output formats:

JSON (Default)

Machine-readable JSON output:

npx devall status frontend --format json

Agent recommendation: Use JSON for parsing responses

YAML

YAML format output:

npx devall status frontend --format yaml

Human

Human-readable output:

npx devall status frontend --format human

Default format is JSON, ideal for agent parsing.

Error Handling

Common Errors

”DevAll server is not running”

Cause: DevAll server is not started

Solution:

# Terminal 1: Start server
npx devall

# Terminal 2: Run CLI commands
npx devall list

“Service not found”

Cause: Service name doesn’t exist in config

Solution:

1. List available services: npx devall list
2. Use exact service name from list
3. Check configuration: npx devall config

”Port already in use”

Cause: Another process is using the port

Solution:

1. Check port usage: npx devall ports
2. Stop conflicting process
3. Or change port in config

Command timeout

Cause: Server not responding

Solution:

1. Check server is running
2. Verify server URL: --server-url http://localhost:7777
3. Check firewall settings

Agent Workflows

Workflow 1: Start Development Environment

# 1. Check what services exist
SERVICES=$(npx devall list)

# 2. Start essential services
npx devall start frontend
npx devall start backend
npx devall start database

# 3. Verify they're running
npx devall status frontend
npx devall status backend
npx devall status database

# 4. Check for errors
npx devall errors frontend
npx devall errors backend

Workflow 2: Diagnose Service Issue

# 1. Check service status
npx devall status backend

# 2. View recent logs
npx devall logs backend 100

# 3. Check for errors
npx devall errors backend 50

# 4. Check resource usage
npx devall info backend

# 5. Restart if needed
npx devall restart backend

# 6. Verify it's working
npx devall health backend

Workflow 3: Deploy Configuration Changes

# 1. Validate new config
npx devall validate

# 2. Restart affected services
npx devall restart --all

# 3. Check all are running
npx devall health

# 4. Monitor logs for issues
npx devall logs frontend 50
npx devall logs backend 50

Workflow 4: Debug Port Conflict

# 1. Check port usage
npx devall ports --process

# 2. Stop conflicting service
npx devall stop backend

# 3. Verify port is free
npx devall ports

# 4. Start service again
npx devall start backend

# 5. Confirm it's running
npx devall status backend

Workflow 5: Share Local Service

# 1. Verify service is running
npx devall status frontend

# 2. Expose via ngrok
npx devall expose frontend

# 3. Get public URL
npx devall tunnel frontend

# 4. Share URL with team
# URL is in JSON response

# 5. Stop exposing when done
npx devall unexpose frontend

Best Practices for Agents

1. Always Check Server Status First

Before running any command, verify DevAll is running:

npx devall health

If it fails, instruct user to start DevAll.

2. Use Service Names from List

Don’t guess service names. Always get them from:

npx devall list

3. Parse JSON Output

Use --format json (default) for consistent parsing:

STATUS=$(npx devall status frontend --format json)
# Parse JSON in your agent code

4. Handle Errors Gracefully

Check command exit codes and output:

if npx devall start frontend; then
  echo "Service started successfully"
else
  echo "Failed to start service"
  npx devall errors frontend
fi

5. Wait After State Changes

After starting/stopping services, wait 2-3 seconds before checking status:

npx devall start frontend
sleep 3
npx devall status frontend

6. Use Specific Commands

Use the most specific command for the task:

• ✅ npx devall errors frontend - Get errors only
• ❌ npx devall logs frontend | grep error - Unnecessary filtering

7. Provide Context to Users

When reporting status, include relevant details:

The frontend service is running on port 3000 (PID: 12345).
It has been up for 5 minutes and 23 seconds.
No errors detected in recent logs.

8. Suggest Next Steps

After diagnosing issues, suggest solutions:

The backend service crashed with this error:
"ECONNREFUSED: Connection refused to database on port 5432"

This suggests the database service is not running.
Would you like me to start the database service?

Why Use AGENTS.md or CLAUDE.md?

Adding DevAll instructions to AGENTS.md or CLAUDE.md has several advantages:

Advantages Over MCP

• Simpler setup: No configuration files, no building, just copy-paste
• Works everywhere: Compatible with all AI coding agents, not just Claude Code
• Project-specific: Instructions are version-controlled with your project
• No dependencies: Doesn’t require MCP server to be running
• Easier debugging: AI agents execute CLI commands you can see and test

When to Use MCP Instead

Consider using MCP integration if you:

• Use Claude Code exclusively
• Want natural language control without CLI syntax
• Need real-time function calling
• Prefer deeper tool integration

For most use cases, the AGENTS.md/CLAUDE.md approach is simpler and sufficient.

Advanced Usage

Custom Server URL

Connect to DevAll on a non-default port:

npx devall list --server-url http://localhost:8888

JSON Parsing Examples

Parse status in bash:

STATUS=$(npx devall status frontend --format json)
IS_RUNNING=$(echo $STATUS | jq -r '.status')

if [ "$IS_RUNNING" = "running" ]; then
  echo "Service is running"
fi

Parse in Python:

import subprocess
import json

result = subprocess.run(
    ['npx', 'devall', 'status', 'frontend'],
    capture_output=True,
    text=True
)

status = json.loads(result.stdout)
if status['status'] == 'running':
    print(f"Service is running on port {status['port']}")

Parse in Node.js:

const { execSync } = require('child_process');

const output = execSync('npx devall status frontend').toString();
const status = JSON.parse(output);

if (status.status === 'running') {
  console.log(`Service is running on port ${status.port}`);
}

Troubleshooting Guide for Agents

Issue: Commands hang or timeout

Diagnosis:

# Check if server is running
curl http://localhost:7777/api/health

Solution:

• Ensure DevAll server is started: npx devall
• Check firewall settings
• Verify port 7777 is not blocked

Issue: “Command not found: devall”

Diagnosis:

# Check if devall is installed
npm list -g devall

Solution:

• Install globally: npm install -g devall
• Or use npx: npx devall

Issue: Service won’t start

Diagnosis:

# Check detailed status
npx devall info <service>

# Check for port conflicts
npx devall ports

# View error logs
npx devall errors <service>

Solution:

• Check if port is in use
• Verify service configuration
• Check system resources
• Review error logs for specific issues

Issue: Can’t find service

Diagnosis:

# List all services
npx devall list

# Check configuration
npx devall config

Solution:

• Use exact service name from list
• Check service is defined in config
• Validate configuration: npx devall validate

Example Agent Implementations

Cursor Agent

When working with DevAll:
1. Check service list: `npx devall list`
2. Use exact service names from list
3. Always check status before starting: `npx devall status <service>`
4. View logs when debugging: `npx devall logs <service> 100`
5. Parse JSON output for consistent results

Aider Instructions

# DevAll Commands

Available services: Run `npx devall list`

To start service: `npx devall start <service>`
To stop service: `npx devall stop <service>`
To check status: `npx devall status <service>`
To view logs: `npx devall logs <service> [lines]`
To restart: `npx devall restart <service>`

Always verify DevAll server is running first.

Windsurf Agent

DevAll service management:
- List services: `npx devall list`
- Service status: `npx devall status <service>`
- Start service: `npx devall start <service>`
- Stop service: `npx devall stop <service>`
- View logs: `npx devall logs <service> 100`
- Check errors: `npx devall errors <service>`

Output is JSON by default. Parse accordingly.

Resources

• DevAll CLI Documentation
• Configuration Guide
• MCP Integration
• Claude Code Integration

Support

If you encounter issues:

1. Check DevAll server is running
2. Verify command syntax: npx devall --help
3. Check service names: npx devall list
4. Review logs: npx devall logs <service>
5. Report issues: GitHub Issues