Recipes

Practical Recipes

Working commands for real autonomous worker jobs — copy, paste, adapt. Each recipe starts from a common workflow and shows the exact command plus what to expect.

Getting Started

Quick Start Recipes

Four commands to get productive in under five minutes. Run a search, watch for changes, push to CRM, and recover from failures.

Run a first research pass

bash

fathom run "Find CTOs at 50-200 person fintech startups in London, verify emails"

Start with a focused query and one region/sector. Findings land in ./research-output/ with sources baked in.

Re-run and alert on changes

bash

fathom run "..." --repeat 3600

Optional watch mode re-runs every 3600s. Diffing and email / Telegram / webhook notifications require the corresponding integrations to be configured.

Push a verified list to CRM

bash

fathom contacts push-crm

Syncs contacts.db to amoCRM / Bitrix24 / HubSpot when those integrations are configured. Review the resulting CRM records according to your provider's matching policy.

Recover a crashed campaign

bash

fathom resume

Find interrupted sessions, keep completed sub-agents, re-run the pending ones, and finish synthesis.

Lead Generation

OSINT & Lead Generation Recipes

Find, enrich, and verify contacts at scale. These recipes cover the full pipeline from raw search to verified, enriched lead lists ready for outreach.

Find CTOs at fintech startups in London

bash

fathom run "Find all CTOs and VP Engineering at fintech startups in London with 10-200 employees. Verify each email address. Include company size, funding stage, and tech stack." -o ./leads/london-fintech-ctos

The agent will search LinkedIn, Crunchbase, and company websites. Email verification runs via MX check and SMTP probe. Results include confidence scores for each contact.

Marketing directors at SaaS companies in Berlin

bash

fathom run "Search for marketing directors and CMOs at SaaS companies headquartered in Berlin. Enrich each person with LinkedIn profile URL, current role tenure, and recent posts."

Enrichment flags pull additional data from each source. LinkedIn enrichment grabs headline, summary, and recent activity without scraping — uses public API data.

Monitor news about a competitor

bash

fathom run "Monitor all news, press releases, blog posts, and social mentions about Acme Corp. Alert me on funding announcements, executive changes, product launches, and partnership deals." --repeat 1800

Watch mode keeps the session alive and re-checks sources every 30 minutes. The diff engine compares new results against prior runs and only alerts on genuinely new items.

Build supplier list from business directories

bash

fathom run "Build a comprehensive list of industrial valve suppliers in the Gulf Cooperation Council region. Scrape business directories, trade association member lists, and exhibition exhibitor pages. De-duplicate by company name and website."

Directory scraping respects robots.txt and rate limits automatically. Review repeated company names and URLs before using the list.

Find decision-makers at recently funded companies

bash

fathom run "Find decision-makers (CEO, CTO, VP Sales, VP Engineering) at B2B SaaS companies that raised Series A or B in the past 90 days in the US. Include funding amount, lead investor, and hiring signals." -o ./leads/fresh-funded

Cross-references Crunchbase funding data with LinkedIn job titles. Hiring signals detected from careers pages and job board postings. Sorted by funding date descending.

Search social media for technology mentions

bash

fathom run "Search Twitter/X, Reddit, Hacker News, and dev.to for people actively discussing Apache Kafka in production. Extract author profiles, engagement metrics, and company affiliations where available."

Social search covers public posts only. The agent identifies technical practitioners vs. marketers by analyzing post content and engagement patterns. Results include permalink to each source.

Parse conference speaker list and enrich

bash

fathom run "Parse the speaker list from https://kccnceu2025.sched.com. For each speaker, find their current company, title, LinkedIn, Twitter, email (if public), and recent publications or talks." -o ./speakers/kccn-eu-2025

The agent crawls the schedule page, extracts speaker names and bios, then enriches each person in parallel. Rate limiting is handled per-domain automatically.

Find companies using a specific tech stack

bash

fathom run "Find companies in the EU that are using Rust in production. Cross-reference job postings mentioning Rust, GitHub organizations with active Rust repos, conference talks, and blog posts about Rust adoption. Identify CTOs and principal engineers."

Tech stack detection uses multiple signals: job postings, GitHub activity, blog posts, Stack Overflow jobs, and conference talks. Confidence scoring weights each signal independently.

Deep Research

Research & Analysis Recipes

Go beyond lead generation. These recipes perform deep investigations into companies, people, supply chains, and markets — with structured, citable outputs.

Deep-dive: company tech stack and team

bash

