camoufox-cli 0.3.0__tar.gz → 0.5.0__tar.gz

camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "camoufox-cli",
+  "owner": {
+    "name": "Benn Huang"
+  },
+  "metadata": {
+    "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Camoufox",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "camoufox-cli",
+      "description": "Anti-detect browser automation skill with fingerprint spoofing for AI agents",
+      "source": "./",
+      "skills": [
+        "./skills/camoufox-cli"
+      ]
+    }
+  ]
+}

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/Makefile

@@ -14,13 +14,13 @@ test-e2e:
 	cd js && npx vitest run tests/e2e.test.ts
 
 build: clean
-	python -m build
+	uv build
 	cd js && npm run build
 
 publish: publish-pip publish-npm
 
 publish-pip: build
-	twine upload dist/*
+	uvx twine upload dist/*
 
 publish-npm: build
 	cd js && npm publish --access public

camoufox_cli-0.3.0/PKG-INFO → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: camoufox-cli
-Version: 0.3.0
-Summary: Anti-detect browser CLI & Skills for AI agents, powered by Camoufox
-Project-URL: Homepage, https://github.com/Bin-Huang/camoufox-cli
-Project-URL: Repository, https://github.com/Bin-Huang/camoufox-cli
-Project-URL: Issues, https://github.com/Bin-Huang/camoufox-cli/issues
-Author: Benn Huang
-License-Expression: MIT
-License-File: LICENSE
-Keywords: ai-agent,anti-detect,automation,browser,camoufox,headless
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
-Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.10
-Requires-Dist: camoufox[geoip]
-Requires-Dist: pillow
-Requires-Dist: playwright
-Description-Content-Type: text/markdown
-
 # camoufox-cli
 
 Anti-detect browser CLI & Skills for AI agents, powered by [Camoufox](https://github.com/daijro/camoufox).
@@ -27,6 +5,7 @@ Anti-detect browser CLI & Skills for AI agents, powered by [Camoufox](https://gi
 ### Highlights
 
 - C++-level fingerprint spoofing via Camoufox (canvas, WebGL, audio, screen metrics, fonts)
+- Persistent identities: stable fingerprint, OS, and locale across launches with `--persistent`
 - Accessibility-tree snapshots with `@ref` element targeting
 - Session isolation with cookie import/export
 - Shell commands, no code generation
@@ -173,11 +152,49 @@ camoufox-cli cookies export file.json     # Export cookies
 --headed               Show browser window (default: headless)
 --timeout <seconds>    Daemon idle timeout (default: 1800)
 --json                 Output as JSON
---persistent [path]    Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
+--persistent [path]    Persistent identity (see below); default path: ~/.camoufox-cli/profiles/<session>
 --proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
 --no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
+--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
+```
+
+## Persistent Identity
+
+Without `--persistent`, every launch gets a fresh random fingerprint. With `--persistent`, a `camoufox-cli.json` file is written next to the browser's user data. Fingerprint, OS, and canvas/font seeds are generated on the first launch and frozen afterwards; locale and proxy-derived timezone/geolocation are also saved but track whatever you pass on the command line. Every subsequent launch with the same path reloads the identity, so sites see the same device on every visit.
+
+```bash
+# First launch: generates + stores identity
+camoufox-cli --persistent ~/.camoufox-cli/profiles/alice open https://example.com
+
+# Every subsequent launch: same fingerprint, same cookies, same device
+camoufox-cli --persistent ~/.camoufox-cli/profiles/alice open https://example.com
+```
+
+**Frozen** — generated on the first launch, permanent until the directory is deleted:
+
+- Fingerprint (UA, canvas, WebGL, fonts, navigator properties)
+- OS (defaults to host OS)
+- Canvas/font noise seeds
+
+**Persisted** — stored in the file, refreshed whenever you pass the flag:
+
+- `--locale`: sets the stored locale; pass it again to change it, omit it to keep the stored value.
+- Timezone / geolocation: re-derived from the current proxy's IP whenever `--proxy` is active (and `--no-geoip` isn't set), then written back. Without a proxy, the last stored values stay in effect.
+
+**Per-launch** — never stored; pass on every launch for it to apply:
+
+- `--proxy`: proxies rotate or expire; re-specify each launch to avoid silently running through a stale one.
+- `--no-geoip`: follows the current `--proxy`.
+
+**Multiple identities in parallel.** Each persistent path is a distinct identity. Combine with `--session` for concurrent daemons:
+
+```bash
+camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://...
+camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://...
 ```
 
+**Resetting an identity.** Just delete the directory (`rm -rf ~/.camoufox-cli/profiles/alice`). The next launch generates a fresh one.
+
 ## Architecture
 
 ```

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camoufox-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Anti-detect headless browser automation CLI & Skills for AI agents, powered by Camoufox",
   "type": "module",
   "bin": {

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/src/browser.ts

@@ -1,11 +1,15 @@
 /** Browser manager: launches and manages Camoufox instance. */
 
 import { execFileSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
 import { Camoufox, launchOptions } from "camoufox-js";
 import { firefox, type Browser, type BrowserContext, type Page } from "playwright-core";
+import { loadOrCreate, toLaunchOptions } from "./identity.js";
 import { parseProxySettings } from "./proxy.js";
 import { RefRegistry } from "./refs.js";
 
+const MAX_HISTORY = 200;
+
 function ensureBrowserInstalled(): void {
   try {
     execFileSync("npx", ["camoufox-js", "path"], { stdio: "pipe" });
@@ -24,13 +28,15 @@ export class BrowserManager {
   private persistent: string | null;
   private proxy: string | null;
   private geoip: boolean;
+  private locale: string | null;
   private history: string[] = [];
   private historyIndex = -1;
 
-  constructor(persistent: string | null = null, proxy: string | null = null, geoip: boolean = true) {
+  constructor(persistent: string | null = null, proxy: string | null = null, geoip: boolean = true, locale: string | null = null) {
     this.persistent = persistent;
     this.proxy = proxy;
     this.geoip = geoip;
+    this.locale = locale;
   }
 
   async launch(headless: boolean = true): Promise<void> {
@@ -50,11 +56,29 @@ export class BrowserManager {
     }
 
     if (this.persistent) {
+      // Persistent identity: freeze fingerprint/OS on first launch; reload
+      // it on subsequent launches. CLI-passed locale / proxy-derived geo
+      // overwrite the stored values so the file tracks current intent.
+      mkdirSync(this.persistent, { recursive: true });
+      const identity = await loadOrCreate(
+        this.persistent,
+        this.locale,
+        this.proxy,
+        this.geoip,
+      );
+      Object.assign(launchOpts, toLaunchOptions(identity));
       const opts = await launchOptions(launchOpts);
       this.context = await firefox.launchPersistentContext(this.persistent, opts);
       const pages = this.context.pages();
       this.page = pages[0] || await this.context.newPage();
     } else {
+      if (this.locale) {
+        // Non-persistent path: locale is a one-shot override, no identity file.
+        const locales = this.locale.split(",").map((s) => s.trim()).filter(Boolean);
+        if (locales.length > 0) {
+          launchOpts.locale = locales.length > 1 ? locales : locales[0];
+        }
+      }
       this.browser = await Camoufox(launchOpts) as Browser;
       this.page = await this.browser.newPage();
       this.context = this.page.context();
@@ -125,6 +149,9 @@ export class BrowserManager {
   pushHistory(url: string): void {
     this.history = this.history.slice(0, this.historyIndex + 1);
     this.history.push(url);
+    if (this.history.length > MAX_HISTORY) {
+      this.history = this.history.slice(-MAX_HISTORY);
+    }
     this.historyIndex = this.history.length - 1;
   }
 

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/src/cli.ts

@@ -30,7 +30,7 @@ function sendCommand(sockPath: string, command: Record<string, unknown>): Promis
   });
 }
 
-function spawnDaemon(session: string, headed: boolean, timeout: number, persistent: string | null, proxy: string | null = null, geoip: boolean = true): Promise<void> {
+function spawnDaemon(session: string, headed: boolean, timeout: number, persistent: string | null, proxy: string | null = null, geoip: boolean = true, locale: string | null = null): Promise<void> {
   const __dirname = path.dirname(fileURLToPath(import.meta.url));
   const daemonPath = path.join(__dirname, "daemon.js");
 
@@ -39,6 +39,7 @@ function spawnDaemon(session: string, headed: boolean, timeout: number, persiste
   if (persistent) args.push("--persistent", persistent);
   if (proxy) args.push("--proxy", proxy);
   if (!geoip) args.push("--no-geoip");
+  if (locale) args.push("--locale", locale);
 
   spawn("node", [daemonPath, ...args], {
     detached: true,
@@ -58,7 +59,7 @@ function spawnDaemon(session: string, headed: boolean, timeout: number, persiste
   });
 }
 
-async function ensureDaemon(session: string, headed: boolean, timeout: number, persistent: string | null, proxy: string | null = null, geoip: boolean = true): Promise<void> {
+async function ensureDaemon(session: string, headed: boolean, timeout: number, persistent: string | null, proxy: string | null = null, geoip: boolean = true, locale: string | null = null): Promise<void> {
   const sockPath = getSocketPath(session);
   if (fs.existsSync(sockPath)) {
     // Verify daemon is alive
@@ -73,7 +74,7 @@ async function ensureDaemon(session: string, headed: boolean, timeout: number, p
       try { fs.unlinkSync(sockPath); } catch {}
     }
   }
-  await spawnDaemon(session, headed, timeout, persistent, proxy, geoip);
+  await spawnDaemon(session, headed, timeout, persistent, proxy, geoip, locale);
 }
 
 export function listSessions(): string[] {
@@ -100,10 +101,11 @@ export interface Flags {
   persistent: string | null;
   proxy: string | null;
   geoip: boolean;
+  locale: string | null;
 }
 
 export function parseArgs(argv: string[]): { flags: Flags; command: Record<string, unknown> } {
-  const flags: Flags = { session: "default", headed: false, timeout: 1800, json: false, persistent: null, proxy: null, geoip: true };
+  const flags: Flags = { session: "default", headed: false, timeout: 1800, json: false, persistent: null, proxy: null, geoip: true, locale: null };
   const rest: string[] = [];
 
   let i = 0;
@@ -137,6 +139,9 @@ export function parseArgs(argv: string[]): { flags: Flags; command: Record<strin
       case "--no-geoip":
         flags.geoip = false;
         break;
+      case "--locale":
+        flags.locale = argv[++i] ?? (process.stderr.write("Error: --locale requires a value\n"), process.exit(1), "");
+        break;
       default:
         rest.push(argv[i]);
     }
@@ -401,7 +406,7 @@ async function main() {
   }
 
   // Ensure daemon is running
-  await ensureDaemon(flags.session, flags.headed, flags.timeout, flags.persistent, flags.proxy, flags.geoip);
+  await ensureDaemon(flags.session, flags.headed, flags.timeout, flags.persistent, flags.proxy, flags.geoip, flags.locale);
 
   const sockPath = getSocketPath(flags.session);
 
@@ -472,9 +477,10 @@ Flags:
   --headed             Show browser window
   --timeout <secs>     Daemon idle timeout (default: 1800)
   --json               Output as JSON
-  --persistent [path]  Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
+  --persistent [path]  Persistent identity — freeze fingerprint/OS/locale + store cookies/state (default: ~/.camoufox-cli/profiles/<session>)
   --proxy <url>        Proxy server (e.g. http://host:port or https://host:443)
-  --no-geoip           Disable automatic GeoIP spoofing (auto-enabled with --proxy)`;
+  --no-geoip           Disable automatic GeoIP spoofing (auto-enabled with --proxy)
+  --locale <tag>       Force browser locale (e.g. "en-US" or "en-US,zh-CN")`;
 
 const isDirectRun = (() => {
   try {

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/src/daemon.ts

@@ -16,8 +16,9 @@ const timeout = parseInt(getArg("--timeout", "1800"), 10);
 const persistent = args.includes("--persistent") ? getArg("--persistent", "") || null : null;
 const proxy = args.includes("--proxy") ? getArg("--proxy", "") || null : null;
 const geoip = !args.includes("--no-geoip");
+const locale = args.includes("--locale") ? getArg("--locale", "") || null : null;
 
-const server = new DaemonServer({ session, headless, timeout, persistent, proxy, geoip });
+const server = new DaemonServer({ session, headless, timeout, persistent, proxy, geoip, locale });
 
 process.stderr.write(`[camoufox-cli] Starting daemon session=${session} headless=${headless}\n`);
 server.start().catch((err) => {

camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0/js/src/identity.ts

@@ -0,0 +1,206 @@
+/** Persistent identity: freeze fingerprint/OS into a persistent dir.
+ *
+ * When a user launches with `--persistent <dir>`, a `camoufox-cli.json` file
+ * is written on first launch capturing the generated fingerprint, OS, locale,
+ * and derived timezone/geolocation. Subsequent launches reload it so the browser
+ * reports the same device identity to every site.
+ *
+ * Fingerprint/OS/canvas+font seeds are frozen for the lifetime of the identity.
+ * User-controllable fields (locale; proxy-derived timezone/geolocation) are
+ * updated to match the command line whenever it's explicitly passed — so the
+ * stored identity always reflects the most recent intent.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Fingerprint } from "fingerprint-generator";
+import { generateFingerprint } from "camoufox-js/dist/fingerprints.js";
+import { publicIP, validIPv4, validIPv6 } from "camoufox-js/dist/ip.js";
+import { getGeolocation } from "camoufox-js/dist/locale.js";
+import { parseProxySettings } from "./proxy.js";
+
+const IDENTITY_FILENAME = "camoufox-cli.json";
+const IDENTITY_VERSION = 1;
+
+export type HostOS = "windows" | "macos" | "linux";
+
+export interface Identity {
+  version: number;
+  created_at: string;
+  os: HostOS;
+  locale: string | null;
+  fingerprint: Fingerprint;
+  config: Record<string, unknown>;
+}
+
+function hostOS(): HostOS {
+  if (process.platform === "win32") return "windows";
+  if (process.platform === "darwin") return "macos";
+  return "linux";
+}
+
+function identityPath(persistentDir: string): string {
+  return join(persistentDir, IDENTITY_FILENAME);
+}
+
+/**
+ * Return the identity for this persistent directory.
+ *
+ * On first launch, a fresh identity is generated and written:
+ *   - fingerprint: fingerprint-generator, firefox, host OS
+ *   - canvas/font seeds: random, stored so future launches reproduce them
+ *   - timezone/geolocation: derived via GeoIP if proxy is set and geoip=true
+ *   - locale: recorded if passed on this first launch, else null
+ *
+ * On subsequent launches, `<persistentDir>/camoufox-cli.json` is loaded.
+ * Fields the user explicitly passes on the command line overwrite the stored
+ * values (`--locale`; `--proxy` + geoip re-derives timezone/geolocation).
+ * Fingerprint, OS, and canvas/font seeds are never touched after first launch.
+ */
+export async function loadOrCreate(
+  persistentDir: string,
+  locale: string | null,
+  proxy: string | null,
+  geoip: boolean,
+): Promise<Identity> {
+  const path = identityPath(persistentDir);
+  if (existsSync(path)) {
+    const identity = JSON.parse(readFileSync(path, "utf8")) as Identity;
+    const changed = await applyCliOverrides(identity, locale, proxy, geoip);
+    if (changed) writeFileSync(path, JSON.stringify(identity, null, 2));
+    return identity;
+  }
+
+  const os_ = hostOS();
+  const fp = generateFingerprint(undefined, { operatingSystems: [os_] });
+
+  const config: Record<string, unknown> = {
+    "canvas:aaOffset": Math.floor(Math.random() * 101) - 50,
+    "canvas:aaCapOffset": Math.random() < 0.5,
+    "fonts:spacing_seed": Math.floor(Math.random() * 0x1_0000_0000),
+  };
+
+  if (proxy && geoip) {
+    mergeGeo(config, await geolocateProxy(proxy));
+  }
+
+  const identity: Identity = {
+    version: IDENTITY_VERSION,
+    created_at: new Date().toISOString(),
+    os: os_,
+    locale,
+    fingerprint: fp,
+    config,
+  };
+
+  mkdirSync(persistentDir, { recursive: true });
+  writeFileSync(path, JSON.stringify(identity, null, 2));
+  return identity;
+}
+
+/** Mutate identity with CLI-passed values. Return true if anything changed. */
+async function applyCliOverrides(
+  identity: Identity,
+  locale: string | null,
+  proxy: string | null,
+  geoip: boolean,
+): Promise<boolean> {
+  let changed = false;
+
+  if (locale !== null && identity.locale !== locale) {
+    identity.locale = locale;
+    changed = true;
+  }
+
+  if (proxy && geoip) {
+    if (!identity.config) identity.config = {};
+    const derived = await geolocateProxy(proxy);
+    if (mergeGeo(identity.config, derived)) changed = true;
+  }
+
+  return changed;
+}
+
+/** Merge proxy-derived geo into config. Return true if anything changed. */
+function mergeGeo(config: Record<string, unknown>, derived: GeoInfo | null): boolean {
+  if (!derived) return false;
+  let changed = false;
+  if (derived.timezone && config["timezone"] !== derived.timezone) {
+    config["timezone"] = derived.timezone;
+    changed = true;
+  }
+  if (derived.latitude !== undefined && derived.longitude !== undefined) {
+    if (config["geolocation:latitude"] !== derived.latitude) {
+      config["geolocation:latitude"] = derived.latitude;
+      changed = true;
+    }
+    if (config["geolocation:longitude"] !== derived.longitude) {
+      config["geolocation:longitude"] = derived.longitude;
+      changed = true;
+    }
+    if (derived.accuracy !== undefined && config["geolocation:accuracy"] !== derived.accuracy) {
+      config["geolocation:accuracy"] = derived.accuracy;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+/**
+ * Translate identity into kwargs for Camoufox / launchOptions.
+ *
+ * Returns fingerprint/os/config (always) and locale (when set). Does NOT
+ * set persistent_context / user_data_dir — the caller handles those.
+ */
+export function toLaunchOptions(identity: Identity): Record<string, unknown> {
+  const opts: Record<string, unknown> = {
+    fingerprint: identity.fingerprint,
+    os: identity.os,
+    config: { ...(identity.config || {}) },
+  };
+
+  if (identity.locale) {
+    const parts = identity.locale.split(",").map((s) => s.trim()).filter(Boolean);
+    if (parts.length > 0) {
+      opts.locale = parts.length > 1 ? parts : parts[0];
+    }
+  }
+
+  return opts;
+}
+
+interface GeoInfo {
+  timezone?: string;
+  latitude?: number;
+  longitude?: number;
+  accuracy?: number;
+}
+
+/** Return {timezone, latitude, longitude, accuracy?} from the proxy's public
+ * IP, or null if anything fails. */
+async function geolocateProxy(proxyUrl: string): Promise<GeoInfo | null> {
+  try {
+    const ip = await publicIP(proxyUrlWithAuth(proxyUrl));
+    if (!validIPv4(ip) && !validIPv6(ip)) return null;
+    const geo = await getGeolocation(ip);
+    const out: GeoInfo = {
+      timezone: geo.timezone,
+      latitude: geo.latitude,
+      longitude: geo.longitude,
+    };
+    if (geo.accuracy !== undefined) out.accuracy = geo.accuracy;
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+/** Rebuild proxy URL as scheme://user:pass@host:port for publicIP(). */
+function proxyUrlWithAuth(proxyUrl: string): string {
+  const settings = parseProxySettings(proxyUrl).proxy;
+  if (!settings.username) return settings.server;
+  const url = new URL(settings.server);
+  url.username = encodeURIComponent(settings.username);
+  url.password = encodeURIComponent(settings.password ?? "");
+  return url.href;
+}

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/js/src/server.ts

@@ -17,13 +17,13 @@ export class DaemonServer {
   private lastActivity = Date.now();
   private watchdogTimer: ReturnType<typeof setInterval> | null = null;
 
-  constructor(opts: { session?: string; headless?: boolean; timeout?: number; persistent?: string | null; proxy?: string | null; geoip?: boolean }) {
+  constructor(opts: { session?: string; headless?: boolean; timeout?: number; persistent?: string | null; proxy?: string | null; geoip?: boolean; locale?: string | null }) {
     this.session = opts.session ?? "default";
     this.headless = opts.headless ?? true;
     this.timeout = opts.timeout ?? 1800;
     this.socketPath = `/tmp/camoufox-cli-${this.session}.sock`;
     this.pidPath = `/tmp/camoufox-cli-${this.session}.pid`;
-    this.manager = new BrowserManager(opts.persistent ?? null, opts.proxy ?? null, opts.geoip ?? true);
+    this.manager = new BrowserManager(opts.persistent ?? null, opts.proxy ?? null, opts.geoip ?? true, opts.locale ?? null);
   }
 
   async start(): Promise<void> {

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "camoufox-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Anti-detect browser CLI & Skills for AI agents, powered by Camoufox"
 requires-python = ">=3.10"
 license = "MIT"

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/skills/camoufox-cli/SKILL.md

@@ -163,6 +163,8 @@ camoufox-cli cookies import auth.json
 camoufox-cli reload
 ```
 
+For long-lived accounts where the site also verifies device stability (not just the cookie), combine this with `--persistent` so the fingerprint stays fixed alongside the cookies — see the Persistent Identity section below.
+
 ### Multiple Tabs
 
 ```bash
@@ -313,9 +315,26 @@ camoufox-cli snapshot -i
 --headed               Show browser window (default: headless)
 --timeout <seconds>    Daemon idle timeout (default: 1800)
 --json                 Output as JSON instead of human-readable
---persistent [path]    Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
+--persistent [path]    Persistent identity — reuse the same fingerprint + cookies across launches
+                       (default path: ~/.camoufox-cli/profiles/<session>)
 --proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
 --no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
+--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
+```
+
+## Persistent Identity
+
+By default, every launch gets a fresh random fingerprint. Add `--persistent [path]` to reuse the same fingerprint + cookies across launches — fingerprint/OS/canvas+font seeds are frozen on first launch (delete the directory to reset); `--locale` and proxy-derived timezone/geolocation are stored but refreshed whenever you pass the flag; `--proxy` / `--no-geoip` are never stored, so pass them every launch.
+
+**Use it when** the same device should see the same fingerprint across visits (account-bound tasks, parallel independent identities, or when `cookies import/export` alone isn't enough because the site also checks device stability). **Skip it** for one-off scraping or quick debugging.
+
+```bash
+# Parallel identities, each with its own fingerprint + cookies
+camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
+camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://app.example.com
+
+# Reset an identity: just remove the directory
+rm -rf ~/.camoufox-cli/profiles/alice
 ```
 
 ## Documentation

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/skills/camoufox-cli/references/commands.md

@@ -120,6 +120,13 @@ camoufox-cli --session <name> ...    # Isolated browser session
 camoufox-cli --headed ...            # Show browser window (not headless)
 camoufox-cli --json ...              # JSON output for parsing
 camoufox-cli --timeout <seconds> ... # Daemon idle timeout (default: 1800)
-camoufox-cli --persistent [path] ... # Use persistent browser profile (default: ~/.camoufox-cli/profiles/<session>)
+camoufox-cli --persistent [path] ... # Persistent identity — reuse the same fingerprint + cookies
+                                     # across launches (default: ~/.camoufox-cli/profiles/<session>)
 camoufox-cli --proxy <url> ...      # Proxy server (e.g. http://host:port or http://user:pass@host:port)
+camoufox-cli --no-geoip ...         # Disable automatic GeoIP spoofing (auto-enabled with --proxy)
+camoufox-cli --locale <tag> ...     # Force browser locale (e.g. "en-US" or "en-US,zh-CN")
 ```
+
+### `--persistent` in detail
+
+Stores fingerprint, OS, canvas/font seeds, locale, and proxy-derived timezone/geolocation in `<path>/camoufox-cli.json` and reloads it on every launch with the same path. Fingerprint/OS/seeds are frozen — delete the directory to reset. `--locale` overwrites the stored locale when passed; `--proxy` + GeoIP re-derives timezone/geolocation each launch and writes back. `--proxy` and `--no-geoip` themselves are never stored. See the README for the full mental model.

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/src/camoufox_cli/__main__.py

@@ -15,6 +15,7 @@ def main():
     parser.add_argument("--persistent", default=None, help="Path for persistent browser profile")
     parser.add_argument("--proxy", default=None, help="Proxy server URL")
     parser.add_argument("--no-geoip", dest="geoip", action="store_false", default=True, help="Disable automatic GeoIP spoofing when using a proxy")
+    parser.add_argument("--locale", default=None, help="Force browser locale (e.g. 'en-US' or 'en-US,zh-CN')")
     args = parser.parse_args()
 
     headless = not args.headed
@@ -26,6 +27,7 @@ def main():
         persistent=args.persistent,
         proxy=args.proxy,
         geoip=args.geoip,
+        locale=args.locale,
     )
 
     print(f"[camoufox-cli] Starting daemon session={args.session} headless={headless}", file=sys.stderr)

{camoufox_cli-0.3.0 → camoufox_cli-0.5.0/.claude/worktrees/hungry-mclaren-0aa1c0}/src/camoufox_cli/browser.py

@@ -3,14 +3,19 @@
 from __future__ import annotations
 
 import base64
+import os
 
 from camoufox.sync_api import Camoufox
 from playwright.sync_api import BrowserContext, Page
 
+from .identity import load_or_create, to_launch_kwargs
 from .proxy import parse_proxy_settings
 from .refs import RefRegistry
 
 
+_MAX_HISTORY = 200
+
+
 def _ensure_browser_installed() -> None:
     """Check that the Camoufox browser binary is installed, raise if not."""
     try:
@@ -23,7 +28,7 @@ def _ensure_browser_installed() -> None:
 
 
 class BrowserManager:
-    def __init__(self, persistent: str | None = None, proxy: str | None = None, geoip: bool = True):
+    def __init__(self, persistent: str | None = None, proxy: str | None = None, geoip: bool = True, locale: str | None = None):
         self._camoufox: Camoufox | None = None
         self._context: BrowserContext | None = None
         self._page: Page | None = None
@@ -32,6 +37,7 @@ class BrowserManager:
         self._persistent = persistent
         self._proxy = proxy
         self._geoip = geoip
+        self._locale = locale
         # Camoufox spoofs history API for anti-fingerprinting,
         # so we track navigation history ourselves.
         self._history: list[str] = []
@@ -51,9 +57,26 @@ class BrowserManager:
             kwargs["proxy"] = proxy_settings
             if self._geoip:
                 kwargs["geoip"] = True
+
         if self._persistent:
+            # Persistent identity: freeze fingerprint/OS on first launch; reload
+            # it on subsequent launches. CLI-passed locale / proxy-derived geo
+            # overwrite the stored values so the file tracks current intent.
+            os.makedirs(self._persistent, exist_ok=True)
+            identity = load_or_create(
+                self._persistent,
+                locale=self._locale,
+                proxy=self._proxy,
+                geoip=self._geoip,
+            )
+            kwargs.update(to_launch_kwargs(identity))
             kwargs["persistent_context"] = True
             kwargs["user_data_dir"] = self._persistent
+        elif self._locale:
+            # Non-persistent path: locale is a one-shot override, no identity file.
+            locales = [s.strip() for s in self._locale.split(",") if s.strip()]
+            if locales:
+                kwargs["locale"] = locales if len(locales) > 1 else locales[0]
 
         self._camoufox = Camoufox(**kwargs)
         result = self._camoufox.__enter__()
@@ -127,6 +150,9 @@ class BrowserManager:
         # Truncate forward history when navigating to a new page
         self._history = self._history[:self._history_index + 1]
         self._history.append(url)
+        # Cap history to avoid unbounded growth in long-lived daemons.
+        if len(self._history) > _MAX_HISTORY:
+            self._history = self._history[-_MAX_HISTORY:]
         self._history_index = len(self._history) - 1
 
     def go_back(self) -> str | None: