Add read-only session introspection CLI command (e.g. context usage)

Resolved 💬 2 comments Opened Mar 3, 2026 by S1m Closed Mar 31, 2026

Problem

From within a running Claude Code session, there's no way for the agent to programmatically check its own context usage. The /context slash command exists but:

  1. It's only available as an interactive slash command — not exposed as a CLI subcommand
  2. Running claude context or claude /context from Bash inside a session fails because Claude Code blocks nested sessions
  3. There's no claude session info <id> or similar read-only command

This means agents cannot self-monitor context consumption, which would be useful for:

  • Long-running tasks: Agents could proactively split work before hitting context limits
  • Team/subagent coordination: A lead agent could monitor child agents' context usage and spawn replacements before they run out
  • User transparency: Agents could report context status when asked without requiring the user to run /context manually

Proposed Solution

A read-only CLI subcommand that reports session metadata without starting or entering a session:

# Query current session (when CLAUDECODE env var is set)
claude session info

# Query a specific session by ID
claude session info <session-id>

# Possible output
{
  "session_id": "abc-123",
  "model": "claude-opus-4-6",
  "tokens_used": 54000,
  "tokens_limit": 200000,
  "tokens_percent": 27.0,
  "categories": {
    "system_prompt": 3400,
    "system_tools": 21100,
    "memory_files": 3300,
    "skills": 917,
    "messages": 24000,
    "compact_buffer": 3000
  }
}

Key requirements:

  • Read-only — no session mutation, no nesting risk
  • Non-interactive — returns data and exits, suitable for programmatic use
  • Accessible from within a session — should not be blocked by the nested session guard since it doesn't start a new session

Use Case

Real-world scenario: coordinating a team of agents on a large codebase refactor. The lead agent has no way to know if a child agent is about to run out of context. Currently the only workaround is "spawn a replacement agent when one stops mid-task" (reactive) rather than monitoring and acting proactively.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