fathom run "Perform a deep-dive analysis of Stripe's technology stack. Map all technologies, frameworks, and infrastructure used. Identify key engineers, their backgrounds, and open-source contributions. Include blog posts about architecture decisions." -o ./analysis/stripe-tech

Deep mode uses more sub-agents and longer context windows. The agent triangulates from multiple sources: GitHub, engineering blogs, job postings, conference talks, and Stack Overflow activity.

Compare 5 competitors across 20 dimensions

bash

fathom run "Compare Datadog, New Relic, Dynatrace, Splunk, and Grafana Labs across these 20 dimensions: pricing model, free tier limits, APM capabilities, log management, infrastructure monitoring, alerting, dashboarding, API quality, SDK languages, cloud integrations, on-prem options, compliance certs, market share, revenue growth, employee count, engineering team size, open-source contributions, community size, documentation quality, and enterprise features." -o ./competitive/comparison

The agent structures each dimension as a separate sub-task for parallel execution. The table output formats findings into a structured comparison grid with confidence indicators.

Track regulatory changes in an industry

bash

fathom run "Track all regulatory changes, proposed rules, enforcement actions, and guidance documents in the US fintech/payments space over the past 30 days. Cover CFPB, OCC, FDIC, FinCEN, SEC, and state-level regulators. Classify each by impact level and affected business models." --repeat 86400

Regulatory monitoring requires reliable source tracking. The agent monitors .gov RSS feeds, Federal Register API, and regulatory news outlets. Daily re-runs detect new filings and classify them.

Analyze GitHub repository contributors

bash

fathom run "Analyze the top 50 contributors to the vercel/next.js GitHub repository. For each contributor, find their current employer, LinkedIn profile, Twitter account, personal website, other notable open-source projects, and conference speaking history." -o ./oss/nextjs-contributors

GitHub API is used for contributor data; enrichment pulls from public profiles. The agent handles GitHub rate limits with automatic token rotation if GITHUB_TOKEN is set.

Research a person's full public footprint

bash

fathom run "Research the full public footprint of Satya Nadella. Compile: career history, education, published articles, conference keynotes, podcast appearances, patent filings, board memberships, philanthropic activities, and social media presence. Cross-reference across LinkedIn, Wikipedia, news archives, and SEC filings." -o ./people/satya-nadella

Person research synthesizes data from 15+ source categories. The agent respects privacy boundaries — only publicly available information is included. Sources are cited for every claim.

Investigate a supply chain

bash

fathom run "Map the supply chain of Tesla's battery production. Identify primary cell suppliers (CATL, Panasonic, BYD), their raw material suppliers (lithium, cobalt, nickel miners), processing facilities, and logistics partners. Flag any single-source dependencies or geopolitical risks." -o ./supply-chain/tesla-battery

Supply chain mapping uses SEC filings (10-K supplier disclosures), trade databases, shipping records, and industry reports. The agent builds a hierarchical supplier tree with risk annotations.

Monitor job postings for strategy signals

bash

fathom run "Monitor job postings at Databricks, Snowflake, and dbt Labs over the past 60 days. Classify each posting by department, seniority, and technology. Detect hiring surges, new team formations, and technology adoption signals. Compare hiring velocity across the three companies." --repeat 86400 -o ./signals/hiring-trends

Job posting analysis reveals strategic intent before public announcements. The agent classifies roles by team/function and tracks velocity changes. A hiring surge in a new area often precedes product launches.

Knowledge Management

Memory & Knowledge Recipes

Build persistent knowledge across sessions. The memory graph stores entities, facts, and relationships that compound over time — making each new session smarter than the last.

Build a knowledge base from research sessions

bash

fathom memory distill --session latest

Distills facts from the latest session into the configured memory graph. Memory commands require the memory subsystem to be enabled in configuration.

Search memory for company facts

bash

fathom memory search "Stripe"

Searches the memory graph for all facts related to Stripe. Results include facts from every past session, ranked by recency and confidence. Useful for quickly recalling prior research.

Distill session facts into permanent knowledge

bash

fathom memory distill --session latest

Distillation promotes run-scoped facts into structured agent-scope knowledge. The distilled knowledge persists beyond session cleanup; review contradictory findings explicitly.

Run garbage collection on stale memories

bash

fathom memory gc --ttl-days 90 --dry-run

Dry-run mode shows what would be archived without actually deleting. Memory maintenance is optional and follows the configured TTL and confidence thresholds.

Use memory to map relationships

bash

fathom memory list

Lists all facts, entities, and relationships in the memory graph. Use grep or pipe to other tools for filtering.

Create a topic digest and inject into next session

