Synced from pluk. This page is pulled from hivecommons/pluk@main during the docs build. Edit the canonical source in the pluk repository.

Pluk

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, 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

npm install -g @hivecommons/pluk

Optional: install rationguard only if you want pluk attach --rationguard. pluk never fetches it for you; without it on PATH (or --rationguard-bin), --rationguard exits with an error.

npm install -g @hivecommons/rationguard

Quick Start

One command to create a tmux session, start an AI CLI, and attach pluk event capture:

pluk attach my-agent --cli=claude

This does three things:

1. Creates a tmux session named my-agent
2. Attaches pluk via tmux pipe-pane to classify all terminal output, including start-up output
3. Starts claude inside it

To also wire up rationguard for real-time excuse detection (requires rationguard to be installed; see Install):

pluk attach my-agent --cli=claude --rationguard --rebuttal=send

This additionally starts rationguard watch to detect rationalizations and send rebuttals back.

To attach to an existing tmux session (e.g., one already running goose):

pluk attach my-agent --cli=goose

Note: When attaching to an existing session with --dangerous, the CLI may not have permission-skip enabled (the flag only applies when creating a new session). pluk will print a warning with the command to restart the CLI with the right flag. Likewise, --command, --cli-args and --dir only apply when creating a new session; pluk warns when they are passed to an existing one.

By default, pluk attaches to the tmux session. Without --rationguard, it attaches in the current terminal. With --rationguard on macOS (iTerm2 / Terminal.app), it opens a new terminal window; elsewhere it prints a tmux attach -t <session> hint, since rationguard runs in the foreground. Use --no-open to suppress this: without --rationguard the session is left detached and the attach hint is printed instead; with --rationguard it suppresses the new window (macOS) or the hint (elsewhere).

See What’s Running

pluk sessions

SESSION          CLI       STATE     TMUX  LAST ACTIVITY EVENTS
scanner          claude    working   ●     2s ago        1204
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, flags, health diagnostics, library API, event schema, and custom patterns.

# 1. Create a tmux session (don't start the CLI yet)
tmux new-session -d -s my-agent
 
# 2. Attach pluk to capture output before the CLI starts, so start-up
#    output (trust prompts, login, model banner) is classified too
export PLUK_RUN_DIR=/tmp/pluk-run
mkdir -p "$PLUK_RUN_DIR/logs"
tmux pipe-pane -t my-agent "PLUK_RUN_DIR=$PLUK_RUN_DIR pluk watch my-agent --cli=claude >> $PLUK_RUN_DIR/logs/my-agent.jsonl"
 
# 3. Start the AI agent inside the session
tmux send-keys -t my-agent "claude" Enter
 
# 4. Subscribe to events (another terminal)
export PLUK_RUN_DIR=/tmp/pluk-run
pluk subscribe my-agent --filter=state_change,rate_limit,error
 
# 5. Or start rationguard for real-time detection
rationguard watch my-agent --rebuttal=send
 
# 6. View the agent
tmux attach -t my-agent

CLI Commands

Unknown, misspelled, or wrong-subcommand --flags exit 2 (unknown flag --name for "pluk <cmd>" (see pluk <cmd> --help)) instead of being silently ignored. For example, pluk sessions --cli=claude is rejected: --cli belongs to attach, watch, and patterns, not sessions. Run pluk --help for the per-command flag lists.

Attach Flags

Watch, Subscribe and Sessions Flags

Health diagnostics (watch, subscribe)

{"pluk_diagnostics":1,"command":"watch","uptime_s":120,"final":false,"linesSeen":842,"framesPolled":0,"captureFailures":0,"classifyErrors":0,"inputErrors":0,"eventsEmitted":31,"emitErrors":0,"eventsFiltered":4}

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.

import { Classifier, getPatterns, subscribe, watch, discoverSessions, attach, send } from '@hivecommons/pluk';
 
// One-command setup: tmux + CLI + pluk + rationguard
attach({
  session: 'my-agent',
  cli: 'claude',
  rationguard: true,
  rebuttal: 'send',
  dangerouslySkipPermissions: true,
});
 
