Add --profile flag for persistent browser profiles (#68)

* Add --profile flag for persistent browser profiles

Adds support for persistent browser profiles that preserve cookies,
localStorage, and login sessions across browser restarts.

Changes:
- Add --profile <path> CLI flag (flags.rs)
- Add AGENT_BROWSER_PROFILE environment variable support
- Add profile field to LaunchCommand type (types.ts)
- Use launchPersistentContext when profile is specified (browser.ts)
- Update help text and README with documentation

Usage:
  agent-browser --profile ~/.myapp-profile open myapp.com

This enables AI agents to maintain authenticated sessions across
browser restarts without re-authenticating each time.

* Expand tilde in profile path to home directory

* fix: add missing profile field to test Flags struct

---------

Co-authored-by: Chris Tate <chris@ctate.dev>

cli/src/commands.rs

@@ -1114,6 +1114,7 @@ mod tests {
             executable_path: None,
             extensions: Vec::new(),
             cdp: None,
+            profile: None,
             proxy: None,
             proxy_bypass: None,
             args: None,

cli/src/flags.rs

@@ -10,6 +10,7 @@ pub struct Flags {
     pub executable_path: Option<String>,
     pub cdp: Option<String>,
     pub extensions: Vec<String>,
+    pub profile: Option<String>,
     pub proxy: Option<String>,
     pub proxy_bypass: Option<String>,
     pub args: Option<String>,
@@ -33,6 +34,7 @@ pub fn parse_flags(args: &[String]) -> Flags {
         executable_path: env::var("AGENT_BROWSER_EXECUTABLE_PATH").ok(),
         cdp: None,
         extensions: extensions_env,
+        profile: env::var("AGENT_BROWSER_PROFILE").ok(),
         proxy: env::var("AGENT_BROWSER_PROXY").ok(),
         proxy_bypass: env::var("AGENT_BROWSER_PROXY_BYPASS").ok(),
         args: env::var("AGENT_BROWSER_ARGS").ok(),
@@ -77,6 +79,12 @@ pub fn parse_flags(args: &[String]) -> Flags {
                     i += 1;
                 }
             }
+            "--profile" => {
+                if let Some(s) = args.get(i + 1) {
+                    flags.profile = Some(s.clone());
+                    i += 1;
+                }
+            }
             "--proxy" => {
                 if let Some(p) = args.get(i + 1) {
                     flags.proxy = Some(p.clone());
@@ -127,6 +135,7 @@ pub fn clean_args(args: &[String]) -> Vec<String> {
         "--executable-path",
         "--cdp",
         "--extension",
+        "--profile",
         "--proxy",
         "--proxy-bypass",
         "--args",

cli/src/main.rs

@@ -217,6 +217,7 @@ fn main() {
         let ignored_flags: Vec<&str> = [
             flags.executable_path.as_ref().map(|_| "--executable-path"),
             if has_extensions { Some("--extension") } else { None },
+            flags.profile.as_ref().map(|_| "--profile"),
             flags.args.as_ref().map(|_| "--args"),
             flags.user_agent.as_ref().map(|_| "--user-agent"),
             flags.proxy.as_ref().map(|_| "--proxy"),
@@ -358,8 +359,8 @@ fn main() {
         }
     }
 
-    // Launch headed browser or proxy if flags are set (without CDP or provider)
-    if (flags.headed || flags.proxy.is_some() || flags.args.is_some() || flags.user_agent.is_some()) && flags.cdp.is_none() && flags.provider.is_none() {
+    // Launch headed browser or configure browser options (without CDP or provider)
+    if (flags.headed || flags.profile.is_some() || flags.proxy.is_some() || flags.args.is_some() || flags.user_agent.is_some()) && flags.cdp.is_none() && flags.provider.is_none() {
         let mut launch_cmd = json!({
             "id": gen_id(),
             "action": "launch",
@@ -369,6 +370,11 @@ fn main() {
         let cmd_obj = launch_cmd.as_object_mut()
             .expect("json! macro guarantees object type");
 
+        // Add profile path if specified
+        if let Some(ref profile_path) = flags.profile {
+            cmd_obj.insert("profile".to_string(), json!(profile_path));
+        }
+
         if let Some(ref proxy_str) = flags.proxy {
             let mut proxy_obj = parse_proxy(proxy_str);
             // Add bypass if specified

cli/src/output.rs

@@ -1412,6 +1412,7 @@ Snapshot Options:
 
 Options:
   --session <name>           Isolated session (or AGENT_BROWSER_SESSION env)
+  --profile <path>           Persistent browser profile (or AGENT_BROWSER_PROFILE env)
   --headers <json>           HTTP headers scoped to URL's origin (for auth)
   --executable-path <path>   Custom browser executable (or AGENT_BROWSER_EXECUTABLE_PATH)
   --extension <path>         Load browser extensions (repeatable)
@@ -1443,6 +1444,7 @@ Examples:
   agent-browser get text @e1
   agent-browser screenshot --full
   agent-browser --cdp 9222 snapshot      # Connect via CDP port
+  agent-browser --profile ~/.myapp open example.com  # Persistent profile
 "#
     );
 }