Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

feat(cli): add token-efficient task monitoring with duration display

ShawnPana723f3335b295
diff --git a/browser_use/skill_cli/commands/session_management.py b/browser_use/skill_cli/commands/session_management.py
index 431c6aabd..3fa505277 100644
--- a/browser_use/skill_cli/commands/session_management.py
+++ b/browser_use/skill_cli/commands/session_management.py
@@ -71,6 +71,39 @@ def _run_async(coro: Any) -> Any:
return asyncio.run(coro)
+def _format_duration(started_at: str | None, finished_at: str | None) -> str:
+ """Format duration between two timestamps, or elapsed time if still running."""
+ if not started_at:
+ return ''
+
+ from datetime import datetime, timezone
+
+ try:
+ # Parse ISO format timestamp
+ start = datetime.fromisoformat(started_at.replace('Z', '+00:00'))
+
+ if finished_at:
+ end = datetime.fromisoformat(finished_at.replace('Z', '+00:00'))
+ else:
+ end = datetime.now(timezone.utc)
+
+ delta = end - start
+ total_seconds = int(delta.total_seconds())
+
+ if total_seconds < 60:
+ return f'{total_seconds}s'
+ elif total_seconds < 3600:
+ minutes = total_seconds // 60
+ seconds = total_seconds % 60
+ return f'{minutes}m {seconds}s'
+ else:
+ hours = total_seconds // 3600
+ minutes = (total_seconds % 3600) // 60
+ return f'{hours}h {minutes}m'
+ except Exception:
+ return ''
+
+
def _handle_list(args: argparse.Namespace) -> int:
"""Handle 'session list' command."""
try:
@@ -95,7 +128,8 @@ def _handle_list(args: argparse.Namespace) -> int:
session_id = s.get('id', 'unknown')
status = s.get('status', 'unknown')
live_url = s.get('liveUrl')
- started_at = s.get('startedAt', '')[:19] if s.get('startedAt') else ''
+ started_at = s.get('startedAt')
+ finished_at = s.get('finishedAt')
keep_alive = 'πŸ”„' if s.get('keepAlive') else ''
# Status emoji
@@ -107,11 +141,13 @@ def _handle_list(args: argparse.Namespace) -> int:
# Truncate ID for display
short_id = session_id[:8] + '...' if len(session_id) > 8 else session_id
+ # Build line with duration
+ duration = _format_duration(started_at, finished_at)
line = f' {status_emoji} {short_id} [{status}]'
+ if duration:
+ line += f' {duration}'
if keep_alive:
line += f' {keep_alive}'
- if started_at:
- line += f' started: {started_at}'
if live_url and status == 'active':
line += f'\n live: {live_url}'
print(line)
@@ -144,18 +180,24 @@ def _handle_get(args: argparse.Namespace) -> int:
'stopped': '⏹️',
}.get(status, '❓')
- print(f'Session: {session_id}')
- print(f'Status: {status_emoji} {status}')
- if keep_alive:
- print('Keep Alive: Yes')
- if started_at:
- print(f'Started: {started_at}')
- if finished_at:
- print(f'Finished: {finished_at}')
+ # Build header with duration
+ duration = _format_duration(started_at, finished_at)
+ header_parts = [f'{status_emoji} {session_id[:8]}... [{status}]']
+ if duration:
+ header_parts.append(duration)
if proxy_cost:
- print(f'Proxy Cost: ${proxy_cost}')
+ # Format proxy cost to 2 decimal places
+ try:
+ cost_val = float(proxy_cost)
+ header_parts.append(f'${cost_val:.2f}')
+ except (ValueError, TypeError):
+ header_parts.append(f'${proxy_cost}')
+ print(' '.join(header_parts))
+
+ if keep_alive:
+ print(' Keep Alive: Yes')
if live_url:
- print(f'Live URL: {live_url}')
+ print(f' Live URL: {live_url}')
return 0
diff --git a/browser_use/skill_cli/commands/task_management.py b/browser_use/skill_cli/commands/task_management.py
index af95b5b47..5058b191a 100644
--- a/browser_use/skill_cli/commands/task_management.py
+++ b/browser_use/skill_cli/commands/task_management.py
@@ -115,21 +115,70 @@ def _handle_list(args: argparse.Namespace) -> int:
return 0
+def _format_duration(started_at: str | None, finished_at: str | None) -> str:
+ """Format duration between two timestamps, or elapsed time if still running."""
+ if not started_at:
+ return ''
+
+ from datetime import datetime, timezone
+
+ try:
+ # Parse ISO format timestamp
+ start = datetime.fromisoformat(started_at.replace('Z', '+00:00'))
+
+ if finished_at:
+ end = datetime.fromisoformat(finished_at.replace('Z', '+00:00'))
+ else:
+ end = datetime.now(timezone.utc)
+
+ delta = end - start
+ total_seconds = int(delta.total_seconds())
+
+ if total_seconds < 60:
+ return f'{total_seconds}s'
+ elif total_seconds < 3600:
+ minutes = total_seconds // 60
+ seconds = total_seconds % 60
+ return f'{minutes}m {seconds}s'
+ else:
+ hours = total_seconds // 3600
+ minutes = (total_seconds % 3600) // 60
+ return f'{hours}h {minutes}m'
+ except Exception:
+ return ''
+
+
def _handle_status(args: argparse.Namespace) -> int:
"""Handle 'task status <task_id>' command."""
try:
- status = _run_async(cloud_task.get_task_status(args.task_id))
+ # Use get_task() for full details including steps
+ task_data = _run_async(cloud_task.get_task(args.task_id))
except Exception as e:
print(f'Error: {e}', file=sys.stderr)
return 1
if getattr(args, 'json', False):
- print(json.dumps(status))
+ print(json.dumps(task_data))
else:
- task_id = status.get('id', args.task_id)
- task_status = status.get('status', 'unknown')
- output = status.get('output')
- cost = status.get('cost')
+ task_id = task_data.get('id', args.task_id)
+ task_status = task_data.get('status', 'unknown')
+ output = task_data.get('output')
+ cost = task_data.get('cost')
+ steps = task_data.get('steps', [])
+ started_at = task_data.get('startedAt')
+ finished_at = task_data.get('finishedAt')
+
+ compact = getattr(args, 'compact', False)
+ verbose = getattr(args, 'verbose', False)
+ last_n = getattr(args, 'last', None)
+ reverse = getattr(args, 'reverse', False)
+ specific_step = getattr(args, 'step', None)
+
+ # Determine display mode:
+ # - Default: show only latest step
+ # - --compact: show all steps with reasoning
+ # - --verbose: show all steps with full details
+ show_all_steps = compact or verbose
# Status emoji
status_emoji = {
@@ -140,18 +189,95 @@ def _handle_status(args: argparse.Namespace) -> int:
'failed': '❌',
}.get(task_status, '❓')
- print(f'Task: {task_id}')
- print(f'Status: {status_emoji} {task_status}')
-
+ # Build header line: status, cost, duration
+ parts = [f'{status_emoji} {task_id[:8]}... [{task_status}]']
if cost is not None:
- print(f'Cost: ${cost}')
+ parts.append(f'${cost}')
+ duration = _format_duration(started_at, finished_at)
+ if duration:
+ parts.append(duration)
+ print(' '.join(parts))
+
+ # Show steps
+ if steps:
+ total_steps = len(steps)
+
+ # Filter to specific step if requested
+ if specific_step is not None:
+ steps = [s for s in steps if s.get('number') == specific_step]
+ if not steps:
+ print(f' Step {specific_step} not found (task has {total_steps} steps)')
+ else:
+ print(f' (showing step {specific_step} of {total_steps})')
+ # Display the specific step
+ for step in steps:
+ _print_step(step, verbose)
+ elif not show_all_steps:
+ # Default mode: show only the latest step
+ latest_step = steps[-1]
+ earlier_count = total_steps - 1
+ if earlier_count > 0:
+ print(f' ... {earlier_count} earlier steps')
+ _print_step(latest_step, verbose=False)
+ else:
+ # --compact or --verbose: show all steps (with optional filters)
+ skipped_earlier = 0
+ if last_n is not None and last_n < total_steps:
+ skipped_earlier = total_steps - last_n
+ steps = steps[-last_n:]
+
+ # Apply --reverse
+ if reverse:
+ steps = list(reversed(steps))
+
+ # Show count info
+ if skipped_earlier > 0:
+ print(f' ... {skipped_earlier} earlier steps')
+
+ # Display steps
+ for step in steps:
+ _print_step(step, verbose)
if output:
- print(f'Output: {output}')
+ print(f'\nOutput: {output}')
return 0
+def _print_step(step: dict, verbose: bool) -> None:
+ """Print a single step in compact or verbose format."""
+ step_num = step.get('number', '?')
+ memory = step.get('memory', '')
+
+ if verbose:
+ url = step.get('url', '')
+ actions = step.get('actions', [])
+
+ # Truncate URL for display
+ short_url = url[:60] + '...' if len(url) > 60 else url
+
+ print(f' [{step_num}] {short_url}')
+ if memory:
+ # Truncate memory/reasoning for display
+ short_memory = memory[:100] + '...' if len(memory) > 100 else memory
+ print(f' Reasoning: {short_memory}')
+ if actions:
+ for action in actions[:2]: # Show max 2 actions per step
+ # Truncate action for display
+ short_action = action[:70] + '...' if len(action) > 70 else action
+ print(f' Action: {short_action}')
+ if len(actions) > 2:
+ print(f' ... and {len(actions) - 2} more actions')
+ else:
+ # Compact mode: just step number and reasoning
+ if memory:
+ # Truncate reasoning for compact display
+ short_memory = memory[:80] + '...' if len(memory) > 80 else memory
+ print(f' {step_num}. {short_memory}')
+ else:
+ print(f' {step_num}. (no reasoning)')
+
+
def _handle_stop(args: argparse.Namespace) -> int:
"""Handle 'task stop <task_id>' command."""
try:
diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.py
index 1b8a489ac..75fb20841 100755
--- a/browser_use/skill_cli/main.py
+++ b/browser_use/skill_cli/main.py
@@ -643,6 +643,11 @@ Setup:
# task status <task_id>
p = task_sub.add_parser('status', help='Get task status')
p.add_argument('task_id', help='Task ID')
+ p.add_argument('--compact', '-c', action='store_true', help='Show all steps with reasoning')
+ p.add_argument('--verbose', '-v', action='store_true', help='Show all steps with full details (URLs, actions)')
+ p.add_argument('--last', '-n', type=int, metavar='N', help='Show only the last N steps')
+ p.add_argument('--reverse', '-r', action='store_true', help='Show steps newest first (100, 99, 98...)')
+ p.add_argument('--step', '-s', type=int, metavar='N', help='Show specific step number')
p.add_argument('--json', action='store_true', help='Output as JSON')
# task stop <task_id>
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index 1b914f9ee..b4b76a1e1 100644
--- a/skills/browser-use/SKILL.md
+++ b/skills/browser-use/SKILL.md
@@ -206,17 +206,19 @@ Manage cloud tasks when using remote mode:
browser-use task list # List recent tasks
browser-use task list --limit 20 # Show more tasks
browser-use task list --status running # Filter by status
-browser-use task list --status finished
browser-use task list --json # JSON output
-browser-use task status <task-id> # Get task status and output
-browser-use task status <task-id> --json
+browser-use task status <task-id> # Get task status (token efficient)
+browser-use task status <task-id> -c # Show all steps with reasoning
+browser-use task status <task-id> -v # Show all steps with URLs + actions
+browser-use task status <task-id> --last 5 # Show only last 5 steps
browser-use task stop <task-id> # Stop a running task
-
browser-use task logs <task-id> # Get task execution logs
```
+**Token-efficient monitoring:** Default `task status` shows only the latest step. Use `-c` (compact) or `-v` (verbose) only when you need more context.
+
### Cloud Session Management (Remote Mode)
Manage cloud browser sessions:
@@ -351,6 +353,62 @@ browser-use -b remote run "task" \
browser-use -b remote run "task" --profile <profile-id> --no-wait
```
+### Debugging & Monitoring
+
+**Live view**: Watch an agent work in real-time:
+```bash
+browser-use session get <session-id>
+# β†’ Live URL: https://live.browser-use.com?wss=...
+# Open this URL in your browser to watch the agent
+```
+
+**Detect stuck tasks**: If cost stops increasing, the task may be stuck:
+```bash
+browser-use task status <task-id>
+# Cost: $0.009 ← if this doesn't change over time, task is stuck
+```
+
+**Logs**: Only available after task completes (not during execution):
+```bash
+browser-use task logs <task-id> # Works after task finishes
+```
+
+### Cleanup
+
+Always clean up sessions after parallel work:
+```bash
+# Stop all active agents
+browser-use session stop --all
+
+# Or stop specific sessions
+browser-use session stop <session-id>
+```
+
+### Troubleshooting Subagents
+
+**Session reuse fails after `task stop`**:
+If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Solution: create a new agent instead.
+```bash
+# This may fail:
+browser-use task stop <task-id>
+browser-use -b remote run "new task" --session-id <same-session> # Might get stuck
+
+# Do this instead:
+browser-use -b remote run "new task" --profile <profile-id> # Fresh session
+```
+
+**Task stuck at "started"**:
+- Check cost with `task status` - if not increasing, task is stuck
+- View live URL with `session get` to see what's happening
+- Stop the task and create a new agent
+
+**Sessions persist after tasks complete**:
+Tasks finishing doesn't auto-stop sessions. Clean up manually:
+```bash
+browser-use session list --status active # See lingering sessions
+browser-use session stop --all # Clean up
+```
+
### Session Management
```bash
browser-use sessions # List active sessions
diff --git a/skills/remote-browser/SKILL.md b/skills/remote-browser/SKILL.md
index bd268e168..b5ab86a31 100644
--- a/skills/remote-browser/SKILL.md
+++ b/skills/remote-browser/SKILL.md
@@ -369,6 +369,96 @@ browser-use run "task" \
browser-use run "task" --profile <profile-id> --no-wait
```
+### Monitoring Subagents
+
+**Task status is designed for token efficiency.** Default output is minimal - only expand when needed:
+
+| Mode | Flag | Tokens | Use When |
+|------|------|--------|----------|
+| Default | (none) | Low | Polling progress |
+| Compact | `-c` | Medium | Need full reasoning |
+| Verbose | `-v` | High | Debugging actions |
+
+**Recommended workflow:**
+
+```bash
+# 1. Launch task
+browser-use run "task" --no-wait
+# β†’ task_id: abc-123
+
+# 2. Poll with default (token efficient) - only latest step
+browser-use task status abc-123
+# βœ… abc-123... [finished] $0.009 15s
+# ... 1 earlier steps
+# 2. I found the information and extracted...
+
+# 3. ONLY IF task failed or need context: use --compact
+browser-use task status abc-123 -c
+
+# 4. ONLY IF debugging specific actions: use --verbose
+browser-use task status abc-123 -v
+```
+
+**For long tasks (50+ steps):**
+```bash
+browser-use task status <id> -c --last 5 # Last 5 steps only
+browser-use task status <id> -c --reverse # Newest first
+browser-use task status <id> -v --step 10 # Inspect specific step
+```
+
+**Live view**: Watch an agent work in real-time:
+```bash
+browser-use session get <session-id>
+# β†’ Live URL: https://live.browser-use.com?wss=...
+```
+
+**Detect stuck tasks**: If cost/duration stops increasing, the task may be stuck:
+```bash
+browser-use task status <task-id>
+# πŸ”„ abc-123... [started] $0.009 45s ← if cost doesn't change, task is stuck
+```
+
+**Logs**: Only available after task completes:
+```bash
+browser-use task logs <task-id> # Works after task finishes
+```
+
+### Cleanup
+
+Always clean up sessions after parallel work:
+```bash
+# Stop all active agents
+browser-use session stop --all
+
+# Or stop specific sessions
+browser-use session stop <session-id>
+```
+
+### Troubleshooting
+
+**Session reuse fails after `task stop`**:
+If you stop a task and try to reuse its session, the new task may get stuck at "created" status. Solution: create a new agent instead.
+```bash
+# This may fail:
+browser-use task stop <task-id>
+browser-use run "new task" --session-id <same-session> # Might get stuck
+
+# Do this instead:
+browser-use run "new task" --profile <profile-id> # Fresh session
+```
+
+**Task stuck at "started"**:
+- Check cost with `task status` - if not increasing, task is stuck
+- View live URL with `session get` to see what's happening
+- Stop the task and create a new agent
+
+**Sessions persist after tasks complete**:
+Tasks finishing doesn't auto-stop sessions. Clean up manually:
+```bash
+browser-use session list --status active # See lingering sessions
+browser-use session stop --all # Clean up
+```
+
### Session Management
```bash
browser-use sessions # List active sessions