> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions Tool

{/* Run: pnpm run docs:sync-toolkit */}

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:

```bash theme={null}
beige tools install github:matthias-hausberger/beige-toolkit/tools/sessions
```

Or install all tools from the toolkit:

```bash theme={null}
# 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