Agent Session Context

Inspect and summarize recorded Claude Code and Codex sessions.

Use Ruby 3.2 or newer.

Add this line to your application's Gemfile:

gem "agent_session_context"

Then run:

bundle install

Show the latest recorded session:

agent-session-context show --current

Show an exact session:

agent-session-context show codex:SESSION_ID

Disambiguate a bare identifier:

agent-session-context show SESSION_ID --agent codex

List exact user prompts:

agent-session-context prompts --current

Render prompts as JSON Lines:

agent-session-context prompts --current --format jsonl

Use these variables for --current, in order:

1. AGENT_SESSION_ID with AGENT_NAME
2. CLAUDE_CODE_SESSION_ID
3. CODEX_SESSION_ID
4. CODEX_THREAD_ID

Without variables, let the command select the unique newest session metadata.

Pass --agent to restrict that disk search.

Keep present identifiers authoritative.

Never trigger fallback after validating a present identifier.

Clear conflicting Claude and Codex identifiers before retrying.

Expect missing targets, empty stores, and timestamp ties to fail.

Read the selected UID from the CLI warning.

Treat disk selection as recency, not live context.

Include deduplicated injected text explicitly:

agent-session-context show --current --include-injected

Review exact prompts and injected text before sharing them.

Expect show to exclude assistant messages, thinking, tool-result bodies, and raw envelopes.

Use show and prompts without starting a model.

Show a session as the agent loop:

agent-session-context loop --current

Print prompts, model entries, tool calls paired with their results, and the last recorded state.

The entry count includes prompts and tool results. Where the store provides no response grouping (including Codex), each message is a separate entry; neither total entries nor model entries is a proven count of API requests. JSON retains the round_trips field and its recorded flags.

Print byte sizes and tool names only, never prompt or tool-result bodies.

The ending is inferred from the last normalized entry; a session may resume after the snapshot. Codex commentary and reasoning tails are incomplete, while a final_answer message is answered. Legacy assistant messages without a phase retain the existing inference.

Codex token accounting is handled by agent_sessions 0.4.1 or later and adds no conversation entries or unknown-record warnings. Human CLI diagnostics appear once on stderr; standalone Ruby views and JSON retain their warnings.

Expect deterministic output: render the same session the same way regardless of machine or time zone.

Render loop as text, Markdown, JSON, or JSON Lines with --format.

Create a grounded summary:

agent-session-context summarize --current

Choose a backend and timeout:

agent-session-context summarize --current --using codex --timeout 45

Codex summarization was tested successfully against a live recorded session.

Expect summaries to cite recorded source references.

Expect summaries to exclude thinking, tool results, injected blocks, and raw records.

Treat Codex filesystem access as read-only, not hermetic.

Resolve and inspect a session:

require "agent/session_context"

session = Agent::SessionContext.resolve("codex:SESSION_ID")
snapshot = Agent::SessionContext.show(session)

Inspect the newest recorded Codex session:

session = Agent::SessionContext.current(agent: :codex, env: {})
prompts = Agent::SessionContext.prompts(session)

Read a session as the agent loop:

loop = Agent::SessionContext.loop(session)
loop.ending #=> :answered, :incomplete, :stopped_in_the_loop, :not_a_model_record, or :empty

Create a summary with built-in settings:

summary = Agent::SessionContext.summarize(session, using: :codex, timeout: 45)

Use a custom summarizer:

summary = Agent::SessionContext.summarize(
  session,
  summarizer: ->(prompt:, schema:) { call_your_model(prompt, schema) }
)

Replace call_your_model with your adapter.

Return a JSON string matching the provided schema.

Pass either summarizer: or timeout:, never both.

Agent::SessionContext.resolve and Agent::SessionContext.current return Agent::Sessions::Session.

Agent::SessionContext.show returns an Agent::SessionContext::Snapshot whose collections contain Agent::SessionContext::Prompt, Agent::SessionContext::InjectedContext, Agent::SessionContext::Item, and Agent::SessionContext::SourceRef values as applicable.

Agent::SessionContext.prompts returns an array of Agent::SessionContext::Prompt values.

Agent::SessionContext.loop returns an Agent::SessionContext::Loop.

Agent::SessionContext.summarize returns an Agent::SessionContext::Snapshot populated with summary Agent::SessionContext::Item values and summary metadata.

Agent::SessionContext::Snapshot, Agent::SessionContext::Prompt, Agent::SessionContext::InjectedContext, Agent::SessionContext::Item, and Agent::SessionContext::SourceRef are part of the supported public data model.

Agent::SessionContext::Loop and Agent::SessionContext::ToolCall are part of the supported public data model. Agent::SessionContext::LoopView is internal.

Agent::SessionContext::VERSION is public.

Agent::SessionContext::CLI::FORMATS is the supported frozen list of CLI output format names.

The public error classes listed in Errors are part of the compatibility contract.

resolve -> capture -> extract/collect -> optionally summarize -> build snapshot -> render.

show can expose injected text only when you opt into include_injected, while summarize keeps injected blocks and tool-result bodies out of the model prompt.

Except for Agent::SessionContext::CLI::FORMATS, the CLI implementation, builders, collectors, parsers, runners, renderers, and built-in summarizer adapters are internal details without compatibility guarantees.

Run agent-session-context help for command details.

Expect only summarize to load configuration.

Configuration paths retain the original agent-context name for compatibility.

Create .agent-context.yml in the recorded project:

summarize:
  timeout_seconds: 300

Set user defaults in $XDG_CONFIG_HOME/agent_context/config.yml.

Otherwise, use $HOME/.config/agent_context/config.yml.

Use XDG_CONFIG_HOME exclusively when it contains an absolute path.

Let project configuration override user defaults.

Pass --timeout to override both files.

Use finite numbers from 1 through 3600.

Apply the timeout to each provider call.

Handle these public errors:

• Agent::SessionContext::SessionNotFound
• Agent::SessionContext::AmbiguousSession
• Agent::SessionContext::CurrentSessionUnavailable
• Agent::SessionContext::UnsupportedAgent
• Agent::SessionContext::ConfigurationError
• Agent::SessionContext::SummarizerUnavailable
• Agent::SessionContext::SummarizerFailed
• Agent::SessionContext::InvalidSummary

Fork the repository and create a branch.

Run the test suite:

bundle exec rake test

Open a pull request with tests and documentation.

Follow CODE_OF_CONDUCT.md.

Report bugs through GitHub Issues.

Use the gem under the MIT License.

See LICENSE.txt.