diff --git a/src/browser.ts b/src/browser.ts
index 8c9be5f1..36b59e90 100644
--- a/src/browser.ts
+++ b/src/browser.ts
@@ -20,10 +20,16 @@ export class SentienceBrowser {
   constructor(
     apiKey?: string,
     apiUrl?: string,
-    headless: boolean = false
+    headless?: boolean
   ) {
     this._apiKey = apiKey;
-    this.headless = headless;
+    // Default to headless=True in CI (no X server), headless=False locally
+    if (headless === undefined) {
+      const ci = process.env.CI?.toLowerCase();
+      this.headless = ci === 'true' || ci === '1' || ci === 'yes';
+    } else {
+      this.headless = headless;
+    }
     // Only set apiUrl if apiKey is provided, otherwise undefined (free tier)
     // Default to https://api.sentienceapi.com if apiKey is provided but apiUrl is not
     if (apiKey) {
diff --git a/tests/generator.test.ts b/tests/generator.test.ts
index 68a08fa0..508e1ed4 100644
--- a/tests/generator.test.ts
+++ b/tests/generator.test.ts
@@ -10,7 +10,7 @@ import { createTestBrowser } from './test-utils';
 
 describe('ScriptGenerator', () => {
   it('should generate Python code', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -37,7 +37,7 @@ describe('ScriptGenerator', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should generate TypeScript code', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -63,7 +63,7 @@ describe('ScriptGenerator', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should save Python script', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -90,7 +90,7 @@ describe('ScriptGenerator', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should save TypeScript script', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
diff --git a/tests/inspector.test.ts b/tests/inspector.test.ts
index 59ec1823..45a133d8 100644
--- a/tests/inspector.test.ts
+++ b/tests/inspector.test.ts
@@ -7,7 +7,7 @@ import { createTestBrowser } from './test-utils';
 
 describe('Inspector', () => {
   it('should start and stop', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
diff --git a/tests/recorder.test.ts b/tests/recorder.test.ts
index 411b439d..498d0e2f 100644
--- a/tests/recorder.test.ts
+++ b/tests/recorder.test.ts
@@ -10,7 +10,7 @@ import { createTestBrowser } from './test-utils';
 
 describe('Recorder', () => {
   it('should start and stop', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -29,7 +29,7 @@ describe('Recorder', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should record click events', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -53,7 +53,7 @@ describe('Recorder', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should record type events', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -77,7 +77,7 @@ describe('Recorder', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should mask sensitive text', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -99,7 +99,7 @@ describe('Recorder', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should save and load trace', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
diff --git a/tests/snapshot.test.ts b/tests/snapshot.test.ts
index 6e40b650..a6615951 100644
--- a/tests/snapshot.test.ts
+++ b/tests/snapshot.test.ts
@@ -7,7 +7,7 @@ import { createTestBrowser } from './test-utils';
 
 describe('Snapshot', () => {
   it('should take a basic snapshot', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
@@ -25,7 +25,7 @@ describe('Snapshot', () => {
   }, 60000); // 60 seconds - browser startup can be slow
 
   it('should have valid element structure', async () => {
-    const browser = await createTestBrowser(false);
+    const browser = await createTestBrowser();
 
     try {
       await browser.getPage().goto('https://example.com');
diff --git a/tests/stealth.test.ts b/tests/stealth.test.ts
index 2557e89e..5b358fd4 100644
--- a/tests/stealth.test.ts
+++ b/tests/stealth.test.ts
@@ -15,7 +15,8 @@ describe('Stealth Mode / Bot Evasion', () => {
   let browser: SentienceBrowser;
 
   beforeAll(async () => {
-    browser = new SentienceBrowser(undefined, undefined, false);
+    // Auto-detect headless mode (headless in CI, headed locally)
+    browser = new SentienceBrowser(undefined, undefined, undefined);
     await browser.start();
   });
 
diff --git a/tests/test-utils.ts b/tests/test-utils.ts
index bc082126..a3431c9c 100644
--- a/tests/test-utils.ts
+++ b/tests/test-utils.ts
@@ -6,8 +6,9 @@ import { SentienceBrowser } from '../src';
 
 /**
  * Creates a browser instance and starts it with better error handling
+ * Auto-detects headless mode based on CI environment (headless in CI, headed locally)
  */
-export async function createTestBrowser(headless: boolean = false): Promise<SentienceBrowser> {
+export async function createTestBrowser(headless?: boolean): Promise<SentienceBrowser> {
   const browser = new SentienceBrowser(undefined, undefined, headless);
   try {
     await browser.start();