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:
- It's only available as an interactive slash command — not exposed as a CLI subcommand
- Running
claude contextorclaude /contextfrom Bash inside a session fails because Claude Code blocks nested sessions - 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
/contextmanually
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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