bash

fathom memory distill --session latest

Use the semantic memory digest in the worker context to bootstrap a follow-up session with prior knowledge. Topic-specific retrieval is handled by the memory tools.

Autonomous Workers

Persistent coworkers & schedules

Use the authenticated control plane to create durable worker profiles, connect channels and schedule recurring operations. These routes are backed by the current server API.

Create a persistent coworker

bash

curl -X POST http://localhost:8080/api/v1/coworkers \
  -H "Content-Type: application/json" \
  -d '{"name":"market-watch","title":"Market watcher","role":"analyst","prompt":"Monitor the assigned market and summarize changes.","active":true}'

Coworkers persist identity, role and prompt in the server database. Link channels and schedules through the authenticated API.

Schedule a coworker task

bash

curl -X POST http://localhost:8080/api/v1/schedules \
  -H "Content-Type: application/json" \
  -d '{"coworker_id":"","cron_expression":"0 9 * * 1-5","timezone":"UTC","query":"Review new market signals","enabled":true}'

Schedules are optional and require a coworker, validated cron expression, timezone and query. The scheduler claims due rows atomically; an external/operator scheduler must launch the claimed work.

Automation

Automation & Watch Mode Recipes

Set up always-on monitoring and batch workflows. Watch mode re-runs sessions on a schedule, diffs results, and sends alerts only when something new appears.

Daily monitoring loop for new leads

bash

fathom run "Find new VP-level executives at Series B+ fintech companies in EMEA who joined in the past 24 hours." --repeat 86400

The session persists across restarts. Configure notifications and review each run's findings before acting on changes.

Test a configured notification channel

bash

curl -X POST http://localhost:8080/api/v1/notifications/test \
  -H "Content-Type: application/json" \
  -d '{"channel":"webhook"}'

The endpoint accepts only a symbolic channel name (webhook, email or telegram) and uses server-side [notifications] configuration. Destinations and credentials are never supplied by the caller.

Telegram alerts for new verified contacts

bash

fathom config set alerts.telegram.bot-token "123456:ABC..." && fathom config set alerts.telegram.chat-id "-1001234567890" && fathom run "..."

Set Telegram bot token and chat ID once, then any session can send alerts to the channel. Alerts include contact name, company, email, and a link to the full result in the dashboard.

Run multiple research tasks

bash

fathom run "Task 1: Research company A" -o ./results/task1
fathom run "Task 2: Research company B" -o ./results/task2

Run multiple research tasks sequentially or in parallel.

Schedule recurring research with cron

bash

# Standard cron scheduling
# Runs the batch file at 09:00 on weekdays
# Output folders are date-stamped. Combine with webhook notifications to get Slack/email alerts when the batch completes.

Standard cron scheduling. Runs the batch file at 09:00 on weekdays. Output folders are date-stamped. Combine with webhook notifications to get Slack/email alerts when the batch completes.

Integrations

API & Integration Recipes

Integrate Fathom into your existing workflows. Create sessions via REST, stream results via SSE, approve operations, and connect to external tools.

Create session via REST API and stream SSE

bash

curl -sS -X POST http://localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"query":"Find CTOs at fintech startups in London"}' \
  | jq -r '.id' \
  | xargs -I{} curl -N http://localhost:8080/api/v1/sessions/{}/events

First call creates the session and returns the session_id. Second call opens an SSE stream that yields real-time progress, sub-agent results, and the final synthesis. Each event is a JSON object.

Answer an agent's question programmatically

bash

curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/answer \
  -H "Content-Type: application/json" \
  -d '{"request_id":"ctrl_001","text":"Yes, proceed with verification."}'

When an agent hits an approval gate or needs input, it pauses and exposes the question via the SSE stream. POST an answer to resume. Useful for building custom UIs or automated decision flows.

Approve tool calls via the API

bash

curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/approve \
  -H "Content-Type: application/json" \
  -d '{"request_id":"ctrl_042","approved":true}'

Tool approval is an optional safety gate. When enabled, agents pause before executing side-effect tools (CRM push, email send, etc.). The API lets you build approval queues and approve or deny pending operations by request_id.

Export contacts to CSV via CLI

bash

fathom contacts export --format csv --output ./contacts-export/

Exports the full contact database to CSV. Use --output to choose the destination directory.

Connect MCP server to Claude Desktop

bash

# Add to claude_desktop_config.json:
# {
#   "mcpServers": {
#     "fathom": {
#       "command": "fathom",
#       "args": ["mcp-serve"]
#     }
#   }
# }
fathom mcp-serve

