{
  "markdown": "# Hum\n\nAI agent skill for content writing on X and LinkedIn.\n\n**Your AI content writer**. Hum handles the full content lifecycle: it crawls your feed sources daily and sends a ranked digest, brainstorms ideas grounded in real research across YouTube, X, Reddit, HN, and the web, then drafts posts in your voice using proven writing styles — from technical storytelling to contrarian takes. Every draft goes through a research-outline-approval loop before writing begins. Once approved, Hum publishes directly to X and LinkedIn via API connectors, and can also manage engagement by drafting replies to comments and suggesting accounts to follow.\n\n## Installation\n\n### Claude Code\n\n```bash\nclaude /install https://github.com/hum-growth/hum\n```\n\nOr clone and add to your skills directory:\n```bash\ngit clone https://github.com/hum-growth/hum ~/.claude/skills/hum\n```\n\n### OpenClaw / ClawHub\n\n```bash\nclaw install hum-writer\n```\n\n### Codex\n\nCopy `agents/openai.yaml` to your agents directory:\n```bash\ncp agents/openai.yaml ~/.codex/agents/hum.yaml\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/hum-growth/hum\n```\n\n## Setup\n\n### 0. Install Python dependencies\n\nRun `bash setup.sh` from the repo root to create a venv at `venv/` and install everything from `requirements.txt`. Activate it with `source venv/bin/activate` before running any `python3 scripts/...` command, or substitute your own Python path if you manage dependencies differently. All examples below assume `python3` resolves to the venv and the cwd is the skill folder.\n\n### 1. Configure data directory\n\nSet the data directory via `openclaw.json` or environment variable (defaults to `~/Documents/hum` if neither is set):\n\n**Option A — openclaw.json** (recommended for OpenClaw users):\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"hum\": {\n        \"config\": {\n          \"hum_data_dir\": \"~/Documents/hum\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Option B — environment variable:**\n```bash\nexport HUM_DATA_DIR=~/Documents/hum\n```\n\n### 2. Configure delivery targets\n\nSet where each loop step is delivered. Supports any channel target recognised by your agent runtime (Telegram chat ID, WhatsApp number, etc.). You can route each step to a different destination — e.g. the digest to a shared group channel and brainstorm/engage to your personal DM.\n\n**Option A — openclaw.json** (recommended):\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"hum\": {\n        \"config\": {\n          \"hum_digest_target\": \"telegram:-100YOUR_GROUP_ID\",\n          \"hum_brainstorm_target\": \"telegram:ghost:YOUR_PERSONAL_ID\",\n          \"hum_engage_target\": \"telegram:ghost:YOUR_PERSONAL_ID\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Option B — environment variables:**\n```bash\nexport HUM_DIGEST_TARGET=telegram:-100YOUR_GROUP_ID\nexport HUM_BRAINSTORM_TARGET=telegram:ghost:YOUR_PERSONAL_ID\nexport HUM_ENGAGE_TARGET=telegram:ghost:YOUR_PERSONAL_ID\n```\n\n**Target format:** `channel:recipient` or `channel:account:recipient`. The optional `account` selects which bot account sends the message (e.g. `ghost`). When omitted the default account is used.\n\nAny target that is not set is skipped silently — the loop step still runs, output is just not delivered.\n\n### 3. Setup workspace and content profile\n\nRun `/hum init` to create all required directories and template files. Then edit the generated files in your data directory to set up your voice, audience, channels, content pillars, and knowledge sources (`knowledge/index.md`).\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/hum init` | Set up data directory with templates and folders |\n| `/hum loop` | Run the full daily morning workflow |\n| `/hum refresh-feed` | Crawl all sources (X, HN, YouTube, knowledge), rank, send digest |\n| `/hum crawl` | Crawl knowledge sources (blogs, YouTube transcripts, podcasts) |\n| `/hum sources` | List, add, or remove social feed sources |\n| `/hum config` | Show current data_dir configuration |\n| `/hum brainstorm` | Research topics and generate content ideas |\n| `/hum learn` | Make improvements to content strategy |\n| `/hum ideas` | Show idea pipeline |\n| `/hum content` | List current drafts |\n| `/hum create` | Draft a post (platform, type, idea) |\n| `/hum publish` | Publish an approved draft |\n| `/hum engage` | Follow accounts, suggest replies, draft responses |\n| `/hum samples` | Collect writing samples from social media |\n| `/hum feedback` | Upvote/downvote digest items to train the ranker |\n\n## Daily Loop\n\nRuns at 6am SGT via `scripts/loop.py`. Sundays include an extra strategy refresh step.\n\n```\n6:00 am ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─\n\n  ┌─────────────────────┐\n  │    1. Digest        │──── Fetch feed ---─────-┐\n  │    /hum refresh-feed│──── Rank feed posts ───┐│\n  └─────────┬───────────┘                        ││\n            │                                    ││\n            ▼                                    ▼▼\n  ┌─────────────────────┐              ┌────────────────────┐\n  │  Send Telegram      │              │  feeds.json        │\n  │  morning digest     │              │  (aggregated feed) │\n  └─────────────────────┘              └────────────────────┘\n                                                 │\n                                                 ▼\n  ┌─────────────────────┐              ┌────────────────────┐\n  │    2. Engage        │              │  VOICE.md          │\n  │    /hum engage      │◄─────────────│  CHANNELS.md       │\n  └─────────┬───────────┘              └────────────────────┘\n            │\n            ▼\n  ┌─────────────────────────────────────┐\n  │  Draft replies + follow suggestions │\n  │  (presented for user approval)      │\n  └─────────────────────────────────────┘\n\n  ┌─────────────────────┐              ┌────────────────────┐\n  │    3. Brainstorm    │              │  CONTENT.md        │\n  │    /hum brainstorm  │◄─────────────│  (content pillars) │\n  |    ideas.json       |              │  feeds.json        │\n  └─────────┬───────────┘              └────────────────────┘\n            │                          \n            ▼\n  ┌─────────────────────────────────────┐\n  │  Top feed items + idea suggestions  │\n  │  → \"Any ideas to add?\"              │\n  │  → \"Want to work on posts today?\"   │\n  └─────────────────────────────────────┘\n\n  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─┐\n  |   4. Learn         |              ┌────────────────────┐\n  │   /hum learn       │◄─────────────│  feeds.json        │\n  |  (Sundays only)    │──web search──│  CHANNELS.md       │\n  └ ─ ─ ─ ─ ┬ ─ ─ ─ ─ ─┘              └────────────────────┘\n            │\n            ▼\n  ┌─────────────────────────────────────┐\n  │  Analyze feed trends                │\n  │  Research platform algorithms       │\n  │  Update context files               │\n  └─────────────────────────────────────┘\n\n─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─\n\n  User wakes up → reviews digest, approves/edits suggestions\n```\n\nRun individual steps with `python3 scripts/loop.py --step digest|engage|brainstorm|learn`.\n\n### Scheduling the Daily Loop\n\nThe daily loop needs a cron job or scheduler to run automatically. Setup varies by platform.\n\n#### OpenClaw\n\nOpenClaw has built-in scheduling. Add a `cron` entry to your `openclaw.json`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"hum\": {\n        \"cron\": \"0 6 * * *\",\n        \"config\": {\n          \"hum_data_dir\": \"~/Documents/hum\"\n        }\n      }\n    }\n  }\n}\n```\n\nThis runs `/hum refresh-feed` → engage → brainstorm at 6am daily. OpenClaw handles process management, retries, and logging.\n\n#### Claude Code\n\nClaude Code does not have built-in scheduling. Use a system crontab to invoke the CLI in non-interactive mode:\n\n```bash\n# Edit your crontab\ncrontab -e\n\n# Add this line (runs at 6am daily)\n0 6 * * * cd /path/to/hum && claude -p \"Run the daily hum loop: python3 scripts/loop.py\" --allowedTools \"Bash(command)\" 2>&1 >> ~/.hum/loop.log\n```\n\nAlternatively, use the `/loop` skill if available in your Claude Code session:\n```\n/loop 24h /hum refresh-feed\n```\n\n> **Note:** The crontab approach requires Claude Code CLI (`claude`) to be installed and authenticated. All core feed sources (X via Bird, HN, YouTube, knowledge) run headless — no browser needed.\n\n#### Codex\n\nUse a system crontab to invoke the Codex CLI:\n\n```bash\n0 6 * * * cd /path/to/hum && codex -q \"Run the daily hum loop: python3 scripts/loop.py\" 2>&1 >> ~/.hum/loop.log\n```\n\n#### Gemini CLI\n\nUse a system crontab to invoke the Gemini CLI:\n\n```bash\n0 6 * * * cd /path/to/hum && gemini -p \"Run the daily hum loop: python3 scripts/loop.py\" 2>&1 >> ~/.hum/loop.log\n```\n\n#### All platforms — manual run\n\nYou can always run the loop manually inside any agent session:\n```\n/hum refresh-feed\n```\nOr run the Python script directly:\n```bash\npython3 scripts/loop.py\n```\n\n## Feed\n\nMost feed sources use direct APIs — no browser automation required. X credentials are session cookies extracted once from browser devtools.\n\n| Source | Method | Credentials | Cost |\n|--------|--------|-------------|------|\n| **X home feed** | Bird API (`filter:follows`) | `AUTH_TOKEN` + `CT0` cookies | Free |\n| **X profiles** | Bird API (`from:handle`) | `AUTH_TOKEN` + `CT0` cookies | Free |\n| **Hacker News** | Algolia public API | None | Free |\n| **YouTube** (digest) | yt-dlp (local tool) | None | Free |\n| **Knowledge sources** | RSS, sitemaps, YouTube transcripts, podcasts | None | Free |\n\nX credentials go in `~/.hum/credentials/x.json` or via `HUM_X_AUTH_TOKEN` / `HUM_X_CT0` env vars. If missing, X sources are skipped and the rest of the pipeline still runs.\n\nTwo source lists serve different purposes:\n- `feed/sources.json` — Social/ephemeral sources (X feed, X profiles, HN, YouTube channels). Managed via `/hum sources`.\n- `knowledge/index.md` — Long-form knowledge sources (RSS blogs, sitemaps, YouTube transcripts, podcasts). Full articles saved to `knowledge/<source_key>/`.\n\n## Image Generation\n\nHum can auto-generate post images using AI. Configure a provider and Hum will generate images during the `/hum create` workflow when an `image_prompt` is set.\n\nSet the active provider via the `HUM_IMAGE_MODEL` environment variable or `image_model` config key. Valid values: `gemini` (default), `openai`, `grok`, `minimax`.\n\n### Providers\n\n| Provider | Model | Env Var | Cost |\n|----------|-------|---------|------|\n| **gemini** (default) | gemini-2.5-flash-image | `GEMINI_API_KEY` | Free tier available |\n| **openai** | gpt-image-1 | `OPENAI_API_KEY` | PAYG |\n| **grok** | grok-2-image | `XAI_API_KEY` | Free with xAI tier |\n| **minimax** | image-01 | `MINIMAX_API_KEY` | PAYG |\n\n### Configuration\n\nSet API keys as environment variables or in `openclaw.json` → `env.vars`:\n\n```json\n{\n  \"env\": {\n    \"vars\": {\n      \"GEMINI_API_KEY\": \"your_key_here\"\n    }\n  }\n}\n```\n\nChoose the active provider in `openclaw.json` → `skills.entries.hum.config.hum_image_model`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"hum\": {\n        \"config\": {\n          \"hum_image_model\": \"gemini\"\n        }\n      }\n    }\n  }\n}\n```\n\nOr override with the `HUM_IMAGE_MODEL` environment variable.\n\n### Visual Style\n\nAdd a `## Visual Style` section to your `VOICE.md` file to define your brand's visual identity. Hum appends this to every image generation prompt automatically.\n\n### Test\n\n```bash\npython3 scripts/lib/image-gen/generate.py \\\n  --prompt \"a clean professional image for a finance tech tweet\" \\\n  --platform twitter --output /tmp/test.png\n```\n\n## Dashboard\n\nBrowse all your hum data in a local web UI — feed, knowledge articles, ideas, content drafts, loop runs, and learnings.\n\n```bash\npython3 scripts/dashboard/serve.py          # http://localhost:8400\npython3 scripts/dashboard/serve.py --open   # auto-open browser\npython3 scripts/dashboard/serve.py --port 9000  # custom port\n```\n\nThe server indexes your knowledge articles at startup (cached to `knowledge/_index.json`). Use `--rebuild-index` to force a fresh scan.\n\n## Local Development\n\nTo develop Hum locally, symlink your OpenClaw workspace to this repo:\n\n```bash\nln -sfn ~/Code/hum ~/.openclaw/workspace/skills/hum\n```\n\nThis makes both paths point to the same files. Edits you make in `~/.openclaw/workspace/skills/hum` (e.g. via OpenClaw) are immediately reflected in `~/Code/hum`, and vice versa. There's no sync step — `git status` shows your changes right away.\n\nTo ship your changes, use the `/ship` command in Claude Code, which commits, pushes, and opens a PR following conventional commit conventions. See `.claude/commands/ship.md` for details.\n\nOnce pushed, anyone can install the updated skill via `claude /install`, `claw install hum-writer`, etc.\n\n",
  "bytes": 12627,
  "sha": "568b9de6fdbb4bb34f7b76a8525caab158378793a3e94a63361adc5d91e5ffb4",
  "repo_slug": "hum-growth/hum",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hum_growth_hum_3ba99ee7/readme"
}