Based on repository activity, growth velocity and community engagement.
27
Growth2/30
Activity7/25
Popularity1/25
Trust17/20
1
Stars
High
Sentiment
Votes
1
README.md
GhostLogic Agent Watchdog
GhostLogic Agent Watchdog is the product surface for the logicd collection daemon. It monitors local AI-agent coding sessions, including Codex CLI and Claude Code, seals them in rolling 10-minute ticks, and ships tamper-evident work receipts to GhostLogic Blackbox over HTTPS.
logicd remains the internal package, module, CLI, and service-runtime name. User-facing docs and plugin metadata should refer to GhostLogic Agent Watchdog.
Sources: Claude Code (~/.claude/projects/**/*.jsonl), Codex CLI (~/.codex/sessions/**/*.jsonl, ~/.codex/history.jsonl).
Capture model: tick-based. 10-minute ticks. Every event carries its tick_index; the server-side aggregator applies a 7-day rolling window as retention policy. The client does not enforce retention.
Transport:POST https://api.ghostlogic.tech/api/v1/ingest with Authorization: Bearer <key>.
Runtime: foreground Python process or a persistent platform launcher. On Windows, the installer registers a logon-triggered scheduled task named logicd that runs as the enrolling user (so it can read that user's keyring and ~/.claude + ~/.codex sessions — see F-WD-022). macOS/Linux register a per-user launchd LaunchAgent / systemd --user unit. Read-only on source files. ACL-locked config.
Platforms: Windows, macOS, Linux (all three).
Forensic posture:
SHA-256 on every source line.
Deterministic batch_id (sha256 of sorted event_ids) for idempotent retries and server dedupe.
Append-only hash-chained audit log (audit.log) of every forwarder activity.
Byte offsets advance only after a batch has been durably handled (shipped or dead-lettered). Process death before durability means the next run re-reads those bytes, so no data loss is expected.
Dead-lettered batches replay on startup with the original batch_id preserved.
Every event carries line_number, byte_offset, byte_end, sha256, source adapter, and captured_at_ns for pinpointable forensic mapping.
Privacy — what is transmitted
Private mode: transcript content is NOT transmitted. File paths, session IDs, hostname, OS username, per-line SHA-256 fingerprints, event subtype, and tool names ARE transmitted.
include_payload = false (the default, "private" mode) keeps the content of each transcript line on your machine. It does not mean nothing leaves the machine: the identity and topology fields above ship unconditionally so the server can prove an event existed without seeing its content. The transport is HTTPS-only — the daemon refuses to start against a non-https:// endpoint unless allow_insecure_url = true is set for local dev/staging (F-WD-019).
Set include_payload = true to ship full transcript bodies (still scanned by the redaction patterns in [privacy]).
(Event subtype and tool-name extraction land in P2a; named here so the disclosure does not lag the code.)
logicd enroll redeems the one-time gl_enroll_... token with https://api.ghostlogic.tech/api/v1/enroll, writes the scoped gl_agent_* key locally, and does not print the full key. logicd install uses the enrolled config and does not prompt for a raw API key.
Installer
For a one-command, fail-closed install/upgrade use the productized installer
(logicd-installer, which drives the bundled install.ps1). It runs the same
path for every host — including ours.
What it enforces (no flag combination can produce an unsafe state):
Single canonical launcher — scheduled task \logicd, run as the enrolling user (logon trigger; F-WD-022). One name, ever.
Dual-launcher detection (fail-closed) — if any other task references the daemon, or more than one task does, the install refuses. Migrate an existing host with a stray task (e.g. a hand-rolled \GitWitness) by running once with --force-remove-existing (removal is audit-logged). See F-WD-021.
HTTPS + UUID + keyring — api.url must be https://; endpoint_id must be the server-issued UUID (never the hostname); the key lives only in the OS keyring. Any violation rolls back.
Idempotent — re-running upgrades the package, preserves endpoint_id + key, verifies the task in place, and bounces the service. Never creates a second task.
Pre-install checks + 30s post-install health with rollback on any failure.
Flags
| Flag | Effect |
|---|---|
| --token gle_... | Enrollment token (required for fresh install / --reenroll). |
| --force-remove-existing | Remove non-canonical launchers (F-WD-021 migration), then install. |
| --dry-run | Run pre-install checks, print intended actions, change nothing. |
| --reenroll | Force re-enrollment even if a healthy install exists. |
| --data-dir <path> | Override the platform data directory. |
| logicd-installer uninstall | Remove task + config + pause sentinel. Preserves the keyring entry and audit.log (forensic record). |
Installer error codes
Every failure exits non-zero with a named code:
| Code | Meaning |
|---|---|
| NOT_ELEVATED (10) | Re-launch from an elevated PowerShell. |
| PYTHON_TOO_OLD (11) | Python 3.11+ required. |
| API_UNREACHABLE (12) | https://api.ghostlogic.tech/health did not return 200. |
| DUAL_LAUNCHER_DETECTED (13) | A non-canonical/extra launcher exists; re-run with --force-remove-existing. |
| TOKEN_FORMAT_INVALID (14) | Token must look like gle_.... |
| WHEEL_INSTALL_FAILED (20) | pip install failed. |
| IMPORT_VERIFY_FAILED (21) | import logicd failed post-install. |
| ENROLL_HTTP_ERROR (30) | Enrollment HTTP request failed. |
| ENROLL_RETURNED_HTTP_URL (31) | Server returned a non-HTTPS api.url (rolled back). |
| ENROLL_RETURNED_NON_UUID (32) | Server/config endpoint_id is not a UUID (rolled back, F-WD-020). |
| KEYRING_MIGRATE_FAILED (33) | Could not move the key out of the TOML into the keyring. |
| TASK_CREATE_FAILED (40) | Scheduled-task create/start/remove failed. |
| POST_INSTALL_HEALTH_FAILED (50) | Health check failed 30s after start (rolled back). |
| UNINSTALL_FAILED (60) | Uninstall step failed. |
The daemon-side allow_insecure_url (F-WD-019) is a daemon dev escape hatch, not an installer knob — the installer never accepts http://.
Default locations
| Platform | Config + state directory | ACL method | Service instructions |
|---|---|---|---|
| Windows | %PROGRAMDATA%\GhostLogic\ | icacls - SYSTEM + Administrators | Scheduled Task logicd |
| macOS | ~/Library/Application Support/GhostLogic/ | chmod 600 - owner only | launchd LaunchAgent (per-user) |
| Linux | $XDG_CONFIG_HOME/ghostlogic/ or ~/.config/ghostlogic/ | chmod 600 - owner only | systemd --user unit (or system unit for root install) |