pw-danger-gemini-web

Gemini Web client

Supported features:

Text generation
Image generation (download + save)
Reference images for visual input (attach local images)
Through persistent --sessionId for multi-turn conversation

Script directory

Important: All scripts are located in this skill's scripts/ subdirectory.

Agent execution instructions:

Determine the directory path of this SKILL.md file as SKILL_DIR
Script path = ${SKILL_DIR}/scripts/<script-name>.ts
Replace all ${SKILL_DIR} in this document with the actual path

Script reference:

Script	Purpose
`scripts/main.ts`	CLI entry point for text/image generation
`scripts/gemini-webapi/*`	`gemini_webapi` TypeScript port (GeminiClient, types, utilities)

⚠️ Disclaimer (required)

Before using this skill, a consent check must be performed.

Consent check process

Step 1: Check the consent file

# macOS
cat ~/Library/Application\ Support/pw-skills/gemini-web/consent.json 2>/dev/null

# Linux
cat ~/.local/share/pw-skills/gemini-web/consent.json 2>/dev/null

# Windows (PowerShell)
Get-Content "$env:APPDATA\pw-skills\gemini-web\consent.json" 2>$null

Step 2: If the consent file exists and accepted: true and matches disclaimerVersion: "1.0":

Print a warning and continue:

⚠️  警告: 使用逆向工程的 Gemini Web API（非官方）。接受时间: <acceptedAt 日期>

Step 3: If the consent file does not exist or disclaimerVersion does not match:

Display the disclaimer and ask the user:

⚠️  免责声明

此工具使用逆向工程的 Gemini Web API，而非官方 Google API。

风险:
- 如果 Google 更改其 API，可能会在没有通知的情况下失效
- 没有官方支持或保证
- 使用风险自负

您是否接受这些条款并希望继续？

Use the AskUserQuestion tool, with the options:

Yes, I accept - Continue and save consent
No, I decline - Exit immediately

Step 4: After accepting, create the consent file:

# macOS
mkdir -p ~/Library/Application\ Support/pw-skills/gemini-web
cat > ~/Library/Application\ Support/pw-skills/gemini-web/consent.json << 'EOF'
{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO 时间戳>",
  "disclaimerVersion": "1.0"
}
EOF

# Linux
mkdir -p ~/.local/share/pw-skills/gemini-web
cat > ~/.local/share/pw-skills/gemini-web/consent.json << 'EOF'
{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO 时间戳>",
  "disclaimerVersion": "1.0"
}
EOF

Step 5: After declining, output the message and stop:

用户拒绝了免责声明。退出。

Quick start

npx -y bun ${SKILL_DIR}/scripts/main.ts "你好，Gemini"
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "解释量子计算"
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image cat.png
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png

# 多轮对话（agent 生成唯一的 sessionId）
npx -y bun ${SKILL_DIR}/scripts/main.ts "记住这个: 42" --sessionId my-unique-id-123
npx -y bun ${SKILL_DIR}/scripts/main.ts "什么数字?" --sessionId my-unique-id-123

Command

Text generation

# 简单提示（位置参数）
npx -y bun ${SKILL_DIR}/scripts/main.ts "你的提示内容"

# 显式提示标志
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "你的提示内容"
npx -y bun ${SKILL_DIR}/scripts/main.ts -p "你的提示内容"

# 选择模型
npx -y bun ${SKILL_DIR}/scripts/main.ts -p "你好" -m gemini-2.5-pro

# 从标准输入管道
echo "总结这个" | npx -y bun ${SKILL_DIR}/scripts/main.ts

Image generation

# 使用默认路径生成图像（./generated.png）
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "山上的日落" --image

# 使用自定义路径生成图像
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一个可爱的机器人" --image robot.png

# 简写形式
npx -y bun ${SKILL_DIR}/scripts/main.ts "一条龙" --image=dragon.png

Visual input (reference image)

# 文本 + 图像 -> 文本
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "描述这张图片" --reference a.png

# 文本 + 图像 -> 图像
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "生成一个变体" --reference a.png --image out.png

Output format

# 纯文本（默认）
npx -y bun ${SKILL_DIR}/scripts/main.ts "你好"

# JSON 输出
npx -y bun ${SKILL_DIR}/scripts/main.ts "你好" --json

Parameter description

Core parameters

--prompt (alias: -p)

Description: The prompt text to send to Gemini
Type: string
Required: yes (unless using --promptfiles or standard input)
Example: --prompt "生成一只可爱的猫咪"
Note: If not using a flag, it can be passed directly as a positional argument

--promptfiles <files...>

Description: Read prompt content from one or more files, concatenated in order
Type: array of file paths
Required: no
Example: --promptfiles system.md content.md
Use case: When the prompt content is long or multiple files need to be combined
Note: File contents are concatenated in order, separated by newlines

--model (alias: -m)

Description: Select the Gemini model to use
Type: enum value
Possible values:
- gemini-3-pro (default): The latest and strongest model, recommended
- gemini-2.5-pro: Previous-generation pro version, good stability
- gemini-2.5-flash: Fast and lightweight, suitable for simple tasks
Required: no
Example: --model gemini-2.5-flash
Selection recommendations:
- Image generation: use gemini-3-pro for best quality
- Simple text: use gemini-2.5-flash for speed
- Complex reasoning: use gemini-3-pro

Image-related parameters

--image [path]

Description: generate an image and save it to the specified path
Type: optional string
Required: No
Default value: generated.png (if only --image is written without a path)
Example:
- --image (saved as generated.png)
- --image cat.png (saved as cat.png)
- --image=/path/to/output.png (using equals-sign syntax)
Note:
- The path can be a relative path or an absolute path
- The directory must exist, otherwise an error will occur
- Supports PNG format

--reference <files...> (alias: --ref)

Description: provide a reference image for visual input
Type: array of file paths
Required: No
Example:
- --reference photo.jpg (single image)
- --reference img1.png img2.png (multiple images)
Use cases:
- Image-to-text: describe the image content
- Image-to-image: generate variations based on a reference image
- Image-text combination: combine images and text prompts
Note: supports common image formats (PNG, JPG, JPEG, WebP)

Session management parameters

--sessionId

Description: session identifier for multi-turn conversations
Type: string
Required: No
Example: --sessionId task-abc123
Use cases:
- Continuous conversations that need to maintain context
- Batch processing multiple tasks on the same topic
- Need Gemini to remember previous interactions
Best practices:
- The Agent should generate a unique session ID (such as a UUID or a task-based hash)
- Use the same session ID for tasks in the same batch
- Use different session IDs for different topics
Note: session data is stored locally and does not expire

--list-sessions

Description: list all saved sessions
Type: boolean flag
Required: No
Output: up to 100 sessions, sorted by update time in descending order
Use case: view historical sessions and decide whether to reuse them

Output format parameters

--json

Description: output the result in JSON format
Type: boolean flag
Required: No

Output format:

{
  "text": "生成的文本内容",
  "imagePath": "/path/to/image.png",
  "sessionId": "task-abc123"
}

Use case: when programmatic parsing of the output is needed
Note: the default output is plain text

Authentication-related parameters

--login

Description: only execute the login flow to refresh cookies, then exit
Type: boolean flag
Required: No
Use cases:
- Cookies have expired and re-login is needed
- Switch Google accounts
- Complete authentication in advance to avoid subsequent interruptions
Note: a browser window will open, and login must be completed manually

--cookie-path

Description: customize the cookie file storage path
Type: file path
Required: No
Default value: cookies.json in the system data directory
Use case: Multi-account management or custom storage location

--profile-dir

Description: Specify the Chrome profile directory
Type: Directory path
Required: No
Use case: Use a specific Chrome profile

Help parameter

--help (alias: -h)

Description: Show help information
Type: Boolean flag

Model

gemini-3-pro - Default, latest model
gemini-2.5-pro - Previous generation pro version
gemini-2.5-flash - Fast, lightweight

Authentication

On first run, a browser will open for Google authentication. Cookies will be cached for subsequent runs.

Supported browsers(auto-detected in order):

Google Chrome
Google Chrome Canary / Beta
Chromium
Microsoft Edge

If needed, you can use the GEMINI_WEB_CHROME_PATH environment variable to override.

# 强制刷新 cookie
npx -y bun ${SKILL_DIR}/scripts/main.ts --login

Login instructions:

After the browser opens, it will wait until you complete the login
There is no timeout limit, so you can take your time with multi-factor authentication and other steps
After successful login, the browser will automatically close after 3 seconds

