diff --git a/README.md b/README.md
index 035d95d..6776240 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@
 - **Dual Profiling**: Captures both CPU and heap profiles concurrently for comprehensive performance insights
 - **Auto-Start Profiling**: Profiling starts immediately when using `flame run` (default behavior)
 - **Automatic Flamegraph Generation**: Interactive HTML flamegraphs are created automatically for both CPU and heap profiles on exit
+- **LLM-Friendly Markdown Analysis**: Generates markdown reports with hotspot analysis, ideal for AI-assisted performance debugging
 - **Sourcemap Support**: Automatically translates transpiled code locations back to original source files (TypeScript, bundled JavaScript, etc.)
 - **Clear File Path Display**: Shows exact paths and browser URLs for generated files
 - **Manual Control**: Optional manual mode with signal-based control using `SIGUSR2`
@@ -34,10 +35,11 @@ flame run server.js
 # 🔥 Heap profile written to: heap-profile-2025-08-27T12-00-00-000Z.pb
 # 🔥 Generating CPU flamegraph...
 # 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T12-00-00-000Z.html
+# 🔥 CPU markdown generated: cpu-profile-2025-08-27T12-00-00-000Z.md
 # 🔥 Generating heap flamegraph...
 # 🔥 Heap flamegraph generated: heap-profile-2025-08-27T12-00-00-000Z.html
+# 🔥 Heap markdown generated: heap-profile-2025-08-27T12-00-00-000Z.md
 # 🔥 Open file:///path/to/cpu-profile-2025-08-27T12-00-00-000Z.html in your browser to view the CPU flamegraph
-# 🔥 Open file:///path/to/heap-profile-2025-08-27T12-00-00-000Z.html in your browser to view the heap flamegraph
 ```
 
 ### Manual Profiling Mode
@@ -53,14 +55,17 @@ kill -USR2 <PID>
 flame toggle
 ```
 
-### Generate Flamegraph
+### Generate Flamegraph and Markdown
 
 ```bash
-# Generate HTML flamegraph from pprof file
+# Generate HTML flamegraph and markdown from pprof file
 flame generate cpu-profile-2024-01-01T12-00-00-000Z.pb
 
 # Specify custom output file
 flame generate -o my-flamegraph.html profile.pb.gz
+
+# Use detailed markdown format for comprehensive analysis
+flame generate --md-format=detailed profile.pb
 ```
 
 ## CLI Usage
@@ -70,7 +75,7 @@ flame [options] <command>
 
 Commands:
   run <script>           Run a script with profiling enabled
-  generate <pprof-file>  Generate HTML flamegraph from pprof file
+  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
   toggle                 Toggle profiling for running flame processes
 
 Options:
@@ -78,6 +83,7 @@ Options:
   -m, --manual             Manual profiling mode (require SIGUSR2 to start)
   -d, --delay <value>      Delay before starting profiler (ms, 'none', or 'until-started')
   -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
+      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
       --node-options <options>  Node.js CLI options to pass to the profiled process
   -h, --help               Show help message
   -v, --version            Show version number
@@ -86,7 +92,7 @@ Options:
 ## Programmatic API
 
 ```javascript
-const { startProfiling, generateFlamegraph, parseProfile } = require('@platformatic/flame')
+const { startProfiling, generateFlamegraph, generateMarkdown, parseProfile } = require('@platformatic/flame')
 
 // Start profiling a script with auto-start (default)
 const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: true })
@@ -102,6 +108,9 @@ toggleProfiler()
 // Generate interactive flamegraph from pprof file
 await generateFlamegraph('profile.pb.gz', 'flamegraph.html')
 
+// Generate LLM-friendly markdown analysis
+await generateMarkdown('profile.pb', 'analysis.md', { format: 'summary' })
+
 // Parse profile data
 const profile = await parseProfile('profile.pb')
 ```
@@ -109,9 +118,10 @@ const profile = await parseProfile('profile.pb')
 ## How It Works
 
 1. **Auto-Start Mode (Default)**: Both CPU and heap profiling begin immediately when `flame run` starts your script
