agent-procs

Concurrent process runner for AI agents. Processes run in a background daemon and persist across CLI invocations.

Install

cargo install agent-procs

Quick start

# Start a process
agent-procs run "npm run dev" --name server

# Auto-restart on crash (up to 5 times)
agent-procs run "npm start" --name api --autorestart on-failure --max-restarts 5

# Restart when source files change
agent-procs run "npm run dev" --name server --watch "src/**"

# Wait for it to be ready
agent-procs wait server --until "Listening on" --timeout 30

# Check output
agent-procs logs server --tail 50

# See what's running
agent-procs status

# Stop it
agent-procs stop server

Config file

Create an agent-procs.yaml to manage multiple processes together:

session: myproject                          # optional — isolates this project's processes
proxy: true                                 # optional — enables reverse proxy
proxy_port: 9095                            # optional — pin proxy to a specific port

processes:
  db:
    cmd: docker compose up postgres
    ready: "ready to accept connections"
    autorestart: always
    max_restarts: 3
  api:
    cmd: ./start-api-server
    cwd: ./backend
    env:
      DATABASE_URL: postgres://localhost:5432/mydb
    ready: "Listening on :8080"
    port: 8080
    depends_on: [db]
    autorestart: on-failure
    watch:
      - "src/**"
      - "config/*"
    watch_ignore:
      - "*.generated.ts"

Processes start in dependency order; independent ones run concurrently.

agent-procs up                    # start all
agent-procs up --only db,api      # start specific ones
agent-procs down                  # stop all

Field reference

Per-process fields:

Top-level fields:

Reverse proxy

Give processes stable named URLs instead of port numbers. Opt-in via proxy: true in config or --proxy on the CLI.

$ agent-procs up
Proxy listening on http://localhost:9090
started api (http://api.localhost:9090)
started web (http://web.localhost:9090)

• Processes without an explicit port get one auto-assigned (4000-4999 range)
• PORT and HOST=127.0.0.1 are injected into the process env (user env takes precedence)
• Each session gets its own proxy port, so two projects can both have api without conflict

Ad-hoc usage without a config file:

agent-procs run "node server.js" --name api --port 3001 --proxy
# → http://api.localhost:9090

Commands

Restart policies

Automatically recover from crashes without agent intervention.

# Restart on non-zero exit, up to 5 times with 2s delay
agent-procs run "npm start" --name api \
  --autorestart on-failure --max-restarts 5 --restart-delay 2000

# Always restart (even clean exits), unlimited attempts
agent-procs run "worker" --name bg --autorestart always

When max_restarts is exhausted, the process enters Failed state. Manual stop disables auto-restart; restart re-enables it and resets the count.

Supervisor annotations ([agent-procs] Restarted, Max restarts exhausted) are written to disk logs and visible in logs --tail, --follow, and the TUI.

File watch mode

Auto-restart processes when source files change.

agent-procs run "npm run dev" --name server --watch "src/**" --watch "config/*"

• Uses OS-native file watching (FSEvents on macOS, inotify on Linux) with 500ms debounce
• .git, node_modules, target, and __pycache__ are always ignored
• Add --watch-ignore "*.log" for additional ignore patterns
• Watch restarts reset the restart count (they're intentional, not crashes)
• File changes can revive a Failed process

Sessions

Use --session to isolate process groups (e.g. per-project):

agent-procs --session projectA run "make serve" --name app
agent-procs --session projectB run "make serve" --name app
agent-procs --session projectA status   # only shows projectA's processes

Architecture

The CLI communicates with a per-session background daemon over a Unix domain socket. The daemon manages process lifecycles, captures stdout/stderr to log files, handles wait conditions, and supervises processes with restart policies and file watchers. The daemon auto-starts on first use and exits when all processes are stopped.

Exit codes