The MCP server exposes all research tools to Claude Desktop via stdio. Once configured, Claude can create sessions, search contacts, manage memory, and run research tasks directly.

Build a custom dashboard using health/metrics

bash

curl http://localhost:8080/health && echo "---" && curl http://localhost:8080/metrics

/health returns component status (database, agents, memory). /metrics returns Prometheus-compatible metrics: active sessions, contacts found, memory usage, sub-agent counts, and API latency histograms.

Power Users

Advanced Configuration Recipes

Fine-tune the agent system for your exact workflow. Switch profiles, route models by role, add approval gates, run parallel agents, and hook into the lifecycle.

Switch between hunter/analyst/validator profiles

bash

fathom run "..." --profile hunter
fathom run "..." --profile analyst
fathom run "..." --profile validator

Profiles are named presets that set model, tools, temperature, and approval policies. Hunter mode maximizes coverage. Analyst mode prioritizes depth and synthesis. Validator mode focuses on fact-checking and email verification.

Role-based model routing

bash

fathom config set agent.role_models.writer "openai/gpt-4o"
fathom config set agent.role_models.researcher "deepseek/deepseek-chat"
fathom config set agent.role_models.verifier "openai/gpt-4o-mini"

Route different agent roles to different models. Writers use GPT-4o for polished output. Researchers use DeepSeek for cost-effective long-context exploration. Verifiers use GPT-4o-mini for fast checks.

Set up approval gates for sensitive operations

bash

fathom config set agent.approval_tools '["crm_push","email_send","webhook_post"]'
fathom run "..."

Approval gates pause the agent before executing sensitive tools.

Configure multi-process mode for parallel agents

bash

fathom config set agent.max_agents 8
fathom run "Research 50 companies across 10 sectors..."

Multi-process mode spawns independent agent processes that communicate via the shared contact DB and memory graph.

Tune context window and compaction thresholds

bash

fathom config set context.context_window 128000
fathom config set context.compact_threshold 0.85

When context usage hits 85% of the max, the compaction engine kicks in.

Set up hooks for custom pre/post processing

bash

# .fathom/hooks.yaml
# hooks:
#   pre-session:
#     - command: ./scripts/enrich-from-db.sh
#       args: ["{{session_id}}"]
#   post-session:
#     - command: ./scripts/push-to-warehouse.sh
#       args: ["{{session_id}}", "{{output_dir}}"]

Hooks run shell commands at key lifecycle points. Pre-session hooks can inject data into the agent's context. Post-session hooks can push results to data warehouses, trigger notifications, or update external systems.

Ops

Troubleshooting Recipes

When things go wrong. These recipes cover session recovery, stall debugging, memory repair, rate limit handling, and context overflow recovery.

Resume a crashed session

bash

fathom resume  # picks up the most recent interrupted session

The resume command inspects the session log, identifies which sub-agents completed, and re-runs only the pending ones. Final synthesis is re-triggered automatically. No data is lost.

Debug agent stalling with stall detection

bash

RUST_LOG=debug fathom run "..."

Debug logging shows every tool call, context usage, and decision point. Check logs at ~/.fathom/logs/.

Fix memory database corruption

bash

fathom memory distill --session latest

Distill facts from a persisted session into the configured memory graph; enable memory in configuration first.

Handle rate limiting from search backends

bash

fathom config set search.backend "hybrid"

Rate limits are applied per-domain. The hybrid backend spreads queries across configured providers, and the agent shifts to alternative sources when one is consistently rate-limited.

Recover from context window overflow

bash

fathom config set context.compact_threshold 0.7

When a session exceeds the context window, compact-and-retry compresses the history and resumes. A lower threshold compacts earlier and leaves more headroom.

Fix stuck session that won't complete

bash

fathom sessions list
fathom resume

Inspect stored sessions, then resume the most recent interrupted session. Resume picks up from the last checkpoint and skips already-completed sub-agents.

Clear corrupted contacts database

bash

cp contacts.db contacts.db.bak

Always back up before repair.

Debug authentication failures

bash

fathom config show

Shows all configured API keys and tokens (values are masked).

Investigate high memory usage

bash

fathom memory stats
fathom memory gc --ttl-days 30

Memory stats reports store counts. GC archives stale entries according to the configured TTL; both commands require memory to be enabled.

Data & Reports

Export & Reporting Recipes

Turn research results into actionable formats. Export contacts to CRMs, generate PDF reports, pipe data to warehouses, and create visualizations from the memory graph.

Export contacts to HubSpot CSV format

bash

