franco README

项目的 README,来自 github.com/GortexAI/franco。合并为一个 markdown 文件:README.md。

Franco

An outbound sales agent that runs on your own machine, on the Claude Code or Codex subscription you already pay for.

Franco works through a list of accounts. For each one it finds or imports a reason to write, sends a short email sequence from your own mailbox, reads the replies, and handles them. Every fact it uses is recorded with its source. You review every email before it sends, unless you turn on autopilot.

It works in three ways (outreach.mode):

Bring your own lists as CSV files: researched accounts, plain company/contact lists, and do-not-contact lists. Use the terminal or the dashboard. Every new campaign starts in preview: a few accounts per owner are staged for review, and nothing sends until someone signs the campaign off.

There is no model API bill. Model calls go through claude (Claude Pro or Max) or, if you opt in, an isolated codex runtime (a ChatGPT plan). Everything that can be done in plain code is done in plain code.

Franco's dashboard: the Today queue, confirming a signal, the cohort builder, a costed discovery estimate, and the outbox decisions desk

Recorded from made-up demo data by scripts/record_demo.py. Re-run it after changing the dashboard.


Contents


Quick start

You need:

Install from PyPI (recommended):

pipx install franco                    # or, in a virtualenv: pip install franco
franco init ~/franco && cd ~/franco    # your home folder: config, .env, prompts, skills, data
franco install                         # Chromium, for LinkedIn and JavaScript-heavy sites

$EDITOR .env                           # mail provider + verifier keys, documented inline
franco gmail auth                      # one-time browser login when provider: gmail
franco gmail test

franco dashboard                       # http://localhost:5555
franco run                             # the heartbeat loop

Franco works in one home folder. It finds it in this order:

  1. $FRANCO_HOME, when set;
  2. the source checkout, when you run from a clone;
  3. the current folder, when it has a franco.yaml;
  4. ~/.franco otherwise.

franco init creates a home folder. The prompts and skills it copies there are yours to edit; delete one to go back to the version that ships with Franco.

Or run from a clone (to change Franco itself):

git clone https://github.com/GortexAI/franco.git && cd franco
python3.13 -m venv .venv && source .venv/bin/activate && pip install -e .
cp .env.example .env && $EDITOR .env

The clone is its own home folder: config, prompts/, skills/ and data/ live next to the code.

Or run the published container image (Linux, Intel or ARM). It already includes Chromium and the Claude CLI:

docker pull ghcr.io/gortexai/franco:latest      # or :edge for the latest main, or a version tag
docker compose up -d                            # uses that image, with ./data, .env and your config mounted

Every image is built by GitHub Actions with a signed provenance attestation. You can check one with gh attestation verify oci://ghcr.io/gortexai/franco:latest --owner GortexAI.

Or open the repo in Claude Code and say "set up Franco for me". CLAUDE.md turns Claude into the setup guide: it checks what's missing and asks for one thing at a time.

Put your real settings in franco.local.yaml. It is gitignored, and when it exists it is used instead of franco.yaml. The tracked franco.yaml stays a template.


How Franco works

Franco runs a heartbeat. By default, every 15 minutes it wakes up, checks quiet hours and its usage budget, decides what most needs doing, does it, logs it, and goes back to sleep.

handle replies  >  send due email  >  write/stage sequences  >  prospect  >  idle (analyze)

The decision is made from counts in the database, not by asking a model. Profiling and draining the outbox happen on every cycle because they cost nothing.

Agent What it does
Scout Scores and personalizes prospects. Searching, website reading and email resolution are plain Python.
Writer Drafts sequences with the model (generated), renders approved copy with no model (approved copy), or places accounts in funnels and writes email 1 from the funnel's brief (raad).
Sender Stages each email in the outbox with a send time, then sends due, approved items with human-like pacing, the daily cap and the pre-send gate.
Handler Reads replies, removes quoted text, classifies intent, stops sequences, records opt-outs, detects bounces, and queues responses through the outbox.
Analyst On idle cycles, writes pipeline stats to data/analytics.json.

Bring your own lists (CSV)

Every list Franco takes can come in as a CSV file. You don't have to use discovery or type entries one at a time. There are three kinds, each with a template:

