homeboy observe

Last updated: May 4, 2026

Passively observe a running system and persist evidence in the observation store as run kind observe.

Usage

homeboy observe <component> --duration 30s --tail-log /path/to/app.log --grep 'invalid_grant'
homeboy observe <component> --duration 5m --watch-process 'opencode-ai/bin/.*serve'
homeboy observe <component> --duration 5m --watch-process 'node .*serve' --watch-process-interval 1s
homeboy observe <component> --duration 5m --tail-log /path/to/app.log --watch-process 'node .*serve'
homeboy observe <component> --duration 30s --probe '{"type":"http.poll","url":"http://127.0.0.1:3000/health","assert-status":200}'

V1 Scope

observe is a passive producer. It does not drive a scenario, attach to privileged OS probes, or own target lifecycle.

V1 supports:

--duration <duration> using ms, s, m, or h
--tail-log <path> for one or more log files
--grep <regex> to filter tailed log lines
--watch-process <regex> for process command-line polling
--watch-process-interval <duration> for process polling cadence; defaults to 1s
--probe <json> for repeatable portable trace probe configs (log.tail, process.snapshot, file.watch, port.snapshot, http.poll, and cmd.run)

Output

The command writes a trace-compatible JSON envelope to a run directory and records it as an artifact on an observation-store run:

json

{
  "component_id": "wp-coding-agents",
  "scenario_id": "observe",
  "status": "pass",
  "summary": "Passive observation timeline",
  "timeline": [
    { "t_ms": 0, "source": "observe", "event": "started" },
    { "t_ms": 251, "source": "log", "event": "line", "data": { "path": "/root/.kimaki/kimaki.log", "line": "HTTP 400 invalid_grant" } },
    { "t_ms": 0, "source": "process", "event": "matched", "data": { "pattern": "opencode-ai/bin/.*serve", "pid": "1234", "command": "node opencode-ai/bin/opencode serve" } },
    { "t_ms": 1002, "source": "process", "event": "spawn", "data": { "pattern": "opencode-ai/bin/.*serve", "pid": "1235", "ppid": "1234", "command": "node opencode-ai/bin/opencode serve" } },
    { "t_ms": 2004, "source": "process", "event": "exit", "data": { "pattern": "opencode-ai/bin/.*serve", "pid": "1235", "was_command": "node opencode-ai/bin/opencode serve" } }
  ],
  "assertions": [],
  "artifacts": []
}

Inspect persisted evidence with:

homeboy runs list --kind observe
homeboy runs show <run-id>
homeboy runs artifacts <run-id>

Use observe to gather live evidence before encoding a deterministic homeboy trace workload with assertions.

View on GitHub

homeboy observe

Usage

V1 Scope

Output

More in Commands

`homeboy file`

Audit Layer Ownership Rules

`homeboy wp`

`homeboy git`