fathom contacts export --format csv --output ./hubspot-import/

Exports contacts to CSV format.

Generate a Markdown research report

bash

fathom run "Analyze the European EV charging market: size, growth, key vendors" -o ./report/

Compiles session findings into a structured Markdown report with executive summary, findings, sources, and confidence scores.

Export to JSON for programmatic processing

bash

fathom config set export.format json
fathom run "Your task" -o ./results/

JSON export includes all fields, nested objects for enrichment data, and source arrays.

Create a PDF report from session results

bash

fathom config set export.format pdf
fathom run "Your task" -o ./results/

PDF generation renders the same report structure; it requires pandoc on the host.

Export contacts as a spreadsheet

bash

fathom contacts export --format xlsx -o ./exports/

xlsx opens directly in Google Sheets and Excel; csv works everywhere.

Bulk export contacts for a data warehouse

bash

fathom config set export.format json
fathom contacts export --format json -o ./warehouse/

JSON export includes every stored field for ingestion into your warehouse.

Generate a competitive landscape PDF

bash

fathom config set export.format pdf
fathom run "Compare Datadog, New Relic and Dynatrace side by side" -o ./landscape/

The PDF report renders a side-by-side comparison of the researched competitors.

Export memory facts for graph tooling

bash

fathom memory list --scope all --status active -n 500 > ./memory-export.txt

Plain-text export of active facts; adapt the rows to your graph tooling of choice.

Playbooks

Multi-Step Workflow Recipes

Complete playbooks that chain multiple sessions into end-to-end workflows. Each recipe is a sequence of commands designed to be run together or scheduled as a pipeline.

Lead enrichment pipeline (3-step)

bash

# Step 1: Find raw leads
fathom run "Find marketing directors at Series A+ SaaS companies in DACH region" -o ./pipeline/raw

# Step 2: Enrich with LinkedIn and verify emails
fathom run "Enrich the contacts in ./pipeline/raw with LinkedIn profiles and verify all email addresses" -o ./pipeline/enriched

# Step 3: Score and prioritize
fathom run "Score the enriched contacts in ./pipeline/enriched by company size, funding stage, and role seniority. Output top 50 for outreach." -o ./pipeline/ready

This three-step pipeline separates discovery, enrichment, and scoring. Each step can be re-run independently. The intermediate outputs serve as checkpoints for debugging and quality review.

Weekly competitor intelligence digest

bash

# Monday morning: gather all signals
fathom run "Compile a weekly intelligence digest for competitors: Datadog, New Relic, Dynatrace. Include news, blog posts, job postings, social media activity, and any pricing changes." -o ./intel/weekly-$(date +%Y%m%d)

Run this as a weekly cron job. Each week's output is date-stamped and stored separately.

Event-driven follow-up research

bash

# When you get a new lead from a webhook:
fathom run "For the company {company_name} that just signed up, find their CTO, VP Engineering, and Head of Product. Research their tech stack, recent hires, and any public statements about {your_product_category}." -o ./follow-up/{company_slug}

Designed to be triggered by a CRM webhook or form submission. The agent performs targeted research on the inbound lead's company, giving your sales team context before the first call.

Conference preparation workflow

bash

# 2 weeks before: research attendees
fathom run "Parse the attendee/speaker list from KubeCon EU 2025. Find LinkedIn profiles, current roles, companies, and recent technical blog posts for each person." -o ./events/kccn-eu-2025/attendees

# 1 week before: prioritize
fathom run "From the attendees in ./events/kccn-eu-2025/attendees, identify the top 30 people to meet based on: company relevance to our product, role seniority, and mutual connections." -o ./events/kccn-eu-2025/priority

Two-phase workflow: broad research first, then focused prioritization. The priority list includes talking points derived from each person's recent activity, making conversations more productive.

Hiring signal detection pipeline

bash

# Daily: scrape new job postings
fathom run "Scrape job postings from Datadog, Snowflake, Databricks, Confluent, and Grafana Labs career pages posted in the last 24 hours. Classify by department, seniority, and technology." --repeat 86400 -o ./hiring/daily

# Weekly: trend analysis
fathom run "Analyze the job postings in ./hiring/daily from the past 7 days. Identify hiring surges by department, new technology adoptions, and geographic expansion patterns." -o ./hiring/weekly-trends

Daily scraping feeds a database of job postings. Weekly analysis detects trends that signal strategic shifts: a surge in ML hiring suggests an AI product, new geo offices suggest expansion.

Supply chain risk monitoring

bash

# Monthly: map the supply chain
fathom run "Map the full supply chain for {product}. Identify all tier-1 and tier-2 suppliers, their geographic locations, financial health, and any recent news about disruptions, sanctions, or regulatory actions." -o ./supply-chain/{product}/monthly-$(date +%Y%m)

# Compare with prior month
fathom run "Compare the supply chain map in ./supply-chain/{product}/monthly-$(date +%Y%m) with the previous month. Highlight any new risks, removed suppliers, or geographic shifts."

Monthly cadence balances freshness with cost. The comparison step uses the diff engine to surface only changes, making the risk report actionable rather than repetitive.

Content gap analysis workflow

bash

fathom run "Analyze the top 10 blog posts, whitepapers, and webinars published by our competitors (list them) in the past quarter. For each piece of content, extract the topic, target persona, format, and estimated engagement. Identify content gaps where we have no competing content." -o ./content/gap-analysis

The agent visits each competitor's content hub, classifies content by topic and persona, and cross-references against your content catalog (if provided). The gap report highlights opportunities ranked by estimated traffic potential.

Investor research for fundraising prep

bash

fathom run "Research the top 50 VCs that invest in B2B SaaS Series A in Europe. For each fund, find: investment thesis, portfolio companies in our space, key partners, check size, and recent deals. Identify warm introduction paths through our network." -o ./fundraising/vc-list

Investor research combines Crunchbase data with partner LinkedIn profiles and portfolio analysis. Warm path detection cross-references your team's LinkedIn connections against VC partner networks.

Setup

Spin up the tools

Three ways to interact with Fathom: terminal UI for hands-on work, HTTP server for dashboards and APIs, and MCP for AI-native tool integration.

Terminal UI

fathom tui — watch the fleet live, approve side effects, inspect jobs and memory.

HTTP + dashboard

fathom mcp-serve — expose 63 always-registered tools, plus up to 5 browser tools when CDP is reachable and up to 6 computer tools when COMPUTER_URL is configured to any MCP client over stdio.

MCP for Claude/ZCode

fathom mcp-serve — expose 63 always-registered tools, plus up to 5 browser tools when CDP is reachable and up to 6 computer tools when COMPUTER_URL is configured to any MCP client over stdio.

Full Recipe Index

All recipes at a glance. Click a section link to jump to the full recipe with command and explanation.

Common Flags Reference

Flags that work across most recipes. Combine them to customize behavior without changing config files.

Flag	Description	Default
`-o <dir>`	Output directory for results, contacts DB, and session logs	`./research-output/`
`–profile <name>`	Load a named profile (hunter, analyst, validator, or custom)	Default profile
`–repeat <seconds>`	Re-run interval for session	`3600`
`–depth <1-5>`	Research depth (1-5)	`3`
`–fast`	Fast mode with reduced depth	Off
`RUST_LOG=debug`	Enable debug logging via environment variable	`info`
`–approval-gate <tool>`	Require approval before executing a specific tool	None
`<session-id>`	Optional positional session identifier for resume	Latest interrupted
`–dry-run`	Show what would happen without executing side effects	Off
`–confirm`	Skip confirmation prompts for destructive operations	Off

Quick Config Reference

Common configuration commands used across recipes. Run fathom config show to see all options.

Model Configuration

bash

fathom config set agent.role_models.writer "openai/gpt-4o"
fathom config set agent.role_models.researcher "deepseek/deepseek-chat"
fathom config set agent.role_models.verifier "openai/gpt-4o-mini"
fathom config set agent.role_models.default "openai/gpt-4o"

Alert Configuration

bash

fathom config set alerts.telegram.bot-token "123456:ABC..."
fathom config set alerts.telegram.chat-id "-1001234567890"
fathom config set alerts.email.to "[email protected]"
fathom config set alerts.webhook.url "https://hooks.slack.com/..."

Search Configuration

bash

fathom config show

Context & Memory

bash

fathom config set context.context_window 128000
fathom config set context.compact_threshold 0.85

Getting Help

Stuck? These commands point you in the right direction.

List all available commands

bash

fathom --help

Shows all top-level commands with descriptions. Use –help on any subcommand for detailed flags and examples.

Show current configuration

bash

fathom config show

Dumps all config values with their sources (default, file, env var, or CLI flag). Useful for debugging unexpected behavior.

Check system health

bash

fathom memory stats

Shows memory graph statistics and health.

View session logs

bash

RUST_LOG=debug fathom run "..."

Enable debug logging to see every tool call, decision, and error with timestamps.

List active sessions

bash

fathom memory list