Kind One row is Required columns Used by
accounts a researched account: one buyer, the campaign they get, and the sourced fact behind it company, domain, campaign, first_name, last_name, title, email, observation, source_url, source_date approved copy, raad
contacts a company, optionally with a person at it company, domain generated, raad
suppressions an email address or a whole domain never to contact value (an address or a domain) everything

Optional columns:

Common spreadsheet header names are accepted, for example website for domain, role for title and funnel for campaign.

From the terminal:

franco import --template --kind contacts > contacts.csv   # start from the template
franco import contacts.csv --kind contacts --dry-run      # check every row, write nothing
franco import contacts.csv --kind contacts --verify       # import; verify unverified emails
franco import accounts.csv                                # --kind defaults to accounts in approved-copy mode
franco suppress import do_not_contact.csv                 # same as --kind suppressions
franco suppress export > suppressions.csv

From the dashboard: the Contacts tab has an Import CSV panel. Pick the kind, download its template, then choose a file. The file is checked straight away, and nothing is written until you press Import. The browser reads the file and sends its text only to your local dashboard.

Rules that apply to every import:


Approved-copy outreach

Use this mode when the copy has been signed off and must go out exactly as written.

1. Define the sequences

In franco.local.yaml:

outreach:
  mode: templates
  timezone: America/Los_Angeles
  send_hour: 9
  observation_max_age_days: 90
  campaigns:
    M1:
      name: Vertical marketplaces
      steps:
        - day: 1
          subject: "{{company}} sponsored listings"
          body: |
            Hi {{first_name}},

            I noticed {{verified_observation}}.
            ...
            Hemin
        - { day: 5,  subject: "...", body: "..." }
        - { day: 9,  subject: "...", body: "..." }
        - { day: 14, subject: "...", body: "..." }

compliance:
  require_footer: true
  postal_address: "<your postal address>"
  blocked_claims: ["real-time auction", "guaranteed uplift"]
  send_opt_out_ack: true

The only merge fields are {{first_name}}, {{last_name}}, {{company}}, {{title}}, {{verified_observation}} and {{sender_name}}. If any field can't be filled, the account is skipped. Franco never sends a gap or a guess.

day counts business days. Day 1 is the first send, and each later step is scheduled from the date the previous step actually went out.

2. Import researched accounts

Each row is one account, one buyer, the campaign they get, and the fact that justifies writing to them, with the page it came from and the date it was checked.

franco import --template --kind accounts > accounts.csv   # header + example row
franco import accounts.csv --dry-run                      # validate every row, write nothing
franco import accounts.csv --verify --owner Hemin

The columns are in Bring your own lists, and the dashboard's Import CSV panel does the same thing. Besides the general import rules, an account row is also rejected if it:

The observation is stored as the account's TRIGGER_OBSERVATION, together with its source and date.

3. What happens next

On the next cycle, the writer stages the full sequence for one contact per account. It does this only when:

The first accounts of every campaign are a preview. Nothing sends until the campaign is signed off; see Review, preview, autopilot and the kill switch. After sign-off, every step waits in the outbox for review, unless autopilot is on.

franco outbox lists each draft with the reason for writing: the campaign, the observation, its source and the date it was checked. franco outbox --edit <id> opens a draft in $EDITOR.


Raad mode

Named after Raad Mobrem, CEO of Intro, whose way of finding customers and personalizing outbound this mode follows:

  1. At most three customer benefits. Every message connects to one of them and never works against another.
  2. Narrow, observable funnels instead of one broad message. Zapier writing to a shop that runs Shopify and QuickBooks about exactly that connection lands far better than "we connect your apps". Split the market by what you can actually see: marketplace vs feed first, then edge cases like "already runs AdSense" vs "no ads at all".
  3. A tiny story the whole funnel recognises. "Every marketplace reaches a size where sellers will pay for better placement…", then how you handle it, kept to what is true today.
  4. The pitch shifts with the buyer. A CEO and a head of product care about different consequences of the same thing.
  5. One page per funnel. The email lands on a page that restates the same narrow case.

Configure it