Environment variables

Variable	Description
`GEMINI_WEB_DATA_DIR`	Data directory
`GEMINI_WEB_COOKIE_PATH`	Cookie file path
`GEMINI_WEB_CHROME_PROFILE_DIR`	Chrome profile directory
`GEMINI_WEB_CHROME_PATH`	Chrome executable path

Proxy configuration

If you need proxy access to Google services (for example, in China), set the HTTP_PROXY and HTTPS_PROXY environment variables before running:

# 使用本地代理的示例
HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 npx -y bun ${SKILL_DIR}/scripts/main.ts "你好"

# 使用代理生成图像
HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只猫" --image cat.png

# 使用代理刷新 cookie
HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 npx -y bun ${SKILL_DIR}/scripts/main.ts --login

Note: Environment variables must be set inline with the command. Shell profile settings (such as .bashrc) may not be inherited by child processes.

Examples

Generate a text response

npx -y bun ${SKILL_DIR}/scripts/main.ts "法国的首都是什么?"

Generate an image

npx -y bun ${SKILL_DIR}/scripts/main.ts "一张金毛猎犬幼犬的逼真照片" --image puppy.png

Get JSON output for parsing

npx -y bun ${SKILL_DIR}/scripts/main.ts "你好" --json | jq '.text'

Generate an image from a prompt file

# 将 system.md + content.md 连接作为提示
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image output.png

Multi-turn conversation

# 使用唯一 ID 开始会话（agent 生成此 ID）
npx -y bun ${SKILL_DIR}/scripts/main.ts "你是一个有帮助的数学导师。" --sessionId task-abc123

# 继续对话（记住上下文）
npx -y bun ${SKILL_DIR}/scripts/main.ts "2+2 等于多少?" --sessionId task-abc123
npx -y bun ${SKILL_DIR}/scripts/main.ts "现在乘以 10" --sessionId task-abc123

# 列出最近的会话（最多 100 个，按更新时间排序）
npx -y bun ${SKILL_DIR}/scripts/main.ts --list-sessions

Best practices for batch processing:

When processing multiple files in a directory, it is recommended to use the same session ID
This maintains conversation continuity, and Gemini can remember the previous context
Example: Generate a fixed session ID for a directory

# 为目录生成固定的 session ID（使用目录路径的 hash）
DIR_PATH="/path/to/project"
SESSION_ID=$(echo -n "$DIR_PATH" | md5sum | cut -d' ' -f1)

# 批量处理该目录下的文件，使用同一个 session ID
npx -y bun ${SKILL_DIR}/scripts/main.ts "生成第一张图" --sessionId "$SESSION_ID" --image img1.png
npx -y bun ${SKILL_DIR}/scripts/main.ts "生成第二张图" --sessionId "$SESSION_ID" --image img2.png
npx -y bun ${SKILL_DIR}/scripts/main.ts "生成第三张图" --sessionId "$SESSION_ID" --image img3.png

Session files are stored in ~/Library/Application Support/pw-skills/gemini-web/sessions/<id>.json , containing:

id: Session ID
metadata: Gemini chat metadata used for continuation
messages: {role, content, timestamp, error?} array
createdAt, updatedAt: Timestamp

Extension support

Custom configuration via EXTEND.md.

Check paths (priority order):

.pw-skills/pw-danger-gemini-web/EXTEND.md (project level)
~/.pw-skills/pw-danger-gemini-web/EXTEND.md (user level)

If found, load before the workflow. Extension content overrides default values.

Common errors and solutions

Authentication-related errors

Error: "Cookie expired" or "Authentication failed"

Cause: The cookie has expired or is invalid

Solution:

# 重新登录刷新 cookie
npx -y bun ${SKILL_DIR}/scripts/main.ts --login

Error: "Browser not found"

Cause: No supported browser was found on the system
Solution:
- Install Chrome, Chromium, or Edge
- Or use an environment variable to specify the browser path:
```
GEMINI_WEB_CHROME_PATH=/path/to/chrome npx -y bun ${SKILL_DIR}/scripts/main.ts --login
```

Error: "Login timeout" or the login window keeps waiting

Cause: Login process not completed
Solution:
- Ensure the complete login process is finished in the browser
- Handle multi-factor authentication (if enabled)
- After successful login, the browser will automatically close after 3 seconds
- There is no timeout limit, so you can complete login slowly