Shows all facts, entities, and relationships in the memory graph.

Show version and build info

bash

fathom --version

Displays the binary version and build info. Useful for bug reports.

Reset to factory defaults

bash

rm ~/.fathom/config.toml

Remove the config file to reset to defaults.

Best Practices

Tips & Best Practices

Hard-won advice from production deployments. These tips help you get better results, avoid common pitfalls, and keep costs under control.

Write specific, structured prompts

text

# Vague (low quality results):
"Find leads in fintech"

# Specific (high quality results):
"Find CTOs and VP Engineering at B2B fintech
startups in London with 50-200 employees that
raised Series A or B in the past 18 months.
Verify each email via SMTP probe. Include
company size, last funding round, and tech
stack from job postings."

Specificity drives quality. Include geography, company size, role, verification method, and enrichment fields. The agent performs better with clear success criteria.

Use -o for reproducibility

bash

# Always specify output directory
fathom run "..." -o ./leads/q1-2025

# Re-run produces deterministic structure
ls ./leads/q1-2025/
# contacts.db  session.json  sources/  synthesis.md

Explicit output directories make results versionable, comparable, and easy to reference in follow-up sessions. The deterministic structure means scripts can reliably process outputs.

Start shallow, then go deep

bash

# First pass: broad, shallow
fathom run "..." --depth 2 -o ./broad

# Second pass: deep dive on top results
fathom run "Analyze top 20 from ./broad"

Shallow depth is faster and cheaper. Use it to identify the most promising targets, then invest deep research only on the best candidates. This two-pass approach cuts costs by 60-80%.

Chain sessions with memory

bash

# Session 1: research
fathom run "..." -o ./research

# Session 2: uses memory from session 1
fathom memory distill --session latest
fathom run "Using prior research, ..." -o ./follow-up

Distilling session facts into memory makes them available to future sessions. The memory graph connects entities across sessions, so the second session benefits from all prior context.

Infrastructure

Docker & Deployment Recipes

Run Fathom in production. Docker, systemd, reverse proxies, health checks, backups, and scaling — everything you need for a reliable deployment.

Run the HTTP server with Docker

bash

docker run -d --name fathom \
  -v ./data:/data \
  -v ~/.fathom:/home/researcher/.fathom \
  -e FATHOM_API_KEYS=$FATHOM_API_KEYS \
  -p 8080:8080 \
  fathom:latest serve --port 8080

Mount persistent state and expose the authenticated HTTP control plane. Configure the LLM provider in the mounted config file.

Deploy to a VPS with systemd

bash

# Create /etc/systemd/system/fathom.service from your deployment settings
# ExecStart=/usr/local/bin/fathom serve --port 8080
# Restart=on-failure
# Set FATHOM_API_KEYS in the unit environment
sudo systemctl daemon-reload
sudo systemctl enable --now fathom

The repository does not ship a unit file. Create one for your host, then use systemd to start the HTTP server on boot and restart it after failures.

Run behind Nginx reverse proxy

bash

# /etc/nginx/sites-available/fathom
# server {
#     listen 443 ssl http2;
#     server_name research.example.com;
#     ssl_certificate /etc/letsencrypt/live/research.example.com/fullchain.pem;
#     ssl_certificate_key /etc/letsencrypt/live/research.example.com/privkey.pem;
#     location / {
#         proxy_pass http://127.0.0.1:8080;
#         proxy_set_header Host $host;
#         proxy_set_header X-Real-IP $remote_addr;
#         proxy_buffering off;
#         proxy_cache off;
#     }
# }

Nginx handles TLS termination and proxies to the local Fathom server. Proxy buffering must be disabled for SSE streams to work. Use certbot for free Let's Encrypt certificates.

Set up health check monitoring

bash

# Add to your monitoring system (UptimeRobot, Healthchecks.io, etc.)
curl -f http://localhost:8080/health || exit 1

# Prometheus scrape config
# scrape_configs:
#   - job_name: fathom
#     static_configs:
#       - targets: ['localhost:8080']
#     metrics_path: /metrics

The /health endpoint returns HTTP 200 when all components are healthy, 503 when degraded. The /metrics endpoint exposes Prometheus-compatible counters and histograms. Set up alerts on session_failure_total and agent_stall_total.

Backup and restore data

bash

cp -r ~/.fathom ~/.fathom.bak
# restore:
cp -r ~/.fathom.bak ~/.fathom

Always backup your data directory before upgrades or destructive commands like memory nuke.

Run in a tmux session for persistence

bash

tmux new-session -d -s research "fathom mcp-serve"
tmux attach -t research