outreach:
  mode: raad
  benefits:                     # at most three; every funnel names one
    - { key: revenue, text: "A measurable revenue opportunity from intent already on the platform" }
    - { key: control, text: "Discovery and commercial rules stay under your product control" }
  first_email_max_words: 110
  funnels:                      # tried in order: put the narrowest first
    MKT_3P_ADS:
      name: "Marketplace already selling third-party ads"
      benefit: control
      match:
        require: ["segment=marketplace", "TECH_STACK=AdSense|Ad Manager|Prebid"]
      story: "A marketplace that monetises with third-party ad slots hands its best positions to a network that knows nothing about its sellers."
      solution: "We help a marketplace offer sponsored listings from its own sellers on one surface, under rules the product team sets."
      landing_url: "https://example.com/marketplaces"
      personas:                 # regex on the contact's title → the angle to lean on
        - { match: "\\b(ceo|founder)\\b", angle: "a revenue line from seller demand you already have" }
        - { match: "product|search",      angle: "control over eligibility, placement and guardrails" }
      steps:                    # approved follow-ups, by business day
        - { day: 5, subject: "...", body: "Hi {{first_name}}, ..." }
        - { day: 9, subject: "...", body: "..." }
    MKT:
      name: "Marketplace, no sponsored placement yet"
      benefit: revenue
      match: { require: ["segment=marketplace"] }
      story: "Every marketplace reaches a size where some sellers will pay for better placement..."
      solution: "..."

Match conditions can use:

exclude takes the same conditions. An account imported with a campaign (funnel) column keeps that funnel; the researcher's call beats inference. The profiler detects publisher ad tags (Google AdSense, Ad Manager, Prebid, Amazon Publisher Services), so "already sells ad space" is something Franco can observe.

What it does each cycle

  1. Find. It places each new, verified contact's company in the first funnel whose conditions hold. Companies that match nothing are left alone.
  2. Check there's something to say. It writes only when it can cite something specific and sourced: a researched TRIGGER_OBSERVATION (within observation_max_age_days) or the observed signal that put the account in the funnel.
  3. Write email 1. The model gets the funnel's story, the account's facts with their sources, the funnel's solution, exactly one benefit, the role angle for the buyer's title, the word limit and the blocked-claims list. It may not claim anything that isn't in that text. A draft that contains a blocked claim is thrown away.
  4. Queue follow-ups. It adds the funnel's approved steps, rendered with merge fields and scheduled in business days.
  5. Apply the usual rules. Preview and sign-off (per funnel), the footer, the gate, suppression, the account stop and autopilot all apply as in the other modes.

See how your companies split across funnels, and why any one landed where it did:

franco funnels                          # benefits, each funnel's conditions, companies and reachable contacts
franco funnels --company market.example # which funnel, which conditions held, which facts

The dashboard's Campaigns tab shows the same table.

Plain contact lists work well with this mode. Import companies with a segment (and, when you have them, an observation and its source). Franco profiles their sites, places them, and writes from what it finds.


Generated outreach

This is the default mode, outreach.mode: generated.

1. Learn the product. franco train https://your-site.com writes franco.yaml, skills/product_knowledge.md and skills/competitive_intel.md. The two skills files are gitignored.

2. Confirm signals. Franco proposes a catalog of 24 signals it knows how to collect, such as ad pixels, tech stack, open roles, incumbent agency and search rank. It collects nothing until you confirm signals:

franco signals                     # the catalog, with what each one costs
franco signals --confirm free      # everything that costs nothing
franco signals --confirm SERP_RANK # a paid one, explicitly

The cohort builder on the dashboard's Signals tab turns confirmed signals into a target list. You choose what a prospect must have and what disqualifies it, and it counts the matches as you go.

3. Discover, or bring a list. Already have the companies? Import them as a CSV (franco import companies.csv --kind contacts) and skip discovery. Otherwise, discovery is the only stage that spends money, so it always estimates first:

franco discover --providers        # the menu, with real prices
franco discover --estimate
franco discover --provider dataforseo_listings --max-spend 2.00
Source Cost Free tier
OpenStreetMap (default) free unlimited. Thin coverage; a trial source.
DataForSEO Business Listings $0.372 / 1k businesses $1 credit
DataForSEO SERP $0.0018 / search at depth 30 $1 credit + sandbox
Serper ~$0.30–1.00 / 1k 2,500 free

