docs: add BROWSERBASE_CONFIG_DIR file-based session logging #1508

shrey150 · 2026-01-06T22:47:13Z

Summary

Documents the BROWSERBASE_CONFIG_DIR environment variable for file-based session logging
Covers setup, usage, and log file types (llm_events.log, cdp_events.log, stagehand.log)
Includes examples for real-time monitoring with tail -f and chronological review

Summary by cubic

Document file-based Stagehand session logging via BROWSERBASE_CONFIG_DIR with setup, log paths, tail/review tips, and log file types. Also fix broken links in Next Steps and add missing leading slashes in observability.

^{Written for commit bb71828. Summary will update on new commits.}

Document the new file-based logging feature that writes detailed logs to ~/.config/browserbase/sessions/ for debugging agent workflows. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

changeset-bot · 2026-01-06T22:47:16Z

⚠️ No Changeset found

Latest commit: bb71828

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

cubic-dev-ai

No issues found across 1 file

greptile-apps · 2026-01-06T22:49:02Z

Greptile Summary

This PR adds comprehensive documentation for file-based session logging in Stagehand via the BROWSERBASE_CONFIG_DIR environment variable, along with fixes to broken navigation links. The new "File-Based Session Logging" section in logging.mdx provides clear setup instructions, usage examples, and guidance for viewing logs with practical bash commands. The PR also improves the Next Steps sections in both files by fixing link paths and making card descriptions more specific and actionable.

Confidence Score: 5/5

This PR is safe to merge with no issues found - documentation improvements with corrected links and new helpful content.
All changes are documentation updates with verified link targets. The new "File-Based Session Logging" section is well-structured with clear setup steps, practical usage examples, and helpful log viewing commands. Link fixes were verified against actual file paths and section headers in the codebase. Card descriptions now accurately reflect destination content as required. No syntax errors, typos, or broken references detected.
No files require special attention

Important Files Changed

Filename	Overview
packages/docs/v3/configuration/logging.mdx	Added comprehensive documentation for file-based session logging via `BROWSERBASE_CONFIG_DIR` with setup, usage examples, log viewing methods, and log file descriptions. Also fixed three incorrect internal links in the Next Steps section - corrected History API link from `/v3/configuration/observability#history-tracking` to `/v3/best-practices/history`, fixed Metrics API anchor from `#real-time-metrics--monitoring` to `#real-time-metrics-%26-monitoring`, and moved LLM Inference Debugging link from observability to logging section.
packages/docs/v3/configuration/observability.mdx	Improved Next Steps section by fixing link paths - added leading slashes to make paths absolute (`/v3/best-practices/history` and `/v3/configuration/logging`), updated card titles to be more specific and descriptive, and restructured from two generic "Complete Guide" cards to focused, individual cards for each topic with relevant icons and concise descriptions.

Sequence Diagram