# Or run a long research task
tmux new-session -d -s research "fathom run 'Deep analysis of...' -o ./analysis"
tmux ls

tmux keeps the session alive if your SSH connection drops. Reattach with tmux attach -t research. Useful for long-running watch mode sessions or batch jobs that take hours.

Scale with multiple instances on different ports

bash

fathom mcp-serve &

Use Nginx upstream for load balancing.

Configure for CI/CD pipeline

bash

# .github/workflows/research.yml
# name: Weekly Research
# on:
#   schedule:
#     - cron: '0 9 * * 1'
# jobs:
#   research:
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#       - name: Build Fathom
#         run: cargo build --release
#       - name: Run research
#         env:
#           FATHOM_API_KEYS: ${{ secrets.FATHOM_API_KEYS }}
#           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
#         run: fathom run "weekly tasks" -o ./results/
#       - name: Upload results
#         uses: actions/upload-artifact@v4
#         with:
#           name: research-results
#           path: ./results/

GitHub Actions runs the batch on a weekly schedule. Secrets store API keys securely. Results are uploaded as artifacts for download. Add a notification step (Slack webhook) to alert the team when the batch completes.

Docker deployment

The repository does not ship a Docker Compose file. Build the image from the checkout and run it directly, or provide an operator-owned Compose definition for your environment.

Configuration

Environment Variables

All environment variables that Fathom recognizes. Set these in your shell, .env file, or Docker container. CLI flags and config values take precedence over environment variables.

Variable	Description	Example
`FATHOM_API_KEYS`	Primary API key for the Fathom service	`key-abc123…`
`OPENAI_API_KEY`	OpenAI API key for GPT-4o and GPT-4o-mini models	`sk-proj-…`
`DEEPSEEK_API_KEY`	DeepSeek API key for the default OpenAI-compatible endpoint	`sk-…`
`GITHUB_TOKEN`	GitHub personal access token for higher API rate limits	`ghp_…`
`GOOGLE_CSE_KEY`	Google Custom Search Engine API key	`AIza…`
`GOOGLE_CSE_ID`	Google Custom Search Engine ID	`a1b2c3d4e5…`
`PR_OUTPUT_DIR`	Override the configured output directory	`/data/fathom`
`PR_CONFIG`	Override the config.toml path	`/etc/fathom/config.toml`
`PR_MEMORY_DB`	Override the memory SQLite database path	`/data/fathom/memory.db`
`PARALLEL_CDP_ENDPOINT`	Chrome DevTools Protocol endpoint for browser tools	`ws://127.0.0.1:9222`
`FATHOM_RATE_LIMIT`	HTTP server rate limit per client (requests per minute)	`120`
`HTTP_PROXY`	HTTP proxy for outbound requests	`http://proxy:8080`
`HTTPS_PROXY`	HTTPS proxy for outbound requests	`http://proxy:8080`
`NO_PROXY`	Comma-separated list of hosts to bypass proxy	`localhost,127.0.0.1`
`TELEGRAM_BOT_TOKEN`	Telegram bot token (alternative to config)	`123456:ABC…`
`TELEGRAM_CHAT_ID`	Telegram chat ID for alerts (alternative to config)	`-1001234567890`
`WEBHOOK_URL`	Default webhook URL for session events	`https://hooks.slack.com/…`
`CRM_PROVIDER`	CRM provider for contacts push (amocrm, bitrix24, hubspot)	`hubspot`
`CRM_API_KEY`	API key for the configured CRM provider	`pat-na1-…`

Example .env File

Copy this template and fill in your keys. The agent loads .env from the current directory automatically.

.env

# Required
FATHOM_API_KEYS=key-your_api_key_here

# Model providers (at least one required)
OPENAI_API_KEY=sk-proj-your_openai_key
DEEPSEEK_API_KEY=sk-your_deepseek_key

# Optional: higher rate limits for source scraping
GITHUB_TOKEN=ghp_your_github_token
GOOGLE_CSE_KEY=AIza_your_google_key
GOOGLE_CSE_ID=your_search_engine_id

# Optional: alerting
TELEGRAM_BOT_TOKEN=123456:ABC-your_bot_token
TELEGRAM_CHAT_ID=-1001234567890
WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx

# Optional: CRM integration
CRM_PROVIDER=hubspot
CRM_API_KEY=pat-na1-your_hubspot_key

# Optional: local data paths
PR_OUTPUT_DIR=./research-output
PR_MEMORY_DB=~/.fathom/memory.db

# Optional: logging
RUST_LOG=info