🤖 DeepSeek Browser Agent

An autonomous AI coding agent that runs entirely for free — no API key required.

It drives a real browser to talk to DeepSeek, giving you a Claude Code / Cursor-style coding agent powered by DeepSeek's AI models at zero cost.

Installation · Quick Start · HTTP API · Configuration · Tools · Contributing

⚠️ This project is currently in active development. Core functionality works, but you may encounter rough edges. Bug reports and contributions are very welcome — see Contributing.

🧠 How It Works

Most AI coding agents talk to a paid API. This one doesn't.

Instead, it uses Playwright to control a real Chromium browser, navigates to chat.deepseek.com, sends your task, waits for the response, and parses it to extract tool calls — all automatically. Your local files and terminal are wired up as tools the AI can use, so it can read code, write files, run commands, and build complete projects step by step.

Your Terminal
     │
     ▼
 Agent Core          ← orchestrates the loop
     │
     ├──► Browser (Playwright)  ← talks to chat.deepseek.com
     │         │
     │    DeepSeek AI           ← thinks, decides what tool to use
     │         │
     └──► Tool Executor  ← reads/writes files, runs commands
              │
         Your Project

📦 Installation

Windows

# 安装 Node.js (如果没有)
# 从 https://nodejs.org 下载安装，或使用 winget:
winget install OpenJS.NodeJS.LTS

# 全局安装 deepseek-free-agent
npm install -g deepseek-free-agent

# 安装 Chromium 浏览器 (首次安装后自动执行，约 150MB)
npx playwright install chromium

💡 提示: 如果安装后 deepseek-agent 命令找不到，可以直接使用 npx deepseek-free-agent 运行。

Ubuntu / Linux

# 安装 Node.js (如果没有)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 全局安装 deepseek-free-agent
npm install -g deepseek-free-agent

# 安装 Chromium 和依赖
npx playwright install chromium
npx playwright install-deps chromium  # 安装系统依赖

💡 提示: 如果安装后 deepseek-agent 命令找不到，可以直接使用 npx deepseek-free-agent 运行。

Requirements: Node.js ≥ 18

🚀 Quick Start

Windows

1. 首次运行 — 登录 DeepSeek:

# 启动 HTTP API 服务器
npx deepseek-free-agent

浏览器窗口打开后，登录你的 DeepSeek 账号。会话会保存 — 只需登录一次。

2. 提交任务:

# 使用 HTTP API 提交任务
curl -X POST http://localhost:9527/task `
  -H "Content-Type: application/json" `
  -d '{"task":"创建一个 Express REST API，带用户认证"}'

Ubuntu / Linux

1. 首次运行 — 登录 DeepSeek:

# 启动 HTTP API 服务器
npx deepseek-free-agent

浏览器窗口打开后，登录你的 DeepSeek 账号。会话会保存 — 只需登录一次。

2. 提交任务:

# 使用 HTTP API 提交任务
curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task":"build a REST API in Express with user authentication"}'

🌐 HTTP API

This agent only accepts tasks via HTTP API on port 9527. This design simplifies the architecture and enables remote task submission.

Task Queue

多客户端并发支持： 所有请求进入队列串行处理，确保每个客户端收到正确的响应。

客户端A → 请求"北京天气" → 队列位置1 → 处理 → 返回"北京天气答案"
客户端B → 请求"上海天气" → 队列位置2 → 等待 → 处理 → 返回"上海天气答案"
客户端C → 请求"广州天气" → 队列位置3 → 等待 → 处理 → 返回"广州天气答案"

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /task | POST | 提交任务 | | /status | GET | 获取队列状态 | | /queue | GET | 获取队列详情 | | /task/:id | GET | 获取单个任务状态 | | / | GET | 服务信息 |

POST /task - 提交任务

Endpoint: POST http://localhost:9527/task

Request Body:

{
  "task": "你的任务描述",
  "newChat": true
}

newChat 参数说明：

| 值 | 行为 | 适用场景 | |---|---|---| | true (默认) | 开启全新对话，AI 无历史记忆 | 新任务、独立问题 | | false | 在当前对话中继续，AI 会记住之前的内容 | 多轮对话、上下文关联任务 |

Response:

{
  "question": "上海天气，20个字",
  "answer": "上海今日晴，气温25°C...",
  "duration": 5234,
  "status": "success"
}

使用示例

Windows PowerShell:

# 提交任务
curl -X POST http://localhost:9527/task `
  -H "Content-Type: application/json" `
  -d '{"task":"创建一个 Express REST API"}'

# 多轮对话示例
curl -X POST http://localhost:9527/task `
  -H "Content-Type: application/json" `
  -d '{"task":"我叫小明"}'

curl -X POST http://localhost:9527/task `
  -H "Content-Type: application/json" `
  -d '{"task":"我叫什么名字","newChat":false}'

# 查看状态
curl http://localhost:9527/status

# 查看队列
curl http://localhost:9527/queue

Ubuntu / Linux:

# 提交任务
curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task":"创建一个 Express REST API"}'

# 多轮对话示例
curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task":"我叫小明"}'

curl -X POST http://localhost:9527/task \
  -H "Content-Type: application/json" \
  -d '{"task":"我叫什么名字","newChat":false}'

# 查看状态
curl http://localhost:9527/status

# 查看队列
curl http://localhost:9527/queue

从其他编程语言调用

Python:

import requests
import json

response = requests.post(
    'http://localhost:9527/task',
    json={'task': '创建一个 Express REST API'}
)
result = response.json()
print(result)

Node.js:

const http = require('http');

const body = JSON.stringify({ task: '创建一个 Express REST API' });

const req = http.request({
  hostname: 'localhost',
  port: 9527,
  path: '/task',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' }
}, (res) => {
  let data = '';
  res.on('data', chunk => data += chunk);
  res.on('end', () => console.log(JSON.parse(data)));
});

req.write(body);
req.end();

GET /status - 队列状态查询

curl http://localhost:9527/status

Response:

{
  "queueLength": 2,
  "isProcessing": true,
  "currentTask": {
    "id": "abc123",
    "task": "北京天气",
    "elapsed": 3000
  },
  "pendingTasks": [
    { "id": "def456", "task": "上海天气", "waitTime": 2000 },
    { "id": "ghi789", "task": "广州天气", "waitTime": 1000 }
  ],
  "stats": {
    "totalProcessed": 10,
    "averageProcessTime": 5000
  }
}

GET /queue - 队列详情

curl http://localhost:9527/queue

GET /task/:id - 单个任务状态

curl http://localhost:9527/task/abc123

💻 Command Line Options

deepseek-agent [OPTIONS]
# 或使用 npx (推荐，无需配置 PATH):
npx deepseek-free-agent [OPTIONS]

OPTIONS:
  --show-browser       显示浏览器（强制有头模式）
  --headless           无头模式（强制隐藏浏览器）
  --debug              调试模式
  -h, --help           帮助

浏览器显示逻辑（优先级从高到低）
  1. --headless        强制无头（隐藏浏览器）
  2. --show-browser    强制有头（显示浏览器）
  3. 默认              有头模式（便于调试）

HTTP API 端点:
  POST http://localhost:9527/task     提交任务
  GET  http://localhost:9527/status   查看状态
  GET  http://localhost:9527/queue    查看队列

示例:
  deepseek-agent                     # 启动服务器（默认显示浏览器）
  deepseek-agent --headless          # 启动服务器（后台运行，不显示浏览器）

⚙️ Configuration

Global config — applies everywhere

Create ~/.deepseek-agent/config.json:

{
  "HEADLESS": false,
  "MAX_ITERATIONS": 50,
  "STABLE_DELAY": 3000,
  "DEBUG": false
}

Per-project config — overrides global

Drop deepseek-agent.config.json in your project root:

{
  "MAX_ITERATIONS": 60,
  "MAX_OUTPUT_LENGTH": 12000
}

All settings

| Setting | Default | Description | |---|---|---| | HEADLESS | false | Hide the browser window | | MAX_ITERATIONS | 40 | Max agent steps per task before stopping | | RESPONSE_TIMEOUT | 120000 | Max ms to wait for a response (120s, performance optimized) | | STABLE_DELAY | 1500 | Ms of silence that means DeepSeek is done (performance optimized) | | SEND_DELAY | 100 | Ms between typing and pressing Enter (optimized) | | MAX_OUTPUT_LENGTH | 8000 | Truncate long command outputs sent to AI | | DEBUG | false | Print raw AI responses to terminal | | SESSION_DIR | ~/.deepseek-agent/session | Where browser cookies are saved | | COMMAND_SECURITY_ENABLED | true | Enable command execution security validation | | COMMAND_MODE | strict | Security mode: strict | moderate | permissive | | COMMAND_WHITELIST_ONLY | true | Only allow whitelisted commands | | COMMAND_LOG_ENABLED | true | Audit log all command executions | | PATH_TRAVERSAL_PROTECTION | true | Block path traversal attacks (../../../etc/passwd) | | FILE_OVERWRITE_PROTECTION | true | Warn and backup before overwriting files | | FILE_BACKUP_ENABLED | true | Auto-backup overwritten files to ~/.deepseek-agent/session/backups/ | | ALLOW_SYSTEM_FILE_ACCESS | false | Block access to system directories (/etc, /usr, /System, etc.) |

⚡ Performance Note: Default configuration is now optimized for speed (30-40% faster than previous version).

• STABLE_DELAY reduced from 2500ms to 1500ms
• RESPONSE_TIMEOUT reduced from 180s to 120s

If you experience stability issues (incomplete responses), restore conservative settings in your config file:

{
  "STABLE_DELAY": 2500,
  "RESPONSE_TIMEOUT": 180000
}

🛠️ Available Tools

The agent can use these tools autonomously to complete your task:

| Tool | Description | |---|---| | read_file | Read file contents with path traversal protection | | write_file | Write file with path validation and overwrite protection | | append_to_file | Append text to an existing file | | replace_in_file | Find and replace text in a file (regex supported) | | delete_file | Permanently delete a file | | list_directory | List directory contents, optionally recursive | | create_directory | Create a directory and all parents | | move_file | Move or rename a file or directory | | copy_file | Copy a file to a new location | | get_file_info | Get file metadata (size, line count, dates) | | run_command | Execute shell commands with security validation | | find_files | Find files by name pattern (e.g. *.ts) | | search_in_files | Search text inside files (like grep -r) | | read_url | Fetch and read the content of a URL | | write_files | Batch write files with security validation |

🔒 Security Note: All file operations now include comprehensive security validation:

• Path traversal protection: Blocks ../../../etc/passwd attacks
• System file protection: Blocks access to /etc, /usr, /System, etc.
• File overwrite protection: Automatic backup for large files (>10KB)
• Command validation: Dangerous commands blocked before execution
• Audit logging: All operations logged to ~/.deepseek-agent/logs/

See Security Guide for configuration details.

📂 Where Data is Stored

Everything lives in ~/.deepseek-agent/ in your home directory:

~/.deepseek-agent/
├── session/        ← Browser cookies (login once, runs forever)
├── logs/           ← Session logs (only saved with --save-log)
├── server.lock     ← HTTP server process lock
└── config.json     ← Your global settings

🔧 Troubleshooting

Agent responds but creates no files

The browser DOM rendered the AI's response in a way the parser didn't catch. Run with --debug to see exactly what's being received:

npx deepseek-free-agent --debug

Agent stops responding / loops

DeepSeek's UI may have changed. Run the calibration tool — it inspects the live DOM and prints updated selectors:

npx deepseek-free-agent --calibrate

Login session expired

Just run without --headless — the browser opens and you log in again:

npx deepseek-free-agent

Chromium didn't download automatically

Windows:

npx playwright install chromium

Ubuntu / Linux:

npx playwright install chromium
npx playwright install-deps chromium

Response times out on long tasks

Increase the timeout in your config:

{ "RESPONSE_TIMEOUT": 300000, "STABLE_DELAY": 4000 }

HTTP server not detected

The lock file may be stale. Kill the old process and restart:

# Check process
cat ~/.deepseek-agent/server.lock

# Kill if needed
kill <PID>  # Linux
taskkill /PID <PID> /F  # Windows

# Restart
npx deepseek-free-agent

🗂️ Project Structure

deepseek-free-agent/
├── src/
│   ├── index.js          ← CLI entry point and argument parsing
│   ├── agent.js          ← Core agent loop (send → wait → parse → execute)
│   ├── browser.js        ← Playwright controller for chat.deepseek.com
│   ├── server.js         ← HTTP server for process communication
│   ├── tools.js          ← All 15 filesystem and shell tools
│   ├── parser.js         ← Extracts tool calls from AI responses (6 strategies)
│   ├── prompt.js         ← System prompt and conversation history manager
│   ├── config.js         ← Configuration loader (global + per-project)
│   ├── logger.js         ← ANSI-colored terminal output
│   ├── calibrate.js      ← DOM selector inspector / auto-fix tool
│   └── postinstall.js    ← Auto-downloads Chromium after npm install
├── LICENSE
├── README.md
└── package.json

🤝 Contributing

Contributions are very welcome — this project is in active development and there's plenty of room to grow.

Setting up locally

git clone https://github.com/YOUR_USERNAME/deepseek-free-agent
cd deepseek-free-agent
npm install
npx playwright install chromium
node src/index.js

Areas that need work

• 🧪 Tests — there are currently no automated tests; a test suite would be a great contribution
• 🎨 UI selector resilience — DeepSeek updates their UI occasionally; better selector strategies are welcome
• 🔌 More tools — image generation, browser control, database tools, etc.
• 🌐 Other AI frontends — adapting the browser layer to work with other free AI chats
• 📝 Better error messages — making failures easier to diagnose

How to contribute

1. Fork the repo
2. Create a branch: git checkout -b feature/my-improvement
3. Make your changes
4. Open a Pull Request with a clear description

Please keep PRs focused — one feature or fix per PR makes review much faster.

Reporting bugs

Open an issue on GitHub with:

• What you ran
• What you expected
• What actually happened
• Output of npx deepseek-free-agent --debug if relevant

⚠️ Disclaimer

This project automates a web browser to interact with chat.deepseek.com. Automating web UIs may violate the terms of service of the website being automated. Use this tool for personal and development purposes only. The authors take no responsibility for account suspensions or other consequences of use.

📄 License

MIT — see LICENSE for details.

Built with Playwright · Powered by DeepSeek · Free forever

If this project helped you, consider giving it a ⭐ on GitHub!