Skip to content
Back to search

grokbot-x

EcomBrain's open-source Grok Bot growth agent for X: scouts the gold, drafts in your voice, publishes via Typefully with your approval, and nightly SkillOpt keeps only what worked.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yanniskiefer--grokbot-x/badge.svg)](/listings/yanniskiefer--grokbot-x)

HTML

<a href="/listings/yanniskiefer--grokbot-x"><img src="/api/listings/yanniskiefer--grokbot-x/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No pip install. Nothing to build. Python 3.10 or newer.

# 1. Environment: three values (Typefully -> Settings -> API + Development mode)
cp .env.example .env
# edit .env: YOUR_TYPEFULLY_API_KEY, YOUR_TYPEFULLY_SOCIAL_SET_ID, YOUR_HANDLE

# 2. Training wheels: example data so you can see the scorer work
cp examples/best_skill.starter.md skillopt/best_skill.md
cp skillopt/held_out.example.json skillopt/held_out.json
cp examples/trajectories.example.jsonl skillopt/trajectories.jsonl
python3 skillopt/sleep_cycle.py status

# 3. Your first original (needs the real API key from step 1)
python3 scripts/publish_original.py --text "your copy, hard first line"

# 4. Your first reply: creates a DRAFT, you publish it in the Typefully UI
python3 scripts/create_reply_draft.py --text "the missing next step" \
  --reply-to https://x.com/someone/status/0123456789012345678

# 5. Log the ship (same shape as examples/trajectories.example.jsonl)
python3 skillopt/sleep_cycle.py append --json '{"id":"d1","ts":"2026-11-08T10:00:00Z","type":"original","text":"...","features":{},"metrics":{},"split":"train"}'

Then:

1. Fill `docs/BRAND-BIBLE.template.md` so drafts know what you sell. 2. Drop the five `skills/*/SKILL.md` files into your Grok Bot skill folder. 3. Follow `docs/PLAYBOOK.md` daily. Replace the example trajectories with your own once real posts are logged.