Network-related errors

Error: "Connection refused" or "Network error"

Cause: Unable to access Google services (common in mainland China)

Solution: Configure a proxy

HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 \
npx -y bun ${SKILL_DIR}/scripts/main.ts "你好"

Note: Environment variables must be set inline with the command

Error: "Rate limit exceeded"

Cause: Request frequency is too high, triggering rate limiting
Solution:
- Reduce request frequency
- Add delays between requests
- Avoid making a large number of requests in a short time

Image-related errors

Error: "Failed to save image" or "Directory not found"

Cause: The target directory does not exist

Solution:

# 确保目录存在
mkdir -p /path/to/output
npx -y bun ${SKILL_DIR}/scripts/main.ts "一只猫" --image /path/to/output/cat.png

Error: "Image generation failed"

Cause: Gemini cannot generate an image based on the prompt
Solution:
- Check whether the prompt is clear and explicit
- Avoid prompts that violate the content policy
- Try rephrasing the prompt
- Use a different model (such as gemini-3-pro)

Error: "Reference image not found"

Cause: The reference image path does not exist
Solution:
- Check whether the file path is correct
- Use absolute paths to avoid relative path issues
- Ensure the file format is supported (PNG, JPG, JPEG, WebP)

Session-related errors

Error: "Session not found"

Cause: The specified session ID does not exist
Solution:
- Use --list-sessions to view available sessions
- Ensure the session ID is spelled correctly
- A new session will be automatically created on first use

Error: "Session corrupted"

Cause: The session file is corrupted

Solution:

# 删除损坏的会话文件
rm ~/Library/Application\ Support/pw-skills/gemini-web/sessions/<session-id>.json
# 或在 Linux 上
rm ~/.local/share/pw-skills/gemini-web/sessions/<session-id>.json

Other errors

Error: "Bun not found"

Cause: Bun is not installed on the system
Solution: npx -y bun will automatically download Bun; no manual installation is required

Error: "Permission denied"

Cause: No write permission
Solution:
- Check the output directory permissions
- Check the data directory permissions
- Use a path with permissions

Best practices

Agent usage recommendations

1. Session ID management

Generate a unique session ID for each independent task
Use meaningful naming: task-<uuid> or project-<hash>
Reuse the session ID for tasks in the same batch to maintain context

Example:

# 为目录生成固定 session ID
SESSION_ID=$(echo -n "/path/to/project" | md5sum | cut -d' ' -f1)

2. Error handling

Always check the command exit code
Use --json output to make results easier to parse
Capture and log error information

Example:

if ! output=$(npx -y bun ${SKILL_DIR}/scripts/main.ts "test" --json 2>&1); then
  echo "Error: $output"
  exit 1
fi

3. Proxy Configuration

Automatically add proxy environment variables in mainland China environments
Prompt the user to configure a proxy when network errors are detected

Example:

# 检测是否需要代理
if [[ $(curl -s -o /dev/null -w "%{http_code}" https://gemini.google.com) != "200" ]]; then
  echo "提示: 可能需要配置代理访问 Google 服务"
fi

4. Batch Processing

Use the same session ID to process related tasks
Add appropriate delays between requests to avoid rate limiting
Use --json output for easy batch parsing

Example:

for file in *.txt; do
  npx -y bun ${SKILL_DIR}/scripts/main.ts \
    --promptfiles "$file" \
    --sessionId "$SESSION_ID" \
    --image "${file%.txt}.png" \
    --json
  sleep 2  # 避免限流
done

Image Generation Recommendations

1. Prompt Optimization

Use clear, specific descriptions
Include details such as style, color, and composition
Avoid vague or abstract expressions
Good example: "A realistic photo of a golden retriever puppy, sunny grassy background, shallow depth of field"
Bad example: "A dog"

2. Model Selection

High-quality images: use gemini-3-pro
Quick preview: use gemini-2.5-flash
Complex scenes: use gemini-3-pro

3. Using Reference Images

Image-to-image: provide a clear reference image and a description of the changes
Image-to-text: provide specific description requirements

Example:

# 基于参考图生成变体
npx -y bun ${SKILL_DIR}/scripts/main.ts \
  --prompt "生成一个卡通风格的变体，保持主体不变" \
  --reference original.jpg \
  --image cartoon.png

Multi-turn Conversation Recommendations

1. Context Management

Set a system prompt or role in the first conversation
Reuse the session ID in subsequent conversations

Example:

# 第一轮: 设置角色
npx -y bun ${SKILL_DIR}/scripts/main.ts \
  "你是一个专业的图像描述专家" \
  --sessionId img-desc-001

# 后续轮次: 描述图像
npx -y bun ${SKILL_DIR}/scripts/main.ts \
  --prompt "描述这张图片" \
  --reference photo.jpg \
  --sessionId img-desc-001

2. Session Cleanup

Regularly clean up sessions that are no longer needed
Use --list-sessions to view the session list

Manually delete session files:

# macOS
rm ~/Library/Application\ Support/pw-skills/gemini-web/sessions/<id>.json

# Linux
rm ~/.local/share/pw-skills/gemini-web/sessions/<id>.json

Performance Optimization

1. Reduce Unnecessary Requests

Combine related prompts into a single request
Use --promptfiles to combine multiple files
Avoid repeatedly generating the same content

2. Parallel Processing

Independent tasks can be executed in parallel
Use different session IDs to avoid conflicts
Be aware of rate limits

3. Caching Strategy

Cookies are cached automatically, so there is no need to log in every time
Session data is persisted, allowing context to be reused
Generated images are saved locally to avoid repeated generation

Security Recommendations

1. Credential Management

Cookie files contain sensitive information, so protect them carefully
Do not commit cookie files to version control
Refresh cookies regularly to maintain security

2. Content Review

Comply with Google content policies
Avoid generating violating content
Pay attention to copyright and privacy issues

3. Data Privacy

Session data is stored locally
Prompt content is sent to Google servers
Do not include sensitive information in prompts

Troubleshooting Checklist

When you encounter a problem, check in the following order:

Check the network connection
```
curl -I https://gemini.google.com
```
- If it fails, configure a proxy
Check the authentication status
```
npx -y bun ${SKILL_DIR}/scripts/main.ts --login
```
- Log in again to refresh the cookie

Check the browser

which chrome || which chromium || which microsoft-edge

Make sure a supported browser is installed

Check file permissions
```
ls -la ~/Library/Application\ Support/pw-skills/gemini-web/
```
- Make sure you have read and write permissions
Check the output directory
```
mkdir -p /path/to/output && ls -la /path/to/output
```
- Ensure the directory exists and is writable

View detailed error

npx -y bun ${SKILL_DIR}/scripts/main.ts "test" 2>&1 | tee error.log

Save full error log

Test basic functionality

# 测试文本生成
npx -y bun ${SKILL_DIR}/scripts/main.ts "你好"

# 测试图像生成
npx -y bun ${SKILL_DIR}/scripts/main.ts "一只猫" --image test.png

Technical limitations

Known limitations:

This is an unofficial API and may become unavailable at any time
No official support or SLA guarantee
There may be unknown rate limiting restrictions
API changes may cause functionality to break
Image generation quality depends on the capabilities of the Gemini model

Unsupported features:

Video generation
Audio generation
Real-time streaming output
Batch API calls
Webhook callbacks

Performance characteristics:

Text generation: usually 2-5 seconds
Image generation: usually 10-30 seconds
Login flow: depends on the user's operation speed
Session loading: almost instant

Changelog

Check the project's Git history for the latest changes:

cd ${SKILL_DIR}
git log --oneline --decorate

About this skill

Script directory

⚠️ Disclaimer (required)

Consent check process

Quick start

Command

Text generation

Image generation

Visual input (reference image)

Output format

Parameter description

Core parameters

Image-related parameters

Session management parameters

Output format parameters

Authentication-related parameters

Help parameter

Model

Authentication

Environment variables

Proxy configuration

Examples

Generate a text response

Generate an image

Get JSON output for parsing

Generate an image from a prompt file

Multi-turn conversation

Extension support

Common errors and solutions

Authentication-related errors

Network-related errors

Image-related errors

Session-related errors

Other errors

Best practices

Agent usage recommendations

Image Generation Recommendations

Multi-turn Conversation Recommendations

Performance Optimization

Security Recommendations

Troubleshooting Checklist

Technical limitations

Changelog