@ssdavidai/zooks

Hooks for Zo Computer. Intercepts messages sent to and received from the Zo API (/zo/ask) by running a local HTTPS proxy — no modifications to Zo source code required.

Zooks uses /etc/hosts to redirect api.zo.computer to a local proxy that fires PreToolUse and PostToolUse events around every API call, then forwards traffic to the real endpoint transparently.

Install

npm install -g @ssdavidai/zooks

Quick Start

# Generate certs, configure /etc/hosts, resolve upstream IPs
zooks setup

# Start the interceptor proxy (foreground)
zooks start

# In another terminal, Zo API calls are now intercepted
# You'll see PreToolUse and PostToolUse log entries for every /zo/ask call

How It Works

Zo services (Python/Bun/Node)
  → fetch("https://api.zo.computer/zo/ask")
  → /etc/hosts resolves api.zo.computer to 127.0.0.1
  → zooks proxy (HTTPS :443)
  → PreToolUse event fires
  → request forwarded to real api.zo.computer IP
  → PostToolUse event fires
  → response returned to caller unchanged

Zooks resolves the real IP addresses of api.zo.computer before adding the /etc/hosts redirect, then forwards all traffic to those IPs with the correct Host header and TLS SNI. A locally-generated CA certificate is added to the system trust store so all runtimes (Python requests, Node, Bun) trust the proxy without extra configuration.

CLI

zooks setup       # Generate certs, add CA to trust store, add /etc/hosts entry
zooks start       # Start proxy on :443 (foreground)
zooks start --daemon                # Background mode
zooks start --log-file /var/log/zooks.log  # Custom log file location
zooks stop        # Stop the daemon
zooks status      # Show proxy status, cert status, /etc/hosts, resolved IPs
zooks logs        # Live tail of intercepted events with color formatting
zooks logs --raw  # Raw JSON lines (no formatting)
zooks teardown    # Remove /etc/hosts entry, certs, and ~/.zooks/

zooks start will auto-run setup if certs or /etc/hosts aren't configured yet.

All intercepted events are logged to ~/.zooks/zooks.log. Run zooks logs in a separate terminal to watch events in real time as they flow through the proxy.

Events

Zooks exposes two events:

PreToolUse

Fires when a message is submitted to the Zo API, before the request is forwarded upstream.

interceptor.on('PreToolUse', (event) => {
  // event:
  // {
  //   timestamp: '2025-01-15T10:30:00.000Z',
  //   input: 'the input sent to /zo/ask',
  //   conversation_id: '...',
  //   headers: { authorization: '...', ... },
  //   method: 'POST',
  //   url: '/zo/ask'
  // }
});

PostToolUse

Fires when a response is received from the Zo API, before it's returned to the caller.

interceptor.on('PostToolUse', (event) => {
  // event:
  // {
  //   timestamp: '2025-01-15T10:30:01.500Z',
  //   status: 200,
  //   output: 'the response from Zo',
  //   conversation_id: '...',
  //   duration_ms: 1500
  // }
});

Library API

Use zooks programmatically in your own Node.js scripts:

import { createInterceptor } from '@ssdavidai/zooks';

const interceptor = createInterceptor({
  logFile: '/var/log/zooks.log', // optional, defaults to stdout
});

interceptor.on('PreToolUse', (event) => {
  console.log('Input sent:', event.input);
});

interceptor.on('PostToolUse', (event) => {
  console.log('Response received:', event.output, `(${event.duration_ms}ms)`);
});

await interceptor.start();

Log Format

Each intercepted call produces two structured JSON log lines:

{"timestamp":"...","direction":"PreToolUse","conversation_id":"...","preview":"first 120 chars of input"}
{"timestamp":"...","direction":"PostToolUse","status":200,"conversation_id":"...","preview":"first 120 chars of response","duration_ms":1500}

Setup Details

zooks setup does the following:

1. Resolves the real IP addresses of api.zo.computer via DNS and caches them in ~/.zooks/resolved-ips.json
2. Generates a local CA and server certificate for api.zo.computer using OpenSSL, stored in ~/.zooks/certs/
3. Appends the CA certificate to /etc/ssl/certs/ca-certificates.crt so Python, Node, and Bun trust the proxy
4. Adds 127.0.0.1 api.zo.computer # zooks to /etc/hosts

zooks teardown reverses all of the above.

Requirements

• Node.js >= 22
• OpenSSL (for certificate generation)
• Root access (for /etc/hosts and port 443)

License

MIT