-2. **Auto-Generation on Exit**: Profile (.pb) files and interactive HTML flamegraphs are automatically created for both CPU and heap profiles when the process exits
+2. **Auto-Generation on Exit**: Profile (.pb) files, interactive HTML flamegraphs, and markdown analysis files are automatically created for both CPU and heap profiles when the process exits
 3. **Manual Mode**: Use `--manual` flag to require `SIGUSR2` signals for start/stop control (no auto-HTML generation)
 4. **Interactive Visualization**: The `@platformatic/react-pprof` library generates interactive WebGL-based HTML flamegraphs for both profile types
+5. **Markdown Analysis**: The `pprof-to-md` library generates LLM-friendly markdown reports with hotspot tables for AI-assisted debugging
 
 ## Sourcemap Support
 
@@ -167,11 +177,23 @@ flame run server.js
 
 Profile files are saved with timestamps in the format:
 ```
-cpu-profile-2024-01-01T12-00-00-000Z.pb
+cpu-profile-2024-01-01T12-00-00-000Z.pb     # Binary pprof data
+cpu-profile-2024-01-01T12-00-00-000Z.html   # Interactive flamegraph
+cpu-profile-2024-01-01T12-00-00-000Z.md     # LLM-friendly markdown analysis
 heap-profile-2024-01-01T12-00-00-000Z.pb
+heap-profile-2024-01-01T12-00-00-000Z.html
+heap-profile-2024-01-01T12-00-00-000Z.md
 ```
 
-Both CPU and heap profiles share the same timestamp for easy correlation. The files are compressed Protocol Buffer format compatible with the pprof ecosystem.
+Both CPU and heap profiles share the same timestamp for easy correlation. The `.pb` files are compressed Protocol Buffer format compatible with the pprof ecosystem. The `.md` files contain hotspot analysis tables suitable for AI/LLM-assisted performance debugging.
+
+### Markdown Formats
+
+The `--md-format` option controls the markdown output:
+
+- **summary** (default): Compact hotspots table, ideal for AI triage and quick overview
+- **detailed**: Comprehensive analysis with full stack traces and detailed statistics
+- **adaptive**: Automatically chooses format based on profile complexity
 
 ## Integration with Existing Apps
 
@@ -200,14 +222,15 @@ curl http://localhost:3000
 curl http://localhost:3000
 curl http://localhost:3000
 
-# Stop the server (Ctrl-C) to automatically save profiles and generate HTML flamegraphs
+# Stop the server (Ctrl-C) to automatically save profiles and generate flamegraphs
 # You'll see the exact file paths and browser URLs in the output:
 # 🔥 CPU profile written to: cpu-profile-2025-08-27T15-30-45-123Z.pb
 # 🔥 Heap profile written to: heap-profile-2025-08-27T15-30-45-123Z.pb
 # 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T15-30-45-123Z.html
+# 🔥 CPU markdown generated: cpu-profile-2025-08-27T15-30-45-123Z.md
 # 🔥 Heap flamegraph generated: heap-profile-2025-08-27T15-30-45-123Z.html
+# 🔥 Heap markdown generated: heap-profile-2025-08-27T15-30-45-123Z.md
 # 🔥 Open file:///path/to/cpu-profile-2025-08-27T15-30-45-123Z.html in your browser to view the CPU flamegraph
