Node SDK

Node workers, Next.js build tasks, Deno/Bun scripts.

LiveSDKchirp login

The Node SDK mirrors the Python ergonomics - a `track` higher-order function, `ChirpAgent` manual lifecycle, and the same green/red end-state semantics. Zero runtime dependencies; ships TypeScript types out of the box. Works in Node ≥ 18 and any runtime that supports the package's Node APIs.

An additional `chirp/express` submodule ships an Express/Connect error middleware that sends one-shot notifications for uncaught server errors.

Prerequisites

Node ≥ 18 (or Bun/Deno).
Chirp installed on your phone, signed in.

Setup

1
Install + authenticate
Same one-time browser pairing as the Python SDK. CI uses CHIRP_API_KEY env var.
shell
```
npm install chirp
npx chirp login
```

Wrap an async function with `track()`

Higher-order pattern: track(opts, fn) returns a wrapped version of fn that owns an @agent activity lifecycle. Resolves green, rejects red.

deploy.ts

import { track } from 'chirp';

const deploy = track(
  { name: 'deploy', theme: '#22c55e' },
  async (env: string) => {
    await build();
    await push(env);
    await smoke(env);
  },
);

await deploy('prod');

Use `ChirpAgent` callback form for finer control

When you need to start/end the activity manually or branch the lifecycle.

typescript

import { ChirpAgent } from 'chirp';

const agent = new ChirpAgent({ name: 'sync', theme: '#22c55e' });
await agent.start();
try {
  await agent.update('halfway');
  await doWork();
  await agent.done('done');
} catch (err) {
  await agent.error('failed: ' + String(err));
  throw err;
}

Use `ChirpClient` for other schemas

The high-level wrapper uses the generic @agent card. When you want a schema-specific layout such as @deploy, use the low-level client directly.

typescript

import { ChirpClient } from 'chirp';

const chirp = new ChirpClient();

await chirp.activityStart('@deploy', {
  repo: 'my-app',
  stage: 'build',
  progress: 0.1,
});
await chirp.activityUpdate('@deploy', { stage: 'deploy', progress: 0.7 });
await chirp.activityEnd('@deploy', {
  data: { stage: 'done' },
  dismissalPolicy: { afterSeconds: 120 },
});

What you’ll see

Same lifecycle as Python: starts on entry, updates as you call `agent.update()`, ends green/red on resolution/rejection. Multiple concurrent calls each spawn their own activity instance.

Troubleshooting

I need a progress bar or another template-specific layout.: Use ChirpClient.activityStart, activityUpdate, and activityEnd with the built-in schema you want. track() and ChirpAgent intentionally target the generic @agent card.
Activity doesn't appear in production but works locally.: Check CHIRP_API_KEY is set in your production env, or that ~/.chirprc exists for the user running the process. The SDK throws a config error when no key is available.
I want Express error notifications.: Use the separate Express integration on this page. The exported chirpErrorNotifier middleware sends one-shot pushes for 5xx errors; it does not create a Live Activity per request.

Browse all integrations