No key, no publish: the scripts exit with a clear error and nothing is drafted to Typefully.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 171 lines
  1. <div align="center">
  2. <a href="https://yanniskiefer.github.io/grokbot-x/"><img src="docs/brand/hero.png" alt="EcomBrain's grokbot-x scouts the gold, drafts in your voice, waits for your yes, and every night SkillOpt keeps only what worked." width="100%"></a>
  3. # grokbot-x
  4. **The self-learning X growth agent for Grok Bot.**<br>
  5. Open source from [EcomBrain](https://ecombrain.io/?utm_source=github&utm_medium=grokbot-x&utm_campaign=oss&utm_content=readme-top), the AI operator for online stores.
  6. [![GitHub stars](https://img.shields.io/github/stars/YannisKiefer/grokbot-x?style=flat&color=171717)](https://github.com/YannisKiefer/grokbot-x/stargazers)
  7. [![CI](https://github.com/YannisKiefer/grokbot-x/actions/workflows/ci.yml/badge.svg)](https://github.com/YannisKiefer/grokbot-x/actions/workflows/ci.yml)
  8. [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-171717)](pyproject.toml)
  9. [![Zero dependencies](https://img.shields.io/badge/dependencies-0-171717)](#development)
  10. [![License: MIT](https://img.shields.io/badge/license-MIT-171717)](LICENSE)
  11. [Website](https://yanniskiefer.github.io/grokbot-x/) &nbsp;|&nbsp; [Quickstart](#quickstart-5-minutes-clean-machine) &nbsp;|&nbsp; [Operator guide](docs/OPERATOR.md) &nbsp;|&nbsp; [EcomBrain](https://ecombrain.io/?utm_source=github&utm_medium=grokbot-x&utm_campaign=oss&utm_content=readme-nav)
  12. </div>
  13. Most X agent repos give you a prompt pack that spams compose and hopes.
  14. This is the other thing: scout posts that actually move, draft in your
  15. voice, publish through the official Typefully API, log every ship as a
  16. trajectory, and let a nightly gate rewrite the playbook only when the
  17. numbers prove the edit helped. Built for tired founders. Dumbed down on purpose.
  18. ## Why you can trust it
  19. | | |
  20. |---|---|
  21. | **You approve every reply** | Replies land as Typefully drafts. A reply reaches X only when you click Publish. Originals publish straight through the API. |
  22. | **Official API only** | Typefully's API. No scripted browser on x.com, no auto-likes, no auto-follows. |
  23. | **Proof before change** | A skill edit is kept only if held-out data shows it does better. Everything else is logged as rejected. |
  24. | **Small and readable** | Python 3.10+ standard library, zero runtime dependencies, tested in CI on 3.10 and 3.14. |
  25. | **Yours** | MIT license. Your logs stay on your machine. AI disclosure is your setting (`X_MADE_WITH_AI`). |
  26. > **Built by EcomBrain.** We built grokbot-x to grow [EcomBrain](https://ecombrain.io/?utm_source=github&utm_medium=grokbot-x&utm_campaign=oss&utm_content=readme-callout) on X, and we open-sourced it because the loop works for any niche.
  27. > If you run an online store, EcomBrain is the AI operator for it: you talk to it, and it does the work across your store's apps. [See what it does](https://ecombrain.io/?utm_source=github&utm_medium=grokbot-x&utm_campaign=oss&utm_content=readme-callout-cta).
  28. <!-- Demo GIF (about 20 s): record a terminal run of `python3 skillopt/sleep_cycle.py status`
  29. followed by `python3 scripts/create_reply_draft.py ...` ending on the Typefully draft.
  30. Save as docs/demo/demo.gif (asciinema + agg, or a cropped screen recording), then
  31. uncomment the next two lines and delete this comment.
  32. <p align="center"><img src="docs/demo/demo.gif" alt="grokbot-x in 20 seconds: status, scout, a reply draft in your voice waiting for approval in Typefully" width="640"></p>
  33. -->
  34. ## How it works
  35. | Step | What happens |
  36. |---|---|
  37. | 1. Scout | Find posts with views far above the author's follower count: the gold. |
  38. | 2. Draft | Write the reply or post in your voice: hook, proof, body. |
  39. | 3. Approve | A reply lands in Typefully as a draft; you read it and publish. Originals go out through the API right away. |
  40. | 4. Log | Each shipped post becomes one JSON line with its results. |
  41. | 5. Learn | Every night SkillOpt tests one skill edit on held-out data and keeps it only if it wins. |
  42. Two lanes, never mixed:
  43. - **Publish lane.** Originals go out via the Typefully API. Replies are
  44. created as Typefully drafts, and a human clicks Publish NOW after
  45. reading them. That human click is the whole compliance model: official
  46. clients only, no scripted browser on x.com (X's automation rules
  47. ban scripting the site), no bulk or unsolicited automated replies, no
  48. auto-likes or auto-follows. Whether posts carry the "Made with AI"
  49. disclosure is your choice (`X_MADE_WITH_AI` in `.env`).
  50. - **Learning lane.** `skillopt/best_skill.md` is the trainable state.
  51. The reward is fixed in code, so no edit can win by rewriting it. The
  52. nightly gate judges held-out trajectories only (a live trial of the
  53. proposed skill, or a replay of its targeting rule), computes a bootstrap
  54. interval on the improvement (stricter with every idea tried), and adopts
  55. an edit only if the lower bound is above zero. Everything else lands in `rejected_edits.md`.
  56. You can replay two targeting rules offline before touching the live one:
  57. `python3 skillopt/sleep_cycle.py replay --skill-a A.md --skill-b B.md`.
  58. ## Quickstart (5 minutes, clean machine)
  59. No pip install. Nothing to build. Python 3.10 or newer.
  60. ```bash
  61. # 1. Environment: three values (Typefully -> Settings -> API + Development mode)
  62. cp .env.example .env
  63. # edit .env: YOUR_TYPEFULLY_API_KEY, YOUR_TYPEFULLY_SOCIAL_SET_ID, YOUR_HANDLE
  64. # 2. Training wheels: example data so you can see the scorer work
  65. cp examples/best_skill.starter.md skillopt/best_skill.md
  66. cp skillopt/held_out.example.json skillopt/held_out.json
  67. cp examples/trajectories.example.jsonl skillopt/trajectories.jsonl
  68. python3 skillopt/sleep_cycle.py status
  69. # 3. Your first original (needs the real API key from step 1)
  70. python3 scripts/publish_original.py --text "your copy, hard first line"
  71. # 4. Your first reply: creates a DRAFT, you publish it in the Typefully UI
  72. python3 scripts/create_reply_draft.py --text "the missing next step" \
  73. --reply-to https://x.com/someone/status/0123456789012345678
  74. # 5. Log the ship (same shape as examples/trajectories.example.jsonl)
  75. python3 skillopt/sleep_cycle.py append --json '{"id":"d1","ts":"2026-11-08T10:00:00Z","type":"original","text":"...","features":{},"metrics":{},"split":"train"}'
  76. ```
  77. Then:
  78. 1. Fill `docs/BRAND-BIBLE.template.md` so drafts know what you sell.
  79. 2. Drop the five `skills/*/SKILL.md` files into your Grok Bot skill folder.
  80. 3. Follow `docs/PLAYBOOK.md` daily. Replace the example trajectories with
  81. your own once real posts are logged.
  82. No key, no publish: the scripts exit with a clear error and nothing is
  83. drafted to Typefully.
  84. ## What each file does
  85. | Path | What |
  86. |---|---|
  87. | `docs/PLAYBOOK.md` | start here: the daily loop |
  88. | `docs/PUBLISH.md` | Typefully originals vs replies, allowed vs forbidden |
  89. | `docs/x-post-guide.md` | writing posts for the current algo weights |
  90. | `docs/x-human-cadence.md` | posting rhythm and volume discipline |
  91. | `docs/SKILLOPT.md` | the nightly gate, scorer reference |
  92. | `docs/OPERATOR.md` | voice and targeting rules |
  93. | `docs/BRAND-BIBLE.template.md` | fill-in product doctrine |
  94. | `skills/` | five Grok Bot SKILL.md files |
  95. | `skillopt/sleep_cycle.py` | scorer, gate, replay eval (offline) |
  96. | `skillopt/best_skill.md` | deployed skill; edit only via the gate |
  97. | `scripts/publish_original.py` | publish an original via Typefully |
  98. | `scripts/create_reply_draft.py` | create a reply draft for human publish |
  99. | `examples/` | fake trajectories + starter skill |
  100. Env vars: `YOUR_HANDLE`, `YOUR_TYPEFULLY_API_KEY`,
  101. `YOUR_TYPEFULLY_SOCIAL_SET_ID` (or `YOUR_SOCIAL_SET_ID`), optional
  102. `SKILLOPT_DIR` and `X_MADE_WITH_AI` (set `true` to disclose; default off).
  103. ## What NOT to do
  104. - No browser automation on x.com. X bans scripting the site; that is the
  105. one rule this kit will not help you break.
  106. - No bulk or unsolicited automated replies. Every reply needs a human
  107. click after a human read.
  108. - No filler originals to fill an hour. Bank the slot.
  109. - No engagement groups, no bought engagement, no "like my post" bait.
  110. - Do not hand-edit `skillopt/best_skill.md` around the gate. That file is
  111. the model's training data; unmeasured edits are how the loop dies.
  112. - Do not commit `.env`, real trajectories, or real handles. The
  113. gitignore already blocks the skillopt data files.
  114. ## Development
  115. ```bash
  116. pip install ruff pytest
  117. ruff check .
  118. pytest
  119. ```
  120. Contributing: `CONTRIBUTING.md`. Security: `SECURITY.md`.
  121. Changelog: `CHANGELOG.md`.
  122. ## Built by EcomBrain
  123. grokbot-x is how we grow [EcomBrain](https://ecombrain.io/?utm_source=github&utm_medium=grokbot-x&utm_campaign=oss&utm_content=readme-footer) on X.
  124. EcomBrain is the AI operator for online stores: you talk to it, it does
  125. the work across your apps. If you run a store, take a look.
  126. ## License
  127. MIT. Copyright 2026 Grok Bot X contributors.
  128. ## Disclaimer
  129. Not affiliated with xAI, X/Twitter, Typefully, or Microsoft.
  130. Educational kit. Do not spam. Human cadence is required. You are
  131. responsible for what you publish and for staying inside each platform's
  132. rules. No growth numbers are claimed here. Run it, log your own.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.