-# 🔥 Open file:///path/to/heap-profile-2025-08-27T15-30-45-123Z.html in your browser to view the heap flamegraph
 ```
 
 **Manual Mode:**
@@ -296,9 +319,10 @@ kill -USR2 <PID>
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- `@datadog/pprof` for CPU profiling
-- `@platformatic/react-pprof` for flamegraph generation
+- Node.js >= 22.6.0
+- `@datadog/pprof` for CPU and heap profiling
+- `react-pprof` for flamegraph generation
+- `pprof-to-md` for markdown analysis generation
 
 ## License
 
diff --git a/bin/flame.js b/bin/flame.js
index a74d754..d66af9f 100755
--- a/bin/flame.js
+++ b/bin/flame.js
@@ -3,7 +3,7 @@
 const { parseArgs } = require('node:util')
 const fs = require('fs')
 const path = require('path')
-const { startProfiling, generateFlamegraph } = require('../lib/index.js')
+const { startProfiling, generateFlamegraph, generateMarkdown } = require('../lib/index.js')
 
 const { values: args, positionals } = parseArgs({
   args: process.argv.slice(2),
@@ -42,6 +42,9 @@ const { values: args, positionals } = parseArgs({
     'node-modules-source-maps': {
       type: 'string',
       short: 'n'
+    },
+    'md-format': {
+      type: 'string'
     }
   },
   allowPositionals: true
@@ -59,7 +62,7 @@ Usage: flame [options] <command>
 
 Commands:
   run <script>           Run a script with profiling enabled
-  generate <pprof-file>  Generate HTML flamegraph from pprof file
+  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
 
 Options:
   -o, --output <file>     Output HTML file (for generate command)
@@ -69,6 +72,7 @@ Options:
   -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
   -n, --node-modules-source-maps <mods>  Node modules to load sourcemaps from (comma-separated, e.g., "next,@next/next-server")
       --node-options <options>  Node.js CLI options to pass to the profiled process
+      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
   -h, --help             Show this help message
   -v, --version          Show version number
 
@@ -80,6 +84,7 @@ Examples:
   flame run --delay=until-started server.js                # Start profiling after next event loop tick (default)
   flame run --sourcemap-dirs=dist:build server.js          # Enable sourcemap support
   flame run -n next,@next/next-server server.js            # Load Next.js sourcemaps from node_modules
+  flame run --md-format=detailed server.js                 # Use detailed markdown format
   flame run --node-options="--require ts-node/register" server.ts     # With Node.js options
   flame run --node-options="--import ./loader.js --max-old-space-size=4096" server.js
   flame generate profile.pb.gz
@@ -136,12 +141,20 @@ async function main () {
           ? args['node-modules-source-maps'].split(',').map(s => s.trim())
           : undefined
 
+        // Parse markdown format option
+        const mdFormat = args['md-format'] || 'summary'
+        if (!['summary', 'detailed', 'adaptive'].includes(mdFormat)) {
+          console.error(`Error: Invalid md-format value '${mdFormat}'. Must be 'summary', 'detailed', or 'adaptive'.`)
+          process.exit(1)
+        }
+
         const { pid, process: childProcess } = startProfiling(script, scriptArgs, {
           autoStart,
           nodeOptions,
           delay,
           sourcemapDirs,
-          nodeModulesSourceMaps
+          nodeModulesSourceMaps,
+          mdFormat
         })
 
         console.log(`🔥 Started profiling process ${pid}`)
@@ -188,13 +201,30 @@ async function main () {
           process.exit(1)
         }
 
+        // Parse markdown format option
+        const mdFormat = args['md-format'] || 'summary'
+        if (!['summary', 'detailed', 'adaptive'].includes(mdFormat)) {
+          console.error(`Error: Invalid md-format value '${mdFormat}'. Must be 'summary', 'detailed', or 'adaptive'.`)
+          process.exit(1)
+        }
+
         const outputFile = args.output || `${path.basename(pprofFile, path.extname(pprofFile))}.html`
+        const mdOutputFile = outputFile.replace(/\.html$/, '.md')
         const profileType = path.basename(pprofFile).includes('heap') ? 'Heap' : 'CPU'
 
         console.log(`🔥 Generating ${profileType} flamegraph from ${pprofFile}...`)
         await generateFlamegraph(pprofFile, outputFile)
         console.log(`🔥 ${profileType} flamegraph generated: ${outputFile}`)
         console.log(`🔥 Open file://${path.resolve(outputFile)} in your browser to view the flamegraph`)
+
+        // Generate markdown
+        console.log(`🔥 Generating ${profileType} markdown analysis...`)
+        try {
+          await generateMarkdown(pprofFile, mdOutputFile, { format: mdFormat })
+          console.log(`🔥 ${profileType} markdown generated: ${mdOutputFile}`)
+        } catch (error) {
+          console.error(`Warning: Failed to generate ${profileType} markdown:`, error.message)
+        }
         break
       }
 
diff --git a/lib/index.js b/lib/index.js
index 3b8f397..7a3cc57 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -24,7 +24,8 @@ function startProfiling (script, args = [], options = {}) {
     ...process.env,
     ...options.env,
     FLAME_AUTO_START: options.autoStart ? 'true' : 'false',
-    FLAME_DELAY: options.delay ?? 'until-started'
+    FLAME_DELAY: options.delay ?? 'until-started',
+    FLAME_MD_FORMAT: options.mdFormat || 'summary'
   }
 
   // Add sourcemap configuration if provided
