dotfiles/home/.agents/skills/process-compose/SKILL.md

name, description

name	description
process-compose	Inspect a running process-compose project read-only. Use when the user asks what services/processes are running, whether a service is up or healthy, what state a process is in, or to read a service's recent log output — or mentions process-compose (pc) by name.

Inspecting process-compose

The process-compose CLI is a thin client. It does not read your config or processes directly — it queries a process-compose server that is already running (the one started by process-compose up). Every command below talks to that server over TCP, default localhost:8080.

This skill is read-only: never start, stop, restart, or scale processes.

Connecting

• Default target is localhost:8080. If a project runs on another port, pass -p PORT (or set PC_PORT_NUM); the port is whatever that project's process-compose.yaml / launch command set.
• A "connection refused" error means no server is running on that port, not a bad command. Report that the project isn't up rather than retrying variants.
• pc is a fish abbreviation for process-compose and exists only in an interactive fish shell. In scripts and Bash calls use the full process-compose.

Read commands

List every process with its status (one line each):

process-compose process list -o wide

Add -o json when you need to parse fields (status, health, pid, restarts, exit code) rather than display them.

Full state of one process:

process-compose process get NAME -o json

Recent log lines for a process (tail the last N — adjust the number to the need):

process-compose process logs NAME -n 100

Multiple processes: comma-separate them (proc1,proc2). A whole namespace: -N NAMESPACE.

Whole-project state (is everything ready):

process-compose project state

Never do

• No TUI. Bare process-compose, up, and attach launch the interactive full-screen TUI and hang a non-interactive shell. Always use a subcommand.
• No -f / --follow on logs — it streams forever and blocks. Use -n to pull a finite tail instead.
• No mutations — start, stop, restart, scale, down are out of scope for this skill.