jackwener / jackwener/OpenCLI

Improve production observability for Windows Chrome profile/session usage

Open
#2,054 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
29.3k
Forks
2.9k
Avg merge
15h 36m
Merged PRs (30d)
70

Description

## Background

We are using OpenCLI in a Windows production workflow to automate logged-in browser sessions for websites such as HeyGen. It works well overall, but several production issues are hard to diagnose because profile/session state is not very observable.

## Pain points

1. It is hard to map OpenCLI profile IDs to Chrome profile directories / account hints / current logged-in site state.
2. We need a safe read-only health check that does not launch a new browser or modify the user profile.
3. Long-running browser automation needs structured JSONL progress / heartbeat output so agents can distinguish "still waiting" from "stuck".
4. Browser API failures should include structured diagnostics: status code, path, body preview, profile id, session id, current page URL, CDP attach state.
5. Windows + Git Bash + Chrome profile usage could use more docs, especially around remote debugging port and safe attach behavior.

## Suggested features

- `opencli profiles list --json`
- `opencli profile check --site --json --no-launch`
- `--jsonl` structured event output for long tasks
- Standard structured error format for browser API calls
- Windows/Chrome profile safety guide

Example profile list output:

```json
[
{
"id": "u343mvn7",
"browser": "chrome",
"profileDirectory": "Profile 31",
"sites": ["app.heygen.com"],
"lastSeenTitle": "...",
"lastSeenUrl": "...",
"accountHint": "user@example.com",
"cdpAttached": true
}
]
```

Example read-only check output:

```json
{
"ok": false,
"reason": "chrome_running_without_remote_debugging_port",
"safeToLaunch": false,
"message": "Existing Chrome instance has no CDP port; cannot attach without relaunching."
}
```

Example browser API error output:

```json
{
"ok": false,
"error": {
"type": "browser_api_http_error",
"status": 401,
"path": "/v1/project/items",
"bodyPreview": "...",
"profile": "u343mvn7",
"session": "heygen-batch-u343mvn7",
"pageUrl": "https://app.heygen.com/..."
}
}
```

## Why this matters

In production, multiple logged-in Chrome profiles are used for different accounts. Accidentally launching a new window, attaching to the wrong profile, or silently losing login state can break long-running jobs. Better profile/session introspection would make OpenCLI much safer for AI-agent production workflows.

Contributor guide

Open the contributing guide

Research direction

Start by locating the existing profile/session commands, browser API error handling, and long-running task output paths in the repository. Define the scope with maintainers before changing code; done should include the agreed read-only profile check, structured JSON/JSONL diagnostics, and Windows/Chrome safety documentation with tests or examples for the supported behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, playwright
Domain
cli, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.