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 classifies, subscribes to, and reacts to JSONL event streams from AI coding agent terminals.

Install

npm install -g @hivecommons/pluk

Quick Start command to create a tmux session, start an AI CLI, attach pluk event capture, and wire up rationguard for real-time excuse detection:

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

This does four things:

1. Creates a tmux session named my-agent
2. Starts claude inside it
3. Attaches pluk via tmux pipe-pane to classify all terminal output
4. Starts rationguard watch to detect rationalizations and send rebuttals back

To just attach pluk without rationguard:

pluk attach my-agent --cli=claude

To attach to an existing tmux session (e.g., 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 applies when creating a new session). pluk will print a warning with the command to restart the CLI with the right flag.

A new terminal window is always opened for the tmux session (unless --no-open is set), so you can interact with the agent directly.

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

Manual Setup

If you prefer to wire things up yourself:

# 1. Start an AI agent in tmux
tmux new-session -d -s my-agent
tmux send-keys -t my-agent "claude" Enter
 
# 2. Attach pluk to capture output
export PLUK_RUN_DIR=/tmp/pluk-run
tmux pipe-pane -t my-agent -o "pluk watch my-agent --cli=claude"
 
# 3. Subscribe to events (another terminal)
pluk subscribe my-agent --filter=state_change,rate_limit,error
 
# 4. Or start rationguard for real-time detection
rationguard watch my-agent --rebuttal=send
 
# 5. View the agent
tmux attach -t my-agent

Environment Variables

CLI Commands

Attach Flags

Health diagnostics (watch, subscribe)

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 that is repeatedly failing, add --diagnostics[=secs] (default every 60 s). It writes JSON line per period, plus a final on exit, to stderr — stdout stays pure event JSONL:

{"pluk_diagnostics":1,"command":"watch","uptime_s":120,"final":false,"linesSeen":842,"framesPolled":0,"captureFailures":0,"classifyErrors":0,"inputErrors":0,"eventsEmitted":31,"eventsFiltered":4}
``` fixed counter categories are reported — never the session name, raw
terminal output or any other user-provided value — and nothing is sent off-box.
The same counters are available programmatically via `watch(...).stats()` and
`Subscriber#stats()`.
 
## Programmatic API
 
```typescript
import { Classifier, getPatterns, subscribe, watch, discoverSessions, attach, send } from '@hivecommons/pluk';
 
//-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',(event) {
    if (event.type === 'rate_limit') {
      console.warn('Rate limited!', event.data.message);
    }
  },
});

Event Types

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.

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

• @hivecommons/rationguard — real-time rationalization detection and rebuttal
• @hivecommons/promptargs — template variable substitution for AI prompts
• hivecommons/pluk — the Go binary (this package is the TypeScript port)

License

Apache-2.0