// Send text to a tmux session
send({ session: 'my-agent', text: 'check the build', enter: true });
 
// Discover running sessions
const sessions = discoverSessions('/tmp/pluk-run');
for (const s of sessions) {
  console.log(`${s.session}: ${s.cli} (${s.state}, ${s.lastActivityAgo})`);
}
 
// Classify individual lines
const patterns = getPatterns('claude');
const classifier = new Classifier({ session: 'my-agent', patterns });
const event = classifier.classify('● Read main.go');
// → { type: 'tool_call_started', data: { tool: 'Read', ... } }
 
// Subscribe to a JSONL log file (tail -f behavior)
const sub = subscribe('my-agent', (event) => {
  console.log(event.type, event.data);
}, { filter: ['rate_limit', 'error'] });
 
// Watch stdin for events
const watcher = watch({
  session: 'my-agent',
  cli: 'claude',
  onEvent(event) {
    if (event.type === 'rate_limit') {
      console.warn('Rate limited!', event.data.message);
    }
  },
});

Event Types

Event Schema

The JSONL event stream is pluk’s stable telemetry surface. pluk watch and pluk subscribe write one JSON object per line to stdout; diagnostic and human-readable output (pluk attach progress and warnings, errors, --diagnostics) goes to stderr.

{"v":1,"ts":"2026-01-01T00:00:00.000Z","seq":1,"pid":4242,"session":"my-agent","pane":"my-agent","source":"pluk","type":"state_change","data":{"to":"idle"}}

Existing fields and event types are not renamed or removed within a schema version; new event types and new data keys may be added, so consumers should ignore what they do not recognise. Counting events per type yields metrics such as classifier hits.

Send Command

Inject text into a running tmux session — used by rationguard to send rebuttals, or by you to send commands:

# Send text and press Enter
pluk send my-agent --text="check the build logs" --enter
 
# Send literal text (no key interpretation)
pluk send my-agent --text="hello world" --literal
 
# Also available as a standalone binary
pluk-send --session=my-agent --text="test" --enter

Standalone Binaries

In addition to the pluk <command> subcommand form, three standalone binaries are installed alongside pluk and behave the same as their subcommand equivalents:

Supported CLIs

Built-in event-classification pattern files exist for: Claude Code, GitHub Copilot CLI, Gemini CLI, Goose CLI, OpenAI Codex CLI, Aider, Oh My Pi (omp).

Custom patterns can be loaded from a directory with --patterns-dir or getPatterns(cli, patternsDir).

Pattern File Format

A pattern file is named <cli>.patterns (e.g. codex.patterns) and placed in the directory passed to --patterns-dir. Each non-blank, non-comment line is KEY='regex' — single or double quotes are both accepted, # starts a comment, and blank lines are ignored. Every value is compiled as a JavaScript RegExp source string, so use | for alternation (as in the bundled files below). A key that is omitted, empty, or fails to compile is simply disabled (treated as null) rather than raising an error.

Recognized keys:

Minimal example (codex.patterns):

# codex.patterns — minimal custom pattern file
IDLE_PATTERN='^\$ $'
WORKING_PATTERNS='Thinking|Generating'
ERROR_PATTERN='^\s*Error:|^\s*FATAL'

See patterns/*.patterns in this repo for complete, real-world examples.

Works With

• Hive — its container image installs pluk, and every agent’s tmux session is piped through pluk watch --include-raw into a per-session JSONL log under /var/run/pluk/logs/
• Crux — the agent runtime split out of Hive; when pluk is on PATH, it attaches pluk watch to each agent tmux session it launches
• @hivecommons/rationguard — real-time rationalization detection and rebuttal
• @hivecommons/promptargs — template variable substitution for AI prompts

Contributing

Contributions are welcome. CONTRIBUTING.md covers local setup, tests, and how to add or fix a CLI pattern set. If an agent CLI’s output is misclassified, or you want pluk to support a new CLI, open a pattern request. For questions, join the Hive Commons Discord.

License

Apache-2.0