Skip to content

Document worker logging scenarios for POSIX shells and PowerShell #58

Description

@highbyte

Documentation gap

The worker documentation explains stdout/stderr, color behavior, and durable redirection, but the examples in docs/reference/worker.md are POSIX-shell-specific. Wrighty also supports Windows, where PowerShell uses different syntax for redirection, background execution, and teeing output.

This can leave operators unsure how to retain unattended-worker logs or show output in the terminal while also writing it to a file.

Suggested documentation

Add a concise Common logging scenarios subsection under Terminal color and machine output, with tested examples for POSIX shells and PowerShell covering:

  • terminal output only;
  • terminal output plus an appended combined log (tee / Tee-Object);
  • background execution with durable logs;
  • NDJSON stdout with stderr stored separately;
  • preserving the Wrighty exit code when output passes through a tee pipeline;
  • service-managed logging, where the process manager owns capture and retention.

Also clarify that:

  • Wrighty does not create, rotate, or retain conventional log files itself;
  • lifecycle events and heartbeats go to stdout, while warnings and errors go to stderr;
  • combining the streams loses that distinction;
  • --color never is recommended for durable human-readable logs;
  • Wrighty intentionally does not log the agent transcript, model reasoning, or tool calls.

Non-goals

  • Adding a --log-file option or changing worker logging behavior.
  • Implementing log rotation or retention.
  • Providing complete launchd, systemd, or Windows service installation guides.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions