Deterministic process supervisor for AI agents.
Token budgets, rate limits, and abort control.

Niki wraps any AI agent command and enforces hard limits. When the agent exceeds its budget, timeout, or rate limit, niki kills it. No negotiation.

npm install -g @tjamescouch/niki

niki [options] -- <command> [args...]

The -- separator is required. Everything before it is niki config, everything after is the command to supervise.

# Basic: 500k token budget, 1 hour timeout
niki --budget 500000 --timeout 3600 -- claude -p "your prompt" --verbose

# Strict: rate-limit sends and tool calls
niki --budget 1000000 --max-sends 5 --max-tool-calls 20 -- claude -p "..." --verbose

# With external abort file (touch this file to kill the agent)
niki --budget 500000 --abort-file /tmp/niki-12345.abort -- claude -p "..." --verbose

# With logging and state output
niki --budget 500000 --log /tmp/niki.log --state /tmp/niki-state.json -- claude -p "..."

1. Niki spawns the child command, inheriting stdin and stdout
2. Stderr is captured and parsed for token counts and tool calls
3. Token usage is tracked via high-water-mark (monotonically increasing)
4. Tool calls and sends are rate-limited with a sliding 60-second window
5. When any limit is exceeded, niki sends SIGTERM, waits the cooldown period, then SIGKILL
6. On exit, niki writes a state summary and exits with the child's exit code

When --state is provided, niki writes a JSON snapshot on exit:

{
  "startedAt": "2026-02-09T12:00:00.000Z",
  "pid": 12345,
  "tokensIn": 45000,
  "tokensOut": 12000,
  "tokensTotal": 57000,
  "toolCalls": 42,
  "sendCalls": 8,
  "exitCode": 0,
  "killedBy": null,
  "duration": 1234
}

When --metrics is provided, niki appends one JSON line per session exit. The file grows across restarts, giving you a full history:

# View last 5 sessions
tail -5 /tmp/niki-metrics.jsonl | jq .

# Total tokens across all sessions
cat /tmp/niki-metrics.jsonl | jq -s '[.[].tokensTotal] | add'

# Sessions killed by reason
cat /tmp/niki-metrics.jsonl | jq -s 'group_by(.killedBy) | map({reason: .[0].killedBy, count: length})'

Each line contains the full session state plus endedAt, budget, and timeoutS for context.

killedBy is one of: "budget", "timeout", "rate-sends", "rate-tools", "abort", or null (clean exit).

• Never logs API tokens, environment variables, or message content
• Diagnostics contain only counters and timestamps
• Credentials flow through inherited env, never in CLI args
• State file contains only operational metrics

MIT

Photo: Unsplash (stylized)