Expose real-time context/usage metrics in the Copilot SDK

Open
#1,516 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Domain
api, documentation

Research direction

Start by reviewing the SDK documentation for session.usage_info, assistant.usage, session.idle, and compaction or lifecycle events, then compare those surfaces with the CLI’s /context and /usage commands. Done means the SDK documents stable on-demand context and usage APIs, explains event persistence and resume behavior, and defines the relevant lifecycle event schemas.

Written by the indexing model from the issue text.

Description

enhancement

Summary

Today the Copilot CLI provides /context and /usage as first-class UX commands, but the SDK docs do not expose an equivalent stable API for apps to fetch the same information directly.

This makes it hard to build a UI that shows live session context pressure, token usage, and compaction status in real time or near-real time. The closest available surfaces appear to be streaming events like session.usage_info, assistant.usage, and compaction/session lifecycle events, but these are event-based and ephemeral rather than a documented queryable API.

Request

  • Add a documented SDK method or session API for retrieving current context/window usage on demand.
  • Add a documented session usage API for current/aggregate token and cost metrics.
  • Clarify which usage events are ephemeral vs persisted and what is available after resume.
  • Provide a stable event/schema contract for session.idle and related lifecycle events.

Why this matters

  • Enables apps to render accurate live context bars and usage dashboards.
  • Avoids relying on internal/undocumented event shapes.
  • Makes Copilot SDK easier to integrate into production UIs.

Docs gap noted

  • The SDK docs mention session.usage_info and assistant.usage, but there is no explicit “fetch current context usage now” API like the CLI’s /context command.
  • session.idle appears to have inconsistent payload documentation across pages.
Dominant language
Java
Stars
10.5k
Forks
1.5k
Avg merge
1d 12h
Merged PRs (30d)
133

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/copilot-sdk

All issues in github/copilot-sdk

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.