Metadata-Version: 2.4
Name: ghostlogic-agent-watchdog
Version: 0.3.3
Summary: Forensic forwarder for AI-agent coding sessions (Claude Code, Codex CLI). Tick-batches transcripts and ships tamper-evident receipts to GhostLogic Blackbox.
Project-URL: Homepage, https://github.com/adam-scott-thomas/ghostlogic-agent-watchdog
Project-URL: Repository, https://github.com/adam-scott-thomas/ghostlogic-agent-watchdog
Project-URL: Issues, https://github.com/adam-scott-thomas/ghostlogic-agent-watchdog/issues
Project-URL: Changelog, https://github.com/adam-scott-thomas/ghostlogic-agent-watchdog/releases
Project-URL: Bug Tracker, https://github.com/adam-scott-thomas/ghostlogic-agent-watchdog/issues
Author-email: Adam Thomas <adamthomasdirect@gmail.com>
Maintainer-email: Adam Thomas <adamthomasdirect@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,audit,claude-code,codex-cli,evidence,forensics,logging,telemetry
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: ghostspine>=0.3.0
Requires-Dist: keyring>=24
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: windows
Requires-Dist: pywin32>=306; extra == 'windows'
Description-Content-Type: text/markdown

# 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.

Repository: `ghostlogic-agent-watchdog`. Plugin manifest name: `ghostlogic-agent-watchdog`. The daemon command remains `logicd`.

## Scope

- **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, `logicd install` registers an ONSTART scheduled task named `logicd` that runs as SYSTEM. macOS/Linux still print platform service instructions. 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.

## Windows Self-Serve Install

Run PowerShell as Administrator:

```powershell
python -m pip install --upgrade ghostlogic-agent-watchdog
logicd enroll --token gl_enroll_xxx --endpoint-name $env:COMPUTERNAME --agent-id logicd
logicd install
```

`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.

### 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) |

Override the default with `--data-dir`:

```bash
logicd enroll --token gl_enroll_xxx --data-dir /opt/ghostlogic
logicd install --data-dir /opt/ghostlogic
```

Legacy/manual mode is still available for operators who already have a scoped `gl_agent_*` key:

```bash
logicd install --legacy-api-key
```

## Run (foreground)

```bash
python -m logicd run --config /path/to/config.toml
```

Paths work the same on all three OSes; use your platform's path form.

## Naming Split

- Product and plugin display name: `GhostLogic Agent Watchdog`
- Repository: `ghostlogic-agent-watchdog`
- Package and plugin manifest name: `ghostlogic-agent-watchdog`
- Internal Python package and CLI module: `logicd`
- Internal config, unit, and label identifiers may still use `logicd` where stability matters

## License

Apache-2.0
