Metadata-Version: 2.4
Name: clawmonitor
Version: 0.1.8
Summary: Real-time OpenClaw session monitor (TUI) with Gateway log correlation and manual progress nudges.
Author: OpenClaw community
License-Expression: MIT
Project-URL: Homepage, https://github.com/openclawq/clawmonitor
Project-URL: Repository, https://github.com/openclawq/clawmonitor
Project-URL: Issues, https://github.com/openclawq/clawmonitor/issues
Keywords: openclaw,monitoring,tui,observability,feishu,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: license-file

# ClawMonitor

English | [简体中文](README.zh-CN.md)

![ClawMonitor TUI](docs/clawmonitor.png)

![ClawMonitor loading screen](docs/clawmonitor_loading.png)

Real-time **OpenClaw** session monitor with:

- Per-session last inbound **user** message + last outbound **assistant** message (preview + timestamp)
- Work state: WORKING / FINISHED / INTERRUPTED / NO_MESSAGE (+ NO_FEEDBACK alert)
- Long-run visibility via `*.jsonl.lock` (works even if Gateway is down)
- Optional Gateway log tail + channel runtime snapshot correlation (Feishu/Telegram-focused rules)
- Full-screen TUI with manual “nudge” (send a progress request via `chat.send`)

## Install (editable)

```bash
cd ~/program/clawmonitor
python3 -m pip install -e .
```

## Install (PyPI)

```bash
pip install clawmonitor
```

## Run

```bash
clawmonitor init
clawmonitor tui
```

Other commands:

```bash
clawmonitor snapshot --format json
clawmonitor snapshot --format md
clawmonitor nudge --session-key 'agent:main:main' --template progress
clawmonitor nudge --session-key 'agent:main:main' --template continue
clawmonitor push --session-key 'agent:main:main' --dry-run
clawmonitor status
clawmonitor status --detail
clawmonitor status --format json
clawmonitor status --format md
clawmonitor status --format md --detail
clawmonitor cron
clawmonitor tree
clawmonitor report --session-key 'agent:main:main' --format both
clawmonitor watch --interval 1
```

## Configuration

Default config path:

- `~/.config/clawmonitor/config.toml`

Example config is in `config.example.toml`.

### Optional labels

You can assign human-friendly names to long session keys (e.g. Feishu `ou_...`).
See the `[labels]` section in `config.example.toml`.

Runtime data (NOT stored in this repo):

- Logs: `~/.local/state/clawmonitor/events.jsonl`
- Reports: `~/.local/state/clawmonitor/reports/`
- Cache: `~/.cache/clawmonitor/`

## Keys (TUI)

- `↑/↓`: move selection
- `Enter`: nudge selected session (choose template)
- `?`: show help overlay
- `x`: focus filter (hide stale sessions)
- `t`: toggle tree view (group by agent)
- `c`: toggle cron jobs in tree view
- `R`: rename/label selected session (writes `[labels]` in config)
- `n`: toggle NODE label mode (channel:label)
- `l`: toggle related logs panel
- `d`: re-run diagnosis for selected session
- `e`: export a redacted report for selected session
- `r`: force refresh
- `f`: cycle refresh interval
- `q`: quit

Rows are color-coded when your terminal supports colors (`OK` green, `RUN` cyan, `IDLE` yellow, `ALERT` red).
In the details panel, `Task:` / `Thinking:` lines are highlighted (magenta when supported).

## Telegram note: ACP “thread bindings”

OpenClaw can route a Telegram chat to a different session key via local *thread bindings*.
This may make it look like your “main” session stopped receiving messages.

ClawMonitor detects this and flags it:

- `BOUND_OTHER` in `clawmonitor status`
- `BIND` in the TUI list

Relevant files/settings:

- Thread bindings: `~/.openclaw/telegram/thread-bindings-default.json`
- Config toggle: `~/.openclaw/openclaw.json` → `channels.telegram.threadBindings.spawnAcpSessions`

## First run

If no config file exists, most commands will offer to run the init wizard (interactive terminals only).

See `docs/launch-post.md` for a longer intro.

## Notes

- ClawMonitor never prints or writes OpenClaw secrets. It avoids dumping `openclaw.json` and redacts suspicious token-like strings in logs/reports.
- If Gateway is unreachable, ClawMonitor still works in offline mode (sessions/transcripts/locks/delivery-queue) but disables log tail + nudge.
- If your terminal window is narrow, `clawmonitor tui` may hide the details panel; use `clawmonitor status` as a stable fallback.
- For ClawHub import, see `docs/clawhub-skill.md` and `skills/claw-monitor/SKILL.md`.

See `CONTRIBUTORS.md` for acknowledgements.
