truenex-promoter 0.1.0a2

Autonomous AI marketing agent for open-source projects

Truenex Promoter

Autonomous AI marketing agent for open-source projects. Monitors your repo, discovers promotion opportunities, generates content drafts, and asks for your approval before taking action.

Human-in-the-loop by design. The agent proposes, you decide. No automated posts, no spam, no surprises.

Product Strategy: Open Core + Freemium UI

Edition	Interface	What's included	Price
OSS	CLI (this repo)	Monitoring, queue, generators, LLM local/remote, hardware analyzer	Free
Pro	Desktop UI (Tauri)	System tray, dashboard, analytics, auto-executors	$19/mo
Team	Desktop + Cloud	Multi-repo, multi-user, sync	$49/mo
Enterprise	SaaS Web	Zero install, white-label, API, support	Custom

The CLI is and will remain open-source forever. The UI is a closed-source paid add-on.

Current Status

Alpha — dogfooding on Truenex Memory.

What it does

1. Monitors GitHub — stars, issues, releases
2. Detects milestones — celebrates star milestones (10, 25, 50...)
3. Discovers Awesome Lists — finds relevant curated lists for your project
4. Finds Stack Overflow questions — unanswered questions matching your tags
5. Generates drafts — PR descriptions, social posts, dev.to articles, Product Hunt launches
6. Queues for approval — every action waits for your approve or reject

Quick Start

# Install from PyPI
pipx install truenex-promoter
# or
pip install truenex-promoter

# Configure (optional)
export TRUENEX_PROMOTER_OWNER=your-org
export TRUENEX_PROMOTER_REPO=your-repo

# Check once
trnx-promoter
# or
python -m truenex_promoter

# Run continuously
trnx-promoter --loop

# View pending actions
trnx-promoter --queue

# Approve an action
trnx-promoter --approve <action-id>

# Reject an action
trnx-promoter --reject <action-id> --reason "not relevant"

Configuration

All settings are via environment variables:

Variable	Default	Description
TRUENEX_PROMOTER_OWNER	marcomnit	GitHub owner
TRUENEX_PROMOTER_REPO	truenex-memory	GitHub repo
TRUENEX_PROMOTER_GITHUB_TOKEN	—	GitHub personal access token
TRUENEX_PROMOTER_INTERVAL	60	Check interval in minutes
TRUENEX_PROMOTER_LLM_PROVIDER	none	none, openai, deepseek, kimi, llamacpp
TRUENEX_PROMOTER_LLM_API_KEY	—	API key for remote LLM
TRUENEX_PROMOTER_LLM_MODEL	—	Model name (e.g. deepseek-chat)
TRUENEX_PROMOTER_LLM_MODEL_PATH	—	Path to .gguf file for local LLM
TRUENEX_PROMOTER_LLM_TEMPERATURE	0.7	Sampling temperature (0.0–2.0)
ENABLE_AWESOME_FINDER	true	Discover Awesome Lists
ENABLE_STACKOVERFLOW	true	Find Stack Overflow questions
ENABLE_DEVTO	true	Generate dev.to drafts
ENABLE_PRODUCTHUNT	true	Generate Product Hunt drafts

Configuration is validated on startup. Invalid values raise clear error messages.

LLM Configuration

The promoter can use a local LLM (llama.cpp) or remote API.

Local LLM (recommended: Nemotron 3 Nano 4B)

# Download Nemotron 4B Q4 (~3GB)
python -c "from huggingface_hub import hf_hub_download; hf_hub_download(repo_id='unsloth/NVIDIA-Nemotron-3-Nano-4B-GGUF', filename='NVIDIA-Nemotron-3-Nano-4B-Q4_K_M.gguf', local_dir='./models')"

# Configure
export TRUENEX_PROMOTER_LLM_PROVIDER=llamacpp
export TRUENEX_PROMOTER_LLM_MODEL_PATH="./models/NVIDIA-Nemotron-3-Nano-4B-Q4_K_M.gguf"
export TRUENEX_PROMOTER_LLM_N_GPU_LAYERS=-1

# Test
trnx-promoter --llm-check

Remote API (OpenAI, DeepSeek, Kimi)

export TRUENEX_PROMOTER_LLM_PROVIDER=deepseek
export TRUENEX_PROMOTER_LLM_API_KEY=sk-...
export TRUENEX_PROMOTER_LLM_MODEL=deepseek-chat
trnx-promoter --llm-check

Example Output

[2026-05-14 08:38:46 UTC] EVENT: NEW_RELEASE
Title: New release: v0.1.0-alpha.1
URL: https://github.com/marcomnit/truenex-memory/releases/tag/v0.1.0-alpha.1

[2026-05-14 08:38:46 UTC] ACTION PROPOSED (ID: 6696a400)
Title: Announce release v0.1.0-alpha.1
Approve:  trnx-promoter --approve 6696a400
Reject:   trnx-promoter --reject 6696a400

[2026-05-14 08:38:49 UTC] ACTION PROPOSED (ID: f15b266a)
Title: Propose addition to awesome-mcp-servers
Target: https://github.com/punkpeye/awesome-mcp-servers

Architecture

trnx-promoter check
    -> github_monitor.check()      # fetch repo state
    -> content_generator           # draft posts/PRs/articles
    -> awesome_finder              # discover awesome lists
    -> stackoverflow_finder        # find relevant questions
    -> action_queue.add()          # queue for approval (SQLite)
    -> notifier.action_proposed()  # notify user

User: trnx-promoter --approve ID
    -> action_queue.approve()      # mark approved
    -> executor.execute()          # generate file + open browser

Security

• Token sanitization — API keys and tokens are redacted from logs and error messages
• Path traversal protection — executor filenames are sanitized and bound-checked
• Action type whitelist — only known action types can be queued
• Rate limiting — GitHub API calls include retry with exponential backoff
• SQLite persistence — atomic operations prevent race conditions in the action queue

Development

# Clone
git clone https://github.com/marcomnit/truenex-promoter.git
cd truenex-promoter

# Install editable
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Build
python -m build

License

Apache 2.0