sequenceDiagram
    participant User
    participant Stagehand
    participant FileSystem
    participant Logs

    User->>Stagehand: Set BROWSERBASE_CONFIG_DIR env var
    User->>Stagehand: Run script with imports stagehand
    Stagehand->>FileSystem: Create ~/.config/browserbase/sessions/session-id/
    Stagehand->>FileSystem: Create 'latest' symlink
    
    Note over Stagehand: Execute automation operations
    Stagehand->>Stagehand: agent.execute()
    Stagehand->>Logs: Write to llm_events.log
    Stagehand->>Logs: Write to cdp_events.log
    Stagehand->>Logs: Write to stagehand.log
    
    Stagehand->>Stagehand: act()
    Stagehand->>Logs: Write operation to stagehand.log
    Stagehand->>Logs: Write LLM request/response to llm_events.log
    
    Stagehand->>Stagehand: extract()
    Stagehand->>Logs: Write operation to stagehand.log
    Stagehand->>Logs: Write LLM request/response to llm_events.log
    
    User->>FileSystem: tail -f ~/.config/browserbase/sessions/latest/*.log
    FileSystem-->>User: Stream logs in real-time
    
    User->>FileSystem: cat ~/.config/browserbase/sessions/latest/*.log | sort
    FileSystem-->>User: Display chronological logs

greptile-apps

Additional Comments (1)

packages/docs/v3/configuration/logging.mdx, line 623-641 (link)

logic: Several anchor links in the "Next Steps" section don't exist in the observability documentation:
- #history-tracking - observability doc only has main sections, no History API subsection
- #detailed-inference-logging - should be in logging.mdx itself, not observability
The observability.mdx has these sections: Browserbase Session Monitoring, Local Environment Monitoring, Resource Usage Monitoring, Real-Time Metrics & Monitoring, Best Practices, Next Steps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

Remove cards linking to non-existent anchors (#history-tracking, #detailed-inference-logging) in the observability docs. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Rename "Complete Observability Guide" to "Debugging Tips" - Replace "Complete Logging Guide" with "LLM Inference Debugging" linking to correct anchor 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

…ct links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Keep only the leading slash fix, revert title/icon changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Rename cards to match their destinations - Update descriptions to be accurate and distinct 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

cubic-dev-ai

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/docs/v3/configuration/observability.mdx">

<violation number="1" location="packages/docs/v3/configuration/observability.mdx:364">
P2: Both cards have identical descriptions which appears to be a copy-paste error. The "Complete Logging Guide" card should have a description specific to logging functionality, not the same text as the observability card.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/docs/v3/configuration/observability.mdx

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

shrey150 · 2026-01-07T08:26:58Z

@greptileai

shrey150 · 2026-01-08T01:07:46Z

Merge activity

Jan 8, 1:07 AM UTC: A user started a stack merge that includes this pull request via Graphite.
Jan 8, 1:08 AM UTC: @shrey150 merged this pull request with Graphite.

mintlify bot deployed to staging - packages/docs January 6, 2026 22:47 View deployment

cubic-dev-ai bot reviewed Jan 6, 2026

View reviewed changes

greptile-apps bot reviewed Jan 6, 2026

View reviewed changes

mintlify bot deployed to staging - packages/docs January 6, 2026 23:58 View deployment

fix: add missing leading slashes to href paths in observability.mdx

bde8dfd

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

mintlify bot deployed to staging - packages/docs January 7, 2026 08:04 View deployment

mintlify bot deployed to staging - packages/docs January 7, 2026 08:16 View deployment

fix: restore History API and LLM Inference Debugging cards with corre…

3e486a2

…ct links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

mintlify bot deployed to staging - packages/docs January 7, 2026 08:18 View deployment

mintlify bot deployed to staging - packages/docs January 7, 2026 08:20 View deployment

cubic-dev-ai bot reviewed Jan 7, 2026

View reviewed changes

packages/docs/v3/configuration/observability.mdx Outdated Show resolved Hide resolved

mintlify bot deployed to staging - packages/docs January 7, 2026 08:22 View deployment

shrey150 and others added 2 commits January 7, 2026 00:25

fix: remove potentially broken anchor from Metrics API link

ca4cbdb

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

fix: use correct URL-encoded anchor for Metrics API link

bb71828

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

mintlify bot deployed to staging - packages/docs January 7, 2026 08:25 View deployment

mintlify bot deployed to staging - packages/docs January 7, 2026 08:26 View deployment

pirate approved these changes Jan 8, 2026

View reviewed changes

shrey150 merged commit 425138b into main Jan 8, 2026
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add BROWSERBASE_CONFIG_DIR file-based session logging #1508

docs: add BROWSERBASE_CONFIG_DIR file-based session logging #1508

Uh oh!

shrey150 commented Jan 6, 2026 •

edited by cubic-dev-ai bot

Loading

Uh oh!

changeset-bot bot commented Jan 6, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

greptile-apps bot commented Jan 6, 2026 •

edited

Loading

Uh oh!

greptile-apps bot left a comment •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

shrey150 commented Jan 7, 2026

Uh oh!

shrey150 commented Jan 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

docs: add BROWSERBASE_CONFIG_DIR file-based session logging #1508

docs: add BROWSERBASE_CONFIG_DIR file-based session logging #1508

Uh oh!

Conversation

shrey150 commented Jan 6, 2026 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by cubic

Uh oh!

changeset-bot bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Additional Comments (1)

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shrey150 commented Jan 7, 2026

Uh oh!

shrey150 commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shrey150 commented Jan 6, 2026 •

edited by cubic-dev-ai bot

Loading

changeset-bot bot commented Jan 6, 2026 •

edited

Loading

greptile-apps bot commented Jan 6, 2026 •

edited

Loading

greptile-apps bot left a comment •

edited

Loading

shrey150 commented Jan 8, 2026 •

edited

Loading