# systemg
> systemg is an agent-friendly general process composer: a single `sysg` binary that
> starts, supervises, restarts, inspects, and logs local service graphs defined
> in YAML. It is useful for development environments, local stacks, CI jobs,
> cron-style units, and agent-managed workflows.
Current release: `0.56.1`
Primary links:
- Documentation: https://sysg.dev
- Quickstart: https://sysg.dev/quickstart
- Installation: https://sysg.dev/installation
- Upgrading sysg: https://sysg.dev/installation/upgrading
- Commands: https://sysg.dev/how-it-works/commands
- Logs command: https://sysg.dev/how-it-works/commands/logs
- Status command: https://sysg.dev/how-it-works/commands/status
- Configuration: https://sysg.dev/how-it-works/configuration
- Validate command: https://sysg.dev/how-it-works/commands/validate
- Claude Code integration: https://sysg.dev/integrations/claude-code
- Debugging method: https://github.com/ra0x3/systemg/blob/main/DEBUGGING.md
- Repository: https://github.com/ra0x3/systemg
## Agent-Friendly Usage
Use `--plain` for scripts, pipes, SSH sessions, and coding agents:
```sh
sysg --plain status
sysg --plain status --format json
sysg --plain inspect -s api --format json
sysg --plain logs -s api --format json
```
`--plain` sets `SYSTEMG_AGENT=1` for the current process. Agent mode is also
enabled when `SYSTEMG_AGENT` or `NO_COLOR` is set. In agent mode, systemg avoids
color, banners, paging, truncation, and accidental log-following where possible.
## Commands LLMs Should Prefer
- `sysg validate -c <file>`: check a manifest before running it. Exits `0` when
valid, `1` otherwise. Add `--format json` for structured diagnostics with the
line, column, category, message, and suggested fix. Run this after writing or
editing any config.
- `sysg --plain status`: human-readable, non-interactive status with full unit
names.
- `sysg status --format json`: structured supervisor status for parsing.
- `sysg inspect -s <unit> --format json`: structured details for one service or
cron unit.
- `sysg logs -s <unit> --format json`: JSON-lines logs with `{ts, stream,
service, line}` fields.
- `sysg logs -s <unit> --raw`: application log lines without systemg timestamp
or stream prefixes.
- `sysg logs -s <unit> --grep ERROR --since 2h`: filtered one-shot log query.
- `sysg logs --path` or `sysg logs -s <unit> --path --all`: locate active and
rotated log files for external tooling.
Manifest schema `2` is required. One resident supervisor can own many projects.
For `logs`, bare `-s <unit>` targets only the loose bundle; include
`-p <project>` for every project-owned unit. Other service selectors require
`-p` when the name is ambiguous. A foreground `start` attaches to one project,
and Ctrl-C stops only that project.
Health-check failures use SG0022 (unreachable), SG0023 (probe timeout), or
SG0104 (reported unhealthy). `attempt_timeout` bounds one probe;
`total_timeout` bounds the readiness window.
Supervisor-wide log caps and lifecycle defaults live in `supervisor.xml`.
Persisted and command-output XML is nested and two-space indented; compact
legacy XML remains readable.
## Log Behavior
As of `0.50.0`, `sysg logs` is safe for non-interactive callers by default. It
follows logs only when stdout is an interactive terminal and agent mode is not
enabled. In pipes, files, SSH commands, and agent sessions, it prints a one-shot
snapshot and exits. Use `--lines 0 --follow` when a long-running, new-lines-only
tail is intended; use `--no-follow` to force a one-shot snapshot on a terminal.
Useful log options:
- `--format json`: clean JSON-lines output for parsing.
- `--raw`: only the application's original line.
- `--strip-ansi`: remove terminal color and escape sequences.
- `--no-strip-ansi`: preserve recorded ANSI escapes.
- `--since`, `--until`: time-window logs by systemg capture timestamp.
- `--grep`: regex filter.
- `--all`: read active plus rotated history, oldest to newest.
## Install
```sh
curl --proto '=https' --tlsv1.2 -fsSL https://sh.sysg.dev/ | sh
```
Compatible releases after 0.56.0 replace a running supervisor by same-PID live
re-execution without restarting workloads. From 0.57.1 forward, compatibility
follows the live-reexec protocol and handoff schema rather than major/minor
version boundaries. Downgrades and contract changes require a stopped
supervisor.