Skip to main content

​
Context Compaction

import {
  estimateTokens,
  estimateMessageTokens,
  needsCompaction,
  truncateToolResults,
  buildCompactPrompt
} from "@open-gitagent/gitagent";

// Estimate tokens in a string
const tokens = estimateTokens("Hello world");  // ~3

// Check if compaction needed (triggers at 75% of context window)
// tokenEstimate is also returned and useful for logging
const { needed, ratio, tokenEstimate } = needsCompaction(messages, 200000);
if (needed) console.log(`Context at ${(ratio * 100).toFixed(0)}% — compaction needed`);

// Truncate oversized tool results (keeps first + last half)
const trimmed = truncateToolResults(messages, 10000);

// Build a summarization prompt for the LLM
const prompt = buildCompactPrompt(messages);
UtilityDescription
estimateTokensFast approximation: chars/4
needsCompactionTriggers at 75% of model context window
truncateToolResultsKeeps first and last half of large results
buildCompactPromptGenerates a prompt asking the LLM to summarize the conversation
Call needsCompaction before each turn in a long-running session and feed the output of buildCompactPrompt back into query() to keep token usage under control.

​
Cost Tracking

import { query } from "@open-gitagent/gitagent";

const result = query({ prompt: "...", dir: "..." });

for await (const msg of result) { /* ... */ }

const costs = result.costs();
// {
//   startTime: 1716825600000,
//   totalCostUsd: 0.05,
//   totalInputTokens: 5000,
//   totalOutputTokens: 2000,
//   totalRequests: 3,
//   modelUsage: {
//     "anthropic:claude-sonnet-4-6": {
//       inputTokens: 5000,
//       outputTokens: 2000,
//       cacheReadTokens: 0,
//       cacheWriteTokens: 0,
//       totalTokens: 7000,
//       requests: 3,
//       costUsd: 0.05
//     }
//   }
// }
console.log(`Session cost: $${costs.totalCostUsd.toFixed(4)}`);

SDK Reference

Full API reference for query(), tool(), buildTool(), and hooks

SDK Quickstart

Install the SDK and run your first query()

Telemetry

Emit session cost and token usage as OpenTelemetry metrics

Models & Providers

Configure per-model pricing used in cost calculations