4. Profile, enrich, verify. Franco reads each homepage, robots.txt, sitemap.xml, and the team and careers pages, with no model calls. It learns each company's email pattern and verifies one candidate through Reoon, ZeroBounce or Hunter. Every address is tagged verified, risky (catch-all), guess or invalid, and Franco only sends to deliverable addresses. Without a verifier key, addresses stay guess and are never sent to.

5. Write. The writer drafts sequences using the skills in skills/, which are plain Markdown you can edit. The next heartbeat uses your changes.

franco export writes a sequencer-ready CSV, so Franco is useful as a list builder even if it never sends.


Review, preview, autopilot and the kill switch

By default every outgoing email waits in the outbox for your approval. That includes replies.

franco outbox                   # review in the terminal (with the reason for each draft)
franco outbox --approve <id>    # or --approve-all, --reject <id>, --edit <id>

On the dashboard, the Outbox is a decisions desk. One email fills the pane, with a strip above it showing why the email exists:

You work the queue with A (approve), R (reject), E (edit the draft in place) and J/K (move).

Preview and sign-off. Every approved-copy campaign and raad funnel starts in preview, set by outreach.preview_accounts (default 10, 0 to turn it off):

Signing off releases the preview for normal approval and lets the rest of the campaign's accounts stage on the next cycle.

franco preview                        # every campaign's state, and each preview account:
                                      # buyer, role, campaign, observation + source, exact first email
franco preview M1 --csv preview.csv   # the same as a spreadsheet, to send to whoever signs off
franco preview signoff M1 --by "Hemin"
franco preview reopen M1              # back to preview: nothing more sends

On the dashboard, each campaign in preview gets a card in the Outbox with a Download preview CSV button and a Sign off button.

Autopilot turns review off without editing config or restarting:

franco autopilot on              # new emails and replies send on schedule, unreviewed;
                                 # also approves what's already waiting (--keep-pending to skip)
franco autopilot off             # every new draft waits for you again
franco autopilot default         # follow channels.email.require_approval in the config
franco autopilot                 # current state and where it comes from

The same switch is on the dashboard's Outbox tab. Autopilot only removes the human review step. Everything else still applies:

Turning autopilot off doesn't affect emails that are already approved. To stop them, use the kill switch.

Kill switch: franco sending pause (or the Outbox button) stops all outbound immediately. franco sending resume restarts it and resets the bounce counter.

The pre-send gate is plain code with no model. It rejects an email that has:


Replies

The handler polls the mailbox every cycle.

The suppression list is shared by every campaign and mode. A domain entry blocks everyone at that domain.

franco suppress list
franco suppress add [email protected] acme.com --reason "asked to stop"
franco suppress import do_not_contact.csv     # CSV with value[,reason], or one address per line
franco suppress export > suppressions.csv     # CSV: value, kind, reason, source, created_at

The dashboard

franco dashboard serves a local web UI at localhost:5555. It's plain HTML, CSS and JavaScript in franco/web/, with no build step: edit a file and reload.


Configuration

.env: credentials. Each variable is documented inline in .env.example. You need a mail provider (Gmail OAuth, SMTP+IMAP, or legacy Instantly). A verifier key is strongly recommended.

franco.yaml / franco.local.yaml:

persona:     { name, company, role, email, tone }
product:     { name, description, pricing, key_benefits, objection_responses, offer }
icp:         { industries, titles, company_size, geography, hiring_signals, geo_coordinates }
channels:
  email:     { provider: gmail | smtp | instantly, max_daily_sends, require_approval,
               send_to_risky, max_bounce_rate }
  linkedin:  { enabled }
outreach:    { mode: generated | templates | raad, campaigns, benefits, funnels,
               timezone, send_hour, observation_max_age_days, preview_accounts,
               first_email_max_words, reply_templates }
compliance:  { require_footer, postal_address, footer, unsubscribe_url,
               blocked_claims, send_opt_out_ack, opt_out_ack }
usage:       { max_daily_claude_percent, heartbeat_interval_minutes, quiet_hours }
brain:       { provider: claude | codex, model, reasoning_effort }

usage.max_daily_claude_percent caps whichever subscription brain.provider uses. Franco reads the live quota and leaves room for your own work.


Commands

