@contextcompany/pi

Instrumentation and a Pi extension for the Pi Agent SDK.

Quick Start

Pi CLI extension

Install the package as a Pi extension:

pi install npm:@contextcompany/pi

Set your API key:

export TCC_API_KEY="your_api_key"

Start Pi as usual. The extension automatically records Pi agent runs, messages, and tool executions. Run /tcc-status inside Pi to confirm the extension is active.

To attach metadata to extension runs, add .pi/tcc.json to your project:

{
  "metadata": {
    "userId": "user-123",
    "environment": "staging",
    "tcc.sessionId": "conversation-123",
    "tcc.conversational": true
  }
}

Programmatic SDK instrumentation

1. Install

pnpm add @contextcompany/pi

2. Set your API key

export TCC_API_KEY="your_api_key"

3. Instrument your session

import { instrumentPiSession } from "@contextcompany/pi";
import { createAgentSession } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession();

instrumentPiSession(session, {
  sessionId: "conversation-123",
  conversational: true,
});

await session.prompt("What files are in the current directory?");

Configuration

instrumentPiSession(session, {
  apiKey: "tcc_abc123",
  sessionId: "conversation-123",
  conversational: true,
  metadata: { userId: "user-123" },
  debug: true,
});

| Option | Type | Default | Description | | ---------------- | ------------------------- | ----------------- | --------------------------- | | apiKey | string | TCC_API_KEY env | TCC API key | | runId | string | Auto-generated | Fixed run ID for all runs | | sessionId | string | — | Group related runs together | | conversational | boolean | — | Mark as conversational flow | | metadata | Record<string, unknown> | — | Custom metadata per run | | debug | boolean | false | Enable debug logging |

Environment Variables

| Variable | Description | | -------------- | ---------------------------------------------------------- | | TCC_API_KEY | Your Context Company API key | | TCC_DEBUG | Enable debug logging for SDK and extension instrumentation |