@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