Sessions Tool

Browse and search your own conversation history. Agents can list past sessions, read full message histories, and search across sessions by pattern. Access is strictly scoped — an agent can only see its own sessions.

Installation

Install this tool individually:

beige tools install github:matthias-hausberger/beige-toolkit/tools/sessions

Or install all tools from the toolkit:

# From npm
beige tools install npm:@matthias-hausberger/beige-toolkit

# From GitHub
beige tools install github:matthias-hausberger/beige-toolkit

Configuration

No configuration needed. The tool works out of the box with no config block. All commands (list, get, grep) are always available.

Prerequisites

No external dependencies. The tool uses beige’s internal session store. Requires beige ≥ 0.1.3 for agent identity injection (BEIGE_AGENT_NAME).

Commands

Command	Description
list	List sessions (newest first). Tool-initiated sessions excluded by default.
list --include-active	Also include the currently running session.
list --format json	Machine-readable list.
get <key>	Full message history of a session. Truncated at 50 messages by default.
get <key> --all	Show all messages (no truncation).
get <key> --format json	Machine-readable message list.
grep <pattern>	Search message content across sessions (up to 100, newest first).
grep <pattern> --session <key>	Search within one session only.
grep <pattern> --max-sessions <n>	Search up to N sessions (default: 100).
grep <pattern> --max-matches <n>	Stop after N total matches (default: 50).
grep <pattern> --format json	Machine-readable matches.

All commands accept --format json for structured output suitable for scripting or further processing.

Security Model

Concern	How it is handled
Agent scoping	Every operation is filtered to the calling agent’s sessions. Agent name comes from BEIGE_AGENT_NAME (injected by beige ≥ 0.1.3).
Ownership check	Before reading any session, the tool verifies the session belongs to the caller.
No cross-agent access	There is no config option to allow reading another agent’s sessions.
Read-only	The tool never writes, modifies, or deletes sessions.
No raw file paths	File paths are never exposed in output — only session keys and message content.

Error Reference

Error	Cause
agent identity unknown	BEIGE_AGENT_NAME not set — requires beige ≥ 0.1.3
session store unavailable	Tool not running in gateway context
session 'X' not found	Key not in the session map
Permission denied: session 'X' belongs to agent 'Y'	Session exists but owned by a different agent
Invalid regex 'X'	/pattern/ syntax used but the regex is malformed

Implementation Details

• Target: Gateway (runs on the host, not in the sandbox)
• Read-only: Never writes, modifies, or deletes sessions
• No dependencies: Uses beige’s internal session store