franco run                      # heartbeat loop
franco dashboard                # web UI at localhost:5555
franco setup                    # interactive setup wizard
franco train <url>              # learn a product from its website
franco status [--check]         # pipeline summary / provider health check
franco usage                    # quota + per-agent tokens

franco import FILE              # a CSV list: --kind accounts|contacts|suppressions (--dry-run, --verify, --template)
franco signals                  # review/confirm signals
franco discover                 # find businesses (--providers, --estimate, --provider, --max-spend)
franco profile                  # read discovered sites (free)
franco export [--all]           # prospects → CSV

franco funnels [--company D]    # raad mode: how companies split across funnels
franco outbox                   # review queue (--approve, --approve-all, --reject, --edit)
franco preview [KEY]            # a campaign's preview (--csv FILE); preview signoff|reopen KEY
franco autopilot on|off|default # send without review
franco sending pause|resume     # kill switch
franco suppress list|add|remove|import|export
franco gmail auth|test          # Gmail provider

Using a ChatGPT plan (Codex)

Claude is the default. To use a ChatGPT plan instead:

npm install -g @openai/[email protected]   # the only version Franco accepts
codex login                            # "Sign in with ChatGPT"; API-key logins are refused
brain:
  provider: codex
  model: gpt-5.5        # the verified text-only model; code-mode models are refused

How it works:


Compliance and deliverability

Franco automates outreach, but you are the sender.

Deliverability:

  1. Authenticate the sending domain with SPF, DKIM and DMARC, and check "Show original" on a test email.
  2. Warm the mailbox up.
  3. Start at 10–20 a day and ramp slowly. The max_daily_sends default is a ceiling, not a target.
  4. Keep bounces under about 3%.

None of this is legal advice.


Your data folder

Everything Franco knows and does lives in data/ inside your home folder (next to the code in a clone, wherever you ran franco init for a pip install), on your machine. It is created on first run. In a clone and in a franco init folder it is gitignored. Never commit it, never put it in a shared drive, and never attach it to an issue.

File What it holds Sensitive?
franco.db The SQLite database: every company, person, email address, observation, email sent, reply, suppression, setting and decision Yes: personal data about the people you contact
gmail_token.json The Gmail OAuth refresh token from franco gmail auth Yes: treat it like a password; it can send as you
franco.log The heartbeat log when Franco is started from the dashboard Somewhat: email addresses appear in it
franco.pid The process id of a dashboard-started franco run No
analytics.json The analyst's latest pipeline report Somewhat

Your credentials are in .env and your sending config is in franco.local.yaml. Both are next to data/, and both are gitignored for the same reason.

Using it

How it's organised

Each fact Franco learns is a row in observations, not a column. A row carries the signal code, the value, a confidence, an evidence URL and a timestamp. As a result:

A database trigger rejects any signal code that isn't in the governed signal_codes table. The schema migrates itself forward on startup.


Troubleshooting


Development

pip install -e ".[dev]"
pytest -q                          # full suite
python scripts/record_demo.py      # re-record docs/dashboard.gif (pip install -e ".[demo]")

Dependencies live in three files that must agree (a test checks):

File What it is
pyproject.toml The version ranges pip install -e . accepts
requirements.in The same direct dependencies and ranges
requirements.txt Generated. Every package, including the ones those depend on, pinned to an exact version with hashes. Docker installs exactly this.

To change a dependency, edit pyproject.toml and requirements.in, then regenerate the lock:

uvx --python 3.11 --from pip-tools pip-compile --generate-hashes \
    --allow-unsafe --strip-extras --output-file=requirements.txt requirements.in

The exact pins are what let GitHub's dependency graph see every installed package. Dependabot alerts and Dependabot security updates rely on them, and Renovate (renovate.json) recompiles the lock when it updates a dependency. Without a lock, Dependabot can't tell what's installed and won't open security fixes.