@@ -142,8 +143,27 @@ async function generateFlamegraph (pprofPath, outputPath) {
   })
 }
 
+/**
+ * Generate LLM-friendly markdown analysis from a pprof file
+ * @param {string} pprofPath - Path to the pprof file
+ * @param {string} outputPath - Path to write the markdown file
+ * @param {object} options - Options for markdown generation
+ * @param {string} options.format - Markdown format: 'summary' (default), 'detailed', or 'adaptive'
+ * @returns {Promise<object>} Result with outputPath
+ */
+async function generateMarkdown (pprofPath, outputPath, options = {}) {
+  const { convert } = await import('pprof-to-md')
+  const markdown = convert(pprofPath, {
+    format: options.format || 'summary',
+    profileName: path.basename(pprofPath)
+  })
+  fs.writeFileSync(outputPath, markdown)
+  return { outputPath }
+}
+
 module.exports = {
   startProfiling,
   parseProfile,
-  generateFlamegraph
+  generateFlamegraph,
+  generateMarkdown
 }
diff --git a/package.json b/package.json
index 0793cf0..3c2ab7b 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,7 @@
     "@datadog/pprof": "^5.9.0",
     "fastify": "^5.5.0",
     "pprof-format": "^2.2.1",
+    "pprof-to-md": "^0.1.0",
     "react-pprof": "^1.4.0"
   },
   "devDependencies": {
@@ -59,7 +60,7 @@
     "neostandard": "^0.12.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.6.0"
   },
   "pre-commit": [
     "lint",
diff --git a/preload.js b/preload.js
index 9c5f3fa..a19d0f8 100644
--- a/preload.js
+++ b/preload.js
@@ -11,6 +11,7 @@ let isCpuProfilerRunning = false
 let isHeapProfilerRunning = false
 let sourceMapper = null
 const autoStart = process.env.FLAME_AUTO_START === 'true'
+const mdFormat = process.env.FLAME_MD_FORMAT || 'summary'
 
 // Initialize sourcemap support if enabled
 const sourcemapDirs = process.env.FLAME_SOURCEMAP_DIRS
@@ -215,6 +216,16 @@ function generateFlamegraph (pprofPath, outputPath) {
   })
 }
 
+async function generateMarkdown (pprofPath, outputPath, format = 'summary') {
+  const { convert } = await import('pprof-to-md')
+  const markdown = convert(pprofPath, {
+    format,
+    profileName: path.basename(pprofPath)
+  })
+  fs.writeFileSync(outputPath, markdown)
+  return { outputPath }
+}
+
 function stopProfilerQuick () {
   if (!isCpuProfilerRunning && !isHeapProfilerRunning) {
     return null
@@ -293,6 +304,16 @@ async function stopProfilerAndSave (generateHtml = false) {
         } catch (error) {
           console.error('Warning: Failed to generate CPU flamegraph:', error.message)
         }
+
+        // Generate markdown analysis
+        const mdFilename = cpuFilename.replace('.pb', '.md')
+        console.log('🔥 Generating CPU markdown analysis...')
+        try {
+          await generateMarkdown(cpuFilename, mdFilename, mdFormat)
+          console.log(`🔥 CPU markdown generated: ${mdFilename}`)
+        } catch (error) {
+          console.error('Warning: Failed to generate CPU markdown:', error.message)
+        }
       }
     }
 
@@ -319,6 +340,16 @@ async function stopProfilerAndSave (generateHtml = false) {
         } catch (error) {
           console.error('Warning: Failed to generate heap flamegraph:', error.message)
         }
+
+        // Generate markdown analysis
+        const mdFilename = heapFilename.replace('.pb', '.md')
+        console.log('🔥 Generating heap markdown analysis...')
+        try {
+          await generateMarkdown(heapFilename, mdFilename, mdFormat)
+          console.log(`🔥 Heap markdown generated: ${mdFilename}`)
+        } catch (error) {
+          console.error('Warning: Failed to generate heap markdown:', error.message)
+        }
       }
     }
 
