social-hook 0.9.0

Automated social media content from development activity

Social Hook

The marketing engine built for devs.

Social Hook watches your development, drafts what matters, and publishes where your audience lives. It evaluates every commit, decides what's post-worthy, drafts platform-native content in your voice, and routes it for approval — or runs fully autonomous.

Try It Out

pip install social-hook
social-hook quickstart /path/to/repo

Quickstart auto-detects your LLM provider, registers your project, imports commit history, analyzes your repo, and generates your first draft. To evaluate your last few commits through the full pipeline:

social-hook quickstart /path/to/repo --evaluate-last 3

To activate automatic triggers on every future commit:

social-hook project install-hook /path/to/repo

Then open the dashboard to see your drafts:

social-hook web

For Humans

Web Dashboard

The web dashboard is the primary interface for managing your content pipeline:

social-hook web

• Draft review — approve, reject, schedule, edit content and media
• Setup wizard and quick preview mode for onboarding
• Project management with commit history import
• Real-time notifications via WebSocket
• Media generation and preview
• Settings across 14 configuration sections
• Chat interface for bot commands

CLI Setup Wizard

For terminal-based configuration:

social-hook setup                # Guided setup (strategy, identity, platforms, voice, audience, keys)
social-hook setup --advanced     # Include scheduling, media, rate limits
social-hook setup --only voice   # Configure a single section

Messaging Channels

Social Hook separates notification channels (where you review drafts) from publishing platforms (where content gets posted). A platform-agnostic messaging adapter layer means channels are pluggable:

• Web — built-in. Notifications appear in the dashboard via WebSocket. Always available.
• Telegram — review and approve drafts from your phone. social-hook bot start

The adapter abstraction (MessagingAdapter) makes adding new channels (Slack, Discord, etc.) straightforward — each adapter handles send, edit, and callback independently.

For Agents

Social Hook is agent-first. Every capability is accessible programmatically:

social-hook help --json                    # Full command tree as structured JSON
social-hook help draft approve --json      # Drill into any subcommand
social-hook quickstart /path/to/repo --json  # Structured output from quickstart

• Every CLI command has a corresponding web API endpoint (and vice versa)
• All commands work non-interactively with --json output and --yes/--force flags
• Exit codes: 0 = success, 1 = user error, 2 = system error

How It Works

1. Detect — A git post-commit hook fires on every commit (installed per-project, works with any editor or agent)
2. Evaluate — An AI evaluator decides if the commit is post-worthy, assigns narrative arcs and episode types
3. Draft — Platform-native content is drafted in your voice, with per-platform identity and optional media
4. Publish — Drafts are scheduled, approved, or posted autonomously via platform adapters

Features

• Narrative Arcs — groups commits into storylines so posts tell a coherent story over time
• Media Generation — diagrams, code screenshots, diff images — generated and attached automatically
• Smart Scheduling — rate limits, optimal timing, posting cadence
• Multi-Platform — X, LinkedIn, Bluesky, Mastodon, custom platforms with per-platform identity
• Content Strategies — bundled templates (Build in Public, Release Updates, Curated Technical, Custom)
• Brand Discovery — AI analyzes your repo to understand what you're building and generate context
• Plugin System — custom evaluators, drafters, media tools, platform adapters
• Decision Rewind — undo a pipeline decision and all its downstream artifacts
• Batch Evaluate — evaluate multiple commits holistically in one pass

Free for Claude Code Users

If you have a Claude Code subscription, set your LLM provider to claude-cli/sonnet — zero additional API cost. Social Hook uses the Claude CLI as a backend, so your existing subscription covers all LLM calls.

Multi-Provider LLM

Social Hook supports multiple LLM providers via a provider/model-id format:

• anthropic/claude-sonnet-4-5 — Anthropic API (default)
• claude-cli/sonnet — Claude Code subprocess (free for subscribers)
• openrouter/anthropic/claude-sonnet-4.5 — OpenRouter
• ollama/llama3.3 — Local Ollama

Documentation

Full documentation: nj-io.github.io/social-hook/docs

Configuration

Social Hook uses a two-level config system:

• Global config (~/.social-hook/config.yaml) — API keys, platform credentials, LLM provider settings
• Project config (.social-hook/ in your repo) — social-context.md (project voice/context), content-config.yaml (content rules)

Contributing

See CONTRIBUTING.md for development setup, running checks, and PR guidelines.

Versioning

Social Hook uses Semantic Versioning. Releases are automated via Release Please — conventional commits on main trigger version bumps, changelog generation, and PyPI publishing.

License

MIT