franco/
├── main.py            # heartbeat loop
├── brain.py           # Claude/Codex provider, skills injection, usage
├── codex.py           # isolated Codex runtime
├── state.py           # SQLite schema + migrations, observations, outbox, suppression, settings
├── outreach.py        # rendering, footer, business days, quoted-text stripping
├── importer.py        # CSV lists: accounts, contacts, suppressions
├── funnels.py         # raad mode: funnel placement and the funnel report
├── gate.py            # deterministic pre-send checks
├── signals.py         # the signal catalog
├── dashboard.py       # FastAPI JSON API
├── agents/            # scout, writer, sender, handler, analyst
├── collectors/        # discover (paid adapters), profile (free HTTP)
├── integrations/      # gmail, smtp, instantly, email finder, quota
└── web/               # dashboard HTML/CSS/JS
skills/                # sales knowledge, editable Markdown
prompts/               # agent system prompts
scripts/record_demo.py # demo GIF recorder
tests/

See CHANGELOG.md for release history.


License

MIT. See LICENSE. Copyright (c) 2026 Gortex. Franco is derived from an MIT-licensed project, and that project's copyright notice is kept in LICENSE as the license requires.


Contact

Franco is built and maintained by Gortex.

Gortex · 440 N Wolfe Rd, Suite E133, Sunnyvale, CA 94085 · [email protected]

Bugs and feature requests: GitHub issues. Want to help? Start with CONTRIBUTING.md; everyone taking part follows the Code of Conduct.

Found a security problem? Please report it privately, as described in SECURITY.md, not in a public issue.

If you run Franco yourself, put your own postal address in compliance.postal_address. The footer on your emails must name you, not Gortex.

franco (GortexAI/franco)

正在搜索数据库…

693 ·GitHub
这是什么?Franco 是一个自主运行的外呼销售代理,它会调研目标客户,用你自己的邮箱起草并发送个性化的冷邮件序列,并处理回复。它运行在你已经付费的 Claude Code 或 Codex 订阅上,不需要单独的模型 API。
这是命令行工具,还是也有仪表盘?两者都有:你在终端里操作 Franco,同时还有一个本地仪表盘,用于导入 CSV、查看发件箱和跟踪营销活动;没有外部 SaaS 后端。
我该怎么让它跑起来?可以从 PyPI 安装,克隆代码仓库后从源码运行,或者运行已发布的 Docker 镜像(支持 Linux,Intel 或 ARM 架构,已内置 Chromium 和 Claude CLI),然后运行 'franco init' 来创建它的主目录。
我需要 Anthropic 或 OpenAI 的 API 密钥吗?不需要单独的 API 密钥。你需要 Python 3.11+、已登录 Pro 或 Max 套餐的 Claude Code(如果你使用 ChatGPT 套餐,则需要独立的 Codex 运行环境),以及一个用于发信的邮箱,推荐使用 Google Workspace。
每封邮件发出前都得我批准吗?默认是的:每个营销活动都从预览开始,每封邮件都会在发件箱中等待人工确认,除非你明确开启自动驾驶模式。另外,只要邮寄地址字段为空,冷邮件就会被暂缓发送。
我导入的名单数据会去哪里?所有操作都在你自己的电脑上运行。当你通过仪表盘导入 CSV 时,浏览器会读取文件,并且只把内容发送到你本地的 Franco 实例,绝不会发送到第三方服务器。
生成模式、已批准文案模式和 raad 模式有什么区别?生成模式是让模型在读完公司网站后起草一套个性化的邮件序列;已批准文案模式是原样发送你预先批准的邮件序列,不涉及任何模型;raad 模式会根据观察到的信号,把每个客户归入一个狭窄的漏斗,并基于该漏斗的故事和一项客户收益来撰写第一封邮件。
Raad 模式是以谁的名字命名的?它的名字来自 Intro 的 CEO Raad Mobrem。他的思路是把外呼拆分成狭窄、可观察的漏斗,每个漏斗共享一个故事,这启发了这个模式。
Franco 多久检查一次有没有新工作要做?它会运行一个心跳机制,默认每 15 分钟唤醒一次,检查安静时段和用量预算,判断最需要做的事情,去做,并在再次休眠前记录下来。
我能自己带潜在客户名单,而不是让 Franco 找客户吗?可以。Franco 接受三种 CSV:已调研的客户(每行附带一条有出处的观察)、普通的联系人或公司名单,以及禁止联系的邮箱地址或域名的抑制名单。
作者
GortexAI
大小
8.3 MB
星标
693
时长
1个月
提交 · 90 天