@@ -350,6 +381,17 @@ function generateHtmlAsync (filenames) {
       .catch(error => {
         console.error(`Warning: Failed to generate ${profileType} flamegraph:`, error.message)
       })
+
+    // Generate markdown analysis
+    const mdFilename = filename.replace('.pb', '.md')
+    console.log(`🔥 Generating ${profileType} markdown analysis...`)
+    generateMarkdown(filename, mdFilename, mdFormat)
+      .then(() => {
+        console.log(`🔥 ${profileType} markdown generated: ${mdFilename}`)
+      })
+      .catch(error => {
+        console.error(`Warning: Failed to generate ${profileType} markdown:`, error.message)
+      })
   })
 }
 
diff --git a/test/cli.test.js b/test/cli.test.js
index 0a1ae64..097e44a 100644
--- a/test/cli.test.js
+++ b/test/cli.test.js
@@ -285,6 +285,86 @@ test('CLI should accept --node-options flag', async (t) => {
   assert.ok(stdout.includes('--max-old-space-size=512'), 'Should pass node options to the profiled process')
 })
 
+test('CLI help should include md-format flag', async (t) => {
+  const result = await runCli(['--help'])
+
+  assert.strictEqual(result.code, 0, 'Should exit successfully')
+  assert.ok(result.stdout.includes('--md-format'), 'Should show --md-format option')
+  assert.ok(result.stdout.includes('summary'), 'Should mention summary format')
+  assert.ok(result.stdout.includes('detailed'), 'Should mention detailed format')
+  assert.ok(result.stdout.includes('adaptive'), 'Should mention adaptive format')
+})
+
+test('CLI should accept --md-format flag for run command', async (t) => {
+  // Create a simple test script that checks for the env var
+  const testScript = path.join(__dirname, 'temp-md-format-test.js')
+  fs.writeFileSync(testScript, `
+    console.log('FLAME_MD_FORMAT:', process.env.FLAME_MD_FORMAT);
+    console.log('Test completed');
+    process.exit(0);
+  `)
+
+  const child = spawn('node', [cliPath, 'run', '--md-format=detailed', testScript], {
+    stdio: 'pipe'
+  })
+
+  let stdout = ''
+
+  child.stdout.on('data', (data) => {
+    stdout += data.toString()
+  })
+
+  child.stderr.on('data', (data) => {
+    // Consume stderr to prevent blocking
+  })
+
+  // Wait for the process to complete or timeout after 5 seconds
+  const [exitCode] = await Promise.race([
+    once(child, 'close'),
+    new Promise((resolve) => {
+      setTimeout(() => {
+        child.kill('SIGKILL')
+        resolve([-1])
+      }, 5000)
+    })
+  ])
+
+  // Clean up
+  fs.unlinkSync(testScript)
+
+  // Verify the env var was passed correctly
+  assert.notStrictEqual(exitCode, -1, 'Process should complete before timeout')
+  assert.ok(stdout.includes('FLAME_MD_FORMAT: detailed'), 'Should pass md-format to the profiled process')
+})
+
+test('CLI run command should reject invalid md-format', async (t) => {
+  // Create a simple test script
+  const testScript = path.join(__dirname, 'temp-invalid-md-format-test.js')
+  fs.writeFileSync(testScript, 'process.exit(0);')
+
+  const result = await runCli(['run', '--md-format=invalid', testScript])
+
+  // Clean up
+  fs.unlinkSync(testScript)
+
+  assert.strictEqual(result.code, 1, 'Should exit with error code')
+  assert.ok(result.stderr.includes('Invalid md-format'), 'Should show invalid md-format error')
+})
+
+test('CLI generate command should reject invalid md-format', async (t) => {
+  // Create a mock pprof file
+  const mockProfile = path.join(__dirname, 'temp-invalid-md-format-generate.pb')
+  fs.writeFileSync(mockProfile, Buffer.alloc(100))
+
+  const result = await runCli(['generate', '--md-format=invalid', mockProfile])
+
+  // Clean up
+  fs.unlinkSync(mockProfile)
+
+  assert.strictEqual(result.code, 1, 'Should exit with error code')
+  assert.ok(result.stderr.includes('Invalid md-format'), 'Should show invalid md-format error')
+})
+
 test('CLI should handle SIGINT gracefully', async (t) => {
   // Create a simple test script that runs for a while
   const testScript = path.join(__dirname, 'temp-long-script.js')
@@ -329,7 +409,7 @@ test('CLI should handle SIGINT gracefully', async (t) => {
   const files = fs.readdirSync(__dirname)
   files.forEach(file => {
     if ((file.startsWith('cpu-profile-') || file.startsWith('heap-profile-')) &&
-        (file.endsWith('.pb') || file.endsWith('.html') || file.endsWith('.js'))) {
+        (file.endsWith('.pb') || file.endsWith('.html') || file.endsWith('.js') || file.endsWith('.md'))) {
       fs.unlinkSync(path.join(__dirname, file))
     }
   })
diff --git a/test/integration.test.js b/test/integration.test.js
index 3527095..4170d82 100644
--- a/test/integration.test.js
+++ b/test/integration.test.js
@@ -97,8 +97,12 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
   // Check that HTML files were also auto-generated (with some tolerance for async generation)
   const autoCpuHtmlFile = cpuProfilePath.replace('.pb', '.html')
   const autoHeapHtmlFile = heapProfilePath.replace('.pb', '.html')
+  const autoCpuMdFile = cpuProfilePath.replace('.pb', '.md')
+  const autoHeapMdFile = heapProfilePath.replace('.pb', '.md')
   const cpuHtmlExists = fs.existsSync(autoCpuHtmlFile)
   const heapHtmlExists = fs.existsSync(autoHeapHtmlFile)
+  const cpuMdExists = fs.existsSync(autoCpuMdFile)
+  const heapMdExists = fs.existsSync(autoHeapMdFile)
 
   if (cpuHtmlExists) {
     console.log('✅ CPU HTML file auto-generated successfully')
@@ -113,6 +117,13 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
     console.log('⚠️ CPU HTML file not generated yet (async generation in progress)')
   }
 
+  if (cpuMdExists) {
+    console.log('✅ CPU markdown file auto-generated successfully')
+    assert.ok(fs.statSync(autoCpuMdFile).size > 0, 'CPU markdown file should not be empty')
+  } else {
+    console.log('⚠️ CPU markdown file not generated yet (async generation in progress)')
+  }
+
   if (heapHtmlExists) {
     console.log('✅ Heap HTML file auto-generated successfully')
     assert.ok(fs.statSync(autoHeapHtmlFile).size > 0, 'Heap HTML file should not be empty')
@@ -126,6 +137,13 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
     console.log('⚠️ Heap HTML file not generated yet (async generation in progress)')
   }
 
+  if (heapMdExists) {
+    console.log('✅ Heap markdown file auto-generated successfully')
+    assert.ok(fs.statSync(autoHeapMdFile).size > 0, 'Heap markdown file should not be empty')
+  } else {
+    console.log('⚠️ Heap markdown file not generated yet (async generation in progress)')
+  }
+
   // Step 3: Generate flamegraph from the CPU profile
   try {
     require.resolve('react-pprof/cli.js')
@@ -187,6 +205,11 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
     fs.unlinkSync(jsFile)
   }
 
+  const mdFile = htmlFile.replace('.html', '.md')
+  if (fs.existsSync(mdFile)) {
+    fs.unlinkSync(mdFile)
+  }
+
   // Clean up auto-generated CPU files too
   if (fs.existsSync(autoCpuHtmlFile)) {
     fs.unlinkSync(autoCpuHtmlFile)
@@ -197,6 +220,10 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
     fs.unlinkSync(autoCpuJsFile)
   }
 
+  if (fs.existsSync(autoCpuMdFile)) {
+    fs.unlinkSync(autoCpuMdFile)
+  }
+
   // Clean up auto-generated heap files
   if (fs.existsSync(autoHeapHtmlFile)) {
     fs.unlinkSync(autoHeapHtmlFile)
@@ -206,6 +233,10 @@ test('integration: full workflow from profiling to flamegraph generation', { ski
   if (fs.existsSync(autoHeapJsFile)) {
     fs.unlinkSync(autoHeapJsFile)
   }
+
+  if (fs.existsSync(autoHeapMdFile)) {
+    fs.unlinkSync(autoHeapMdFile)
+  }
 })
 
 test('integration: Windows compatibility test', { skip: process.platform !== 'win32' ? 'Windows-only test' : false }, async (t) => {
diff --git a/test/lib.test.js b/test/lib.test.js
index c3300b2..a920d78 100644
--- a/test/lib.test.js
+++ b/test/lib.test.js
@@ -5,7 +5,7 @@ const assert = require('node:assert')
 const fs = require('fs')
 const path = require('path')
 const { once } = require('node:events')
-const { startProfiling, parseProfile, generateFlamegraph } = require('../lib/index.js')
+const { startProfiling, parseProfile, generateFlamegraph, generateMarkdown } = require('../lib/index.js')
 
 test('startProfiling should spawn process with preload script', async (t) => {
   // Create a simple test script
@@ -132,3 +132,98 @@ test('generateFlamegraph should create HTML file', async (t) => {
   const jsFile = outputFile.replace('.html', '.js')
   if (fs.existsSync(jsFile)) fs.unlinkSync(jsFile)
 })
+
+test('generateMarkdown should create markdown file from pprof', async (t) => {
+  // Skip this test if pprof-to-md is not available
+  try {
+    await import('pprof-to-md')
+  } catch (error) {
+    t.skip('pprof-to-md not available')
+    return
+  }
+
+  // Create a mock pprof file (this would need actual pprof data in real scenario)
+  const mockProfile = path.join(__dirname, 'temp-profile-md.pb')
+  const outputFile = path.join(__dirname, 'temp-output.md')
+
+  // Create minimal pprof data (this is just for testing the file handling)
+  fs.writeFileSync(mockProfile, Buffer.alloc(100))
+
+  try {
+    await generateMarkdown(mockProfile, outputFile, { format: 'summary' })
+    // The actual converter might fail with invalid data, but we test the interface
+  } catch (error) {
+    // Expected to fail with mock data, but should be a converter error, not file system error
+    assert.ok(
+      error.message.includes('decode') ||
+      error.message.includes('Profile') ||
+      error.message.includes('pprof') ||
+      error.message.includes('convert') ||
+      error.message.includes('Sample type') ||
+      error.message.includes('not found'),
+      `Should fail with profile parsing error, not file system error. Got: ${error.message}`
+    )
+  }
+
+  // Clean up
+  if (fs.existsSync(mockProfile)) fs.unlinkSync(mockProfile)
+  if (fs.existsSync(outputFile)) fs.unlinkSync(outputFile)
+})
+
+test('generateMarkdown should use default format when not specified', async (t) => {
+  // Skip this test if pprof-to-md is not available
+  try {
+    await import('pprof-to-md')
+  } catch (error) {
+    t.skip('pprof-to-md not available')
+    return
+  }
+
+  // Create a mock pprof file
+  const mockProfile = path.join(__dirname, 'temp-profile-md-default.pb')
+  const outputFile = path.join(__dirname, 'temp-output-default.md')
+
+  fs.writeFileSync(mockProfile, Buffer.alloc(100))
+
+  try {
+    // Call without format option - should default to 'summary'
+    await generateMarkdown(mockProfile, outputFile)
+  } catch (error) {
+    // Expected to fail with mock data
+    assert.ok(error.message, 'Should have error message')
+  }
+
+  // Clean up
+  if (fs.existsSync(mockProfile)) fs.unlinkSync(mockProfile)
+  if (fs.existsSync(outputFile)) fs.unlinkSync(outputFile)
+})
+
+test('generateMarkdown should accept different format options', async (t) => {
+  // Skip this test if pprof-to-md is not available
+  try {
+    await import('pprof-to-md')
+  } catch (error) {
+    t.skip('pprof-to-md not available')
+    return
+  }
+
+  const mockProfile = path.join(__dirname, 'temp-profile-md-formats.pb')
+  const outputFile = path.join(__dirname, 'temp-output-formats.md')
+
+  fs.writeFileSync(mockProfile, Buffer.alloc(100))
+
+  const formats = ['summary', 'detailed', 'adaptive']
+
+  for (const format of formats) {
+    try {
+      await generateMarkdown(mockProfile, outputFile, { format })
+    } catch (error) {
+      // Expected to fail with mock data, but the format option should be accepted
+      assert.ok(error.message, `Should have error message for format: ${format}`)
+    }
+  }
+
+  // Clean up
+  if (fs.existsSync(mockProfile)) fs.unlinkSync(mockProfile)
+  if (fs.existsSync(outputFile)) fs.unlinkSync(outputFile)
+})