devloop - Agent Feedback Loop CLI

devloop provides AI coding agents with a structured feedback loop for Ruby/Rails projects: run tests, manage dev servers, inspect logs, and smoke-test apps. All commands return JSON for easy agent parsing.

Built for exe.dev VMs, but works on any host with proper configuration.

Agents: See USAGE.md for a compact command reference.

Why devloop exists

Stock Rails tools are often too verbose or lack machine-friendly output. devloop wraps them to output structured JSON, making it easier for autonomous agents to maintain a tight feedback loop.

Usage

usage: devloop <command> [args...]    

Setup:                                
  detect                        Report detected host capabilities
  init                          Configure devloop and scan for projects
  add <path-or-name>            Add a project to devloop                     

Commands:                             
  list                          List configured projects               
  test <project> [path] [-f]    Run tests (minitest/rspec auto-detected) 
  server start|stop|status      Manage dev servers
  logs <project> [--lines N]    Fetch server logs (default: 50 lines)       
  check <project>               Run tests + start server + smoke test                  
  doctor                        Check environment health                     
  errors <project>              Fetch Sentry errors     
  inspect <url> <selector>      Inspect element styles via Puppeteer       

Configuration

Config files are loaded in this order:

1. DEVLOOP_CONFIG_FILE
2. ~/.config/devloop/config.json
3. <devloop-install-dir>/config.json

Per-project overrides can be placed at <project>/.devloop.json.

Example config.json:

{
  "projects_dir": "/home/user/projects",
  "port_range_start": 3000,
  "environment": {
    "os": "linux",
    "toolchain": "mise",
    "services": { "provider": "systemd" }
  },
  "projects": {
    "my-app": { "port": 3000 }
  }
}

Note: If no config exists, devloop scans DEVLOOP_PROJECTS_DIR (default: ~/projects) for directories with a Gemfile.

Output Format

Commands always return JSON indicating success/failure and details:

{
  "success": true,
  "command": "test",
  "project": "my-app",
  "summary": "42 tests, 0 failures",
  "details": { ... }
}

Commands Reference

• detect: Reports host capabilities (OS, Ruby toolchain, databases).
• init: Interactive setup to scan for projects and assign ports.
• add <path>: Adds a single project and auto-assigns a port.
• list: Lists configured projects.
• test <project> [path] [-f]: Runs Minitest or RSpec based on project structure. Fails populate failure_details.
• server start|stop|status <project>: Manages development servers via systemd or a foreground fallback.
• logs <project> [--lines N]: Returns recent server log output.
• check <project>: Runs tests, starts the server, and smoke-tests the HTTP response.
• errors <project>: Fetches unresolved issues from a Sentry-compatible service (needs sentry_project_id and token).
• doctor: Checks host environment health.
• inspect <url> <selector>: Inspects element styles (requires Node.js + Puppeteer).

(Note: devloop browse is deprecated; use native agent browser tools instead.)

Agent Workflow

1. Run devloop detect to inspect the host.
2. Update config.json if necessary.
3. Code and verify: devloop test <project>. Check success and failure_details.
4. Review: devloop server start <project> and use native browser tools to validate the UI.

Environment Variables

• DEVLOOP_PROJECTS_DIR: Fallback directory for scanning projects.
• DEVLOOP_LIB: Path for helper scripts (like inspect).
• SENTRY_DOMAIN & SENTRY_AUTH_TOKEN: Credentials for devloop errors.

devloop also sources project-level .env files before starting servers.

Portability

Works on Linux, macOS, and WSL. Requires Bash, Ruby, jq, and curl. Supports common Ruby toolchains (mise, rvm, rbenv, asdf, etc.).