Metadata-Version: 2.4
Name: adauto
Version: 1.0.1
Summary: Developer marketing automation — pulse scanning, ethics filter, multi-platform posting
License: Proprietary
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Requires-Dist: httpx>=0.27
Requires-Dist: tenacity>=8.2
Requires-Dist: praw>=7.7
Requires-Dist: tweepy>=4.14
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"

# adauto

**Developer marketing automation — ethics-filtered, human-approved.**

adauto runs on your machine, drafts authentic posts for developer communities
(Reddit, Hacker News, dev.to, X/Twitter), hunts for people who actually have the
problem you solve, and learns from engagement over time. Every post passes an
ethics filter and waits for your explicit approval — nothing is ever published
automatically.

- **Local-first.** Runs as a CLI, an HTTP server, or an MCP server on your own machine.
- **Bring your own brain.** Works with deepstrain, OpenAI, Ollama, Anthropic, or any
  OpenAI-compatible API. No LLM backend is mandatory for the deterministic features.
- **Human-in-the-loop.** Generate and queue → review → approve → post. You hold the gate.
- **Honest by design.** Marketing claims are checked against a verified-claims source;
  the ethics filter blocks hype and unverifiable numbers.

Site: [adauto.massiron.com](https://adauto.massiron.com)

---

## Install

```bash
pip install adauto
```

Requires Python 3.11+.

---

## Start in 30 seconds

```bash
# 1. Register adauto (and any sibling tools) into every MCP client you have,
#    and start the local servers.
adauto setup

# 2. Open the web control center — run campaigns, review drafts, approve, connect.
adauto gui
```

`adauto gui` opens [http://127.0.0.1:8766/ui](http://127.0.0.1:8766/ui) in your
browser. Nothing posts without your approval.

Prefer the terminal? The classic loop is:

```bash
adauto init-from-repo .      # build a campaign from YOUR repo's README + manifest
adauto generate myproject    # draft posts (queued, NOT posted)
adauto review                # read each draft, approve or skip
adauto post myproject        # publish only what you approved
```

---

## LLM backend options

adauto needs a language model only to *write* posts. The deterministic features
(signal hunting, pulse scanning, analytics) use no LLM at all. When generation is
needed, adauto picks the first available backend in this order:

| Priority | Backend | How to enable | Notes |
|----------|---------|---------------|-------|
| 1 | **deepstrain** | Run `deepstrain serve` (auto-detected on `localhost:8765`) | Richest context; uses your own deepstrain key. Optional. |
| 2 | **OpenAI-compatible** | `ADAUTO_LLM_KEY` (+ optional `ADAUTO_LLM_URL`, `ADAUTO_LLM_MODEL`) | Works with OpenAI, Together, Groq, **Ollama** (`ADAUTO_LLM_URL=http://localhost:11434/v1`), etc. |
| 3 | **OpenAI** | `OPENAI_API_KEY` (+ optional `OPENAI_BASE_URL`) | Defaults to `gpt-4o-mini`. |
| 4 | **Anthropic Claude** | `ANTHROPIC_API_KEY` | Requires `pip install anthropic`. Model via `ADAUTO_CLAUDE_MODEL`. |

deepstrain is **optional** — adauto is fully standalone. To skip deepstrain even
when it is running, set `ADAUTO_NO_DEEPSTRAIN=1`.

See [`.env.example`](.env.example) for a copy-paste starting point.

---

## Command reference

### Setup & serving

| Command | What it does |
|---------|--------------|
| `adauto setup` | Detect all MCP clients (Claude Code, Kilo Code, Cursor, Windsurf, Claude Desktop, Cline), register every installed product, and start the HTTP servers. |
| `adauto setup --list-clients` | List supported MCP clients and their config-file paths (no changes made). |
| `adauto setup --no-start` | Register clients but do not launch any HTTP server. |
| `adauto gui` | Open the 5-tab web control center (`--port`, `--no-browser`). |
| `adauto chat` | Terminal REPL against a running MCP HTTP server (`--product`, `--url`). |
| `adauto serve` | Start the REST/automation HTTP server (`GET /`, `/exec`, `/eval`, `/approve`). |
| `adauto mcp` | Start the MCP server (stdio by default; `--http` for HTTP). |
| `adauto service install` | Register adauto as an OS service that auto-starts on boot. |

### Campaign lifecycle

| Command | What it does |
|---------|--------------|
| `adauto init` | Create config directories and the local database. |
| `adauto init-from-repo <path>` | Auto-generate a campaign from a repo's README + manifest (`--no-llm` for offline). |
| `adauto campaigns` | List configured campaigns. |
| `adauto generate <campaign>` | Draft posts and queue them for approval (does **not** post). |
| `adauto run` | Full loop across due platforms: generate → queue (never auto-posts). |
| `adauto review` | Interactively read each pending post and approve / skip / edit. |
| `adauto post <campaign>` | Publish only the posts you approved (`--dry-run` to preview). |

### Signals & learning

| Command | What it does |
|---------|--------------|
| `adauto hunt <campaign>` | Zero-cost, no-LLM scan of Reddit/HN/GitHub/dev.to/Stack Overflow for matching pain signals. |
| `adauto signals [campaign]` | Review found signals (`--stats` for a platform breakdown). |
| `adauto respond <campaign>` | Draft genuinely-helpful replies to found signals → queued for approval. |
| `adauto check-engagement` | Poll platforms for upvotes/comments and update the learning data. |
| `adauto report [campaign]` | ROI report: cost, cost-per-score, best-performing strategy. |
| `adauto status` | Pending / approved / posted counts and engagement scores. |

### Configuration

| Command | What it does |
|---------|--------------|
| `adauto configure` | Set platform API credentials (Reddit, Twitter, dev.to) into `~/.adauto/credentials.env`. |
| `adauto configure --show` | Show which credentials are set (masked). |
| `adauto license activate <key>` | Activate a Pro license. |
| `adauto license status` | Show current license tier. |

Run `adauto <command> --help` for the full option list on any command.

---

## `adauto setup` — one command, every client

`adauto setup` looks for installed MCP clients and registers every massiron
product you have on `PATH` as an **HTTP** MCP server (a single running server is
visible to every client *and* to you directly — no invisible stdio subprocesses).

Supported clients and the config files they use:

| Client | Config path |
|--------|-------------|
| Claude Code | `~/.claude.json` |
| Claude Desktop | `%APPDATA%/Claude/claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Kilo Code | `%APPDATA%/Code/User/globalStorage/kilocode.kilo-code/.../cline_mcp_settings.json` |
| Cline | `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/.../cline_mcp_settings.json` |

Default HTTP MCP ports: `adauto → 8767`, `deepstrain → 8765`, `atlas → 8768`.

```bash
adauto setup                 # detect, register, start servers
adauto setup --list-clients  # just show clients + paths
adauto setup --no-start      # register only; start servers yourself later
```

After registering, restart your MCP client once to pick up the new servers.

---

## `adauto chat` — talk to a running server

A minimal REPL that speaks MCP to a running HTTP server. Useful for poking at
tools without an LLM client.

```bash
adauto chat                       # connect to adauto      (port 8767)
adauto chat --product deepstrain  # connect to deepstrain  (port 8765)
adauto chat --url http://HOST:PORT
```

Example session:

```text
$ adauto chat
[chat] Connected to adauto v0.5.5  (http://localhost:8767)
[chat] 5 tools: run, status, approve, post, report
[chat] Type 'tools' to list, '<tool> [k=v ...]' to call, 'q' to quit.

adauto> status
{
  "pending": 3,
  "approved": 1,
  "posted": 12
}
adauto> run campaign=myproject
{
  "queued": 4,
  "next": "Review with `adauto review`"
}
adauto> q
```

Inside the REPL: `tools` lists available tools, `<tool> key=value …` calls one
(values are coerced to int/bool when they look like it), and `q` / `quit` exits.

---

## `adauto sessions` — resume an unfinished thread

adauto can find where your AI coding tools store their chat history on disk —
Claude Code, Cursor, Windsurf, Cline, Kilo and Claude Desktop — so a
half-finished thread can be picked up and handed to deepstrain to keep building.
Read-only, deterministic, no LLM, no network.

```bash
adauto sessions                      # list detected sources, newest first
adauto sessions --json               # machine-readable (pipe into automation)
adauto sessions --handoff deepstrain # 'continue from' brief for deepstrain
adauto sessions --handoff deepstrain --product claude-code
```

Example:

```text
$ adauto sessions
[adauto] 2 chat-history source(s) — newest first:

  Claude Code       122 sessions   last: 2026-06-01 22:56:06
                   one .jsonl per session, grouped by project path
                   → ~/.claude/projects/<project>/<session>.jsonl

  deepstrain         16 sessions   last: 2026-06-01 10:48:14
                   deepstrain's own session logs (see `deepstrain logs`)
```

The `--handoff` brief restates the recent exchange and the goal so another agent
can continue exactly where you left off — the "continue from Claude / from your
IDE" workflow.

---

## `adauto gui` — the web control center

```bash
adauto gui                 # opens http://127.0.0.1:8766/ui
adauto gui --port 9000     # custom port
adauto gui --no-browser    # start the server without opening a browser
```

Five tabs:

| Tab | What it does |
|-----|--------------|
| **Campaigns** | Overview stats, pick a campaign, **Run** it (generate + queue), and pull a ROI **Report**. |
| **Review** | Every pending draft shown in full with its ethics status. Approve all, or approve/skip one at a time. A badge shows how many are waiting. |
| **Signals** | Pain signals found by `adauto hunt`, grouped by campaign — the people who need what you built. |
| **Analytics** | Engagement scores and cost/score by platform and post type, plus a live readout of which **LLM backend** is active. |
| **Connect** | One-click "register in all MCP clients" (same as `adauto setup`), live server status, and an MCP tool tester. |

Nothing posts from the GUI without your approval.

---

## Ecosystem (optional)

adauto stands alone. It is also one of three independent tools that share a
local-first, bring-your-own-LLM design:

- **adauto** — developer marketing automation (this tool).
- **deepstrain** — terminal-native AI engineering agent. If running, adauto uses
  it as its richest content backend; otherwise adauto falls back to any
  OpenAI-compatible API. Entirely optional.
- **atlas** — deterministic code intelligence (offline, zero LLM tokens).

`adauto setup` will register whichever of these are installed into your MCP
clients. Install only what you need.

---

## Configuration & data locations

- Campaign configs: `~/.adauto/campaigns/<name>.toml` (copy from the repo's `campaigns/`).
- Platform credentials: `~/.adauto/credentials.env` (user-only permissions, auto-loaded).
- Local database (queue, engagement, signals): under `~/.adauto/`.

---

## Licensing

- **Free** — 1 campaign, 3 posts/day, all deterministic features (hunt, signals, pulse).
- **Pro ($29/mo)** — unlimited campaigns, all platforms, engagement learning.

```bash
adauto license activate ADTO-XXXXX-XXXXX-XXXXX-XXXXX
adauto license status
```

Get a license at [adauto.massiron.com](https://adauto.massiron.com).
