From e005f2b1c1886577c1f0f49448382dfdcd090192 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 23:31:57 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20docs:=20explain=20purpose=20and?= =?UTF-8?q?=20first-session=20prerequisites?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson --- README.md | 38 +++++++++++++++++++++++++++++++++++--- ROADMAP.md | 13 +++++++++---- 2 files changed, 44 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 397d95f..0c7cce6 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,19 @@ [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) -Pluk classifies, subscribes to, and reacts to JSONL event streams from AI coding agent terminals. +Pluk turns an AI coding agent's terminal output into events, such as “agent is +idle” or “usage limit reached”. Other tools can read these events and decide +what to do. Events are stored as **JSONL**: one JSON record per line. ## Install Requirements: - Node.js 22 or newer -- tmux (`attach`, `send` and `watch --capture` drive tmux sessions) +- tmux, a tool that keeps terminal sessions running (`attach`, `send` and + `watch --capture` drive those sessions) +- For the live examples, an installed and authenticated coding-agent CLI + such as Claude Code; pluk does not install or sign in to it for you ```bash npm install -g @hivecommons/pluk @@ -69,9 +74,23 @@ helper claude idle ● 45s ago 892 goose-exp goose idle ○ 3m ago 156 ``` +## Reference: commands, integration, and event formats + +After your first session, use the sections below as needed: +[commands](#cli-commands), [flags](#attach-flags), +[health diagnostics](#health-diagnostics-watch-subscribe), +[library API](#programmatic-api), [event schema](#event-schema), and +[custom patterns](#pattern-file-format). + +
+Optional: wire tmux and event capture manually + ## Manual Setup -If you prefer to wire things up yourself: +**Advanced wiring; most users can stay with `attach`.** Data flows from the +agent's tmux pane → `pipe-pane` (tmux's output pipe) → `pluk watch` → a JSONL +log. `pluk subscribe` reads that log from another terminal. +The run directory must be the same in both terminals. ```bash # 1. Create a tmux session (don't start the CLI yet) @@ -106,6 +125,8 @@ tmux attach -t my-agent | `PLUK_LOG_KEEP_LINES` | `5000` | Keep up to this many trailing lines across rotation, within the `PLUK_LOG_MAX_BYTES` cap | | `PLUK_RATIONGUARD_BIN` | *(unset)* | Rationguard command for `pluk attach --rationguard` when it is not on `PATH`; same as `--rationguard-bin` | +
+ ## CLI Commands | Command | What it does | @@ -155,6 +176,9 @@ Unknown, misspelled, or wrong-subcommand `--flags` exit 2 (`unknown flag --name ### Health diagnostics (`watch`, `subscribe`) +
+Operator reference: counters and diagnostics intervals + `pluk watch` and `pluk subscribe` deliberately swallow capture-pane failures, input errors and malformed log lines so the pipe-pane process never dies. To tell a healthy quiet session from one that is repeatedly failing, add @@ -176,8 +200,16 @@ period above 2147483.647 seconds (about 24.9 days) have it capped at that value to stay within Node's timer limit; the CLI rejects out-of-range values as described above. +
+ ## Programmatic API +This example enables automatic messages and skips the launched CLI's permission +prompts. Both are optional: omit `rebuttal: 'send'` and +`dangerouslySkipPermissions: true` for a detection-only setup with normal +permission checks. Only bypass prompts in an environment you have deliberately +isolated and authorized. + ```typescript import { Classifier, getPatterns, subscribe, watch, discoverSessions, attach, send } from '@hivecommons/pluk'; diff --git a/ROADMAP.md b/ROADMAP.md index ae2fad6..e11906f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,6 +3,8 @@ Pluk turns AI-agent terminal output into structured events that downstream tools can consume. This roadmap describes the direction for the TypeScript package and its relationship with the wider Hive Commons agent-tooling stack. +For example, a `state_change` event can report that an agent went idle. +Logs use JSONL: one JSON record per line. ## Recently shipped @@ -16,20 +18,23 @@ package and its relationship with the wider Hive Commons agent-tooling stack. ## Near term -1. **Event schema evolution:** keep the JSONL envelope additive within schema +1. **Event schema evolution:** keep the JSONL envelope (fields around each event) + additive within schema version 1 and define the process for a version bump, so tools such as - rationguard can depend on it safely. + rationguard can depend on it safely: add fields without removing or changing + the meaning of existing ones within version 1. 2. **Broader CLI coverage:** add and test pattern packs for additional active agent CLIs as they become adoption-relevant. 3. **Operational hardening:** continue replacing tmux/terminal edge cases with - explicit diagnostics, non-zero exits for operator errors, and hermetic tests. + explicit diagnostics, non-zero exits for operator errors, and isolated tests + that do not depend on a real agent or external service. ## Implementation Pluk is a single TypeScript package published to npm as `@hivecommons/pluk`; there is no separate Go binary. Hive and other consumers shell out to the npm CLI and read its JSONL logs, so event shapes and user-facing semantics are the -compatibility surface. +compatibility surface — the behavior other tools depend on. ## Non-goals for now