Skip to content
Back to search

log

Open-source CLI and MCP server that lets your AI agent (Claude Code, Codex) run your social media: DMs, replies, inbox and outbound on X, Discord, Slack, Instagram, Reddit and LinkedIn, in your own voice. Free Xreacher alternative.

Safety scan

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

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/matthewdonsemail-lab/log with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/matthewdonsemail-lab/log'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/matthewdonsemail-lab--log/badge.svg)](/listings/matthewdonsemail-lab--log)

HTML

<a href="/listings/matthewdonsemail-lab--log"><img src="/api/listings/matthewdonsemail-lab--log/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.

These steps run a script from the network that findsafeskills does not scan.

Install

curl -fsSL https://log.listeningkit.com/install.sh | sh                        # macOS and Linux
irm https://log.listeningkit.com/install.ps1 | iex                             # Windows (PowerShell)
curl -fsSL https://log.listeningkit.com/install.sh | sh -s -- --skills all     # also every play as a skill

This installs the `log` and `logMcp` commands, and Python with everything the platform engines need. It writes your settings to `~/.logCli/.env`. Already have [Bun](https://bun.sh)? `bun add -g @listeningkit/log` installs just the commands. Already have log? `--skills all --skillsOnly` adds only the skills; on Windows, set `$env:LOG_SKILLS = "all"` before the PowerShell line. More: [docs/install.md](docs/install.md).

Connect your accounts

Add the account once, sign it in, then check that the platform still accepts it:

| Platform | How to sign in | |---|---| | X | `log twitter cookies save --account <handle>`: paste `auth_token`, `ct0` and `twid` from a cookie-export extension | | LinkedIn | `log linkedin cookies save --account <publicId>`: paste `li_at` and `JSESSIONID` | | Slack | `log slack cookies save --account <name>`: paste the `d` cookie | | Discord, Reddit, Instagram | `log localAccount add --platform <platform> --account <name>`, then `log inspect start --account <name>`, sign in by hand in the window that opens, and `log inspect do stop --account <name>` to save the session | | Facebook | `log localAccount add --platform facebook --account <name>`, then `log facebook connect --account <name>` |

Then check it with `log <platform> session check --account <name>`, which sends nothing. The answer is `loggedIn`, `loggedOut` or `restricted`. Cookies are always typed into a masked prompt and never passed as flags. More: [docs/accounts.md](docs/accounts.md).

Connect your agent

| Agent | How to connect | |---|---| | Claude Code | `claude mcp add log -- logMcp` | | Hermes | `hermes plugins pack install https://log.listeningkit.com/hermes-pack.yaml`: the [log plugin for Hermes](hermesPlugin/README.md), tools, skills, dashboard tab and router hook in one install | | Codex, Cursor, OpenCode and other MCP clients | add `logMcp` as a stdio MCP server: [docs/mcp.md](docs/mcp.md) | | Claude, ChatGPT and Grok, or an agent on a server | the hosted server, `https://mcp.listeningkit.com/mcp`, over OAuth |

Then ask in plain words: *"read my X DMs and tell me who's waiting on me"*. log's router names the play for that request, and the agent follows its steps. Every harness, and what each one can do: [Works in every harness](#works-in-every-harness).

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 · 516 lines · 4 findings marked
  1. <p align="center">
  2. <img src="banner.png" alt="log: run your social accounts from the command line or your AI agent" width="100%" />
  3. </p>
  4. <p align="center">
  5. <a href="https://x.com/xAccount/status/2120938715820474690"><img src="media/readme/hermesIntro.gif" alt="Introducing log by ListeningKit, in collaboration with Hermes Agent: Hermes asks who is waiting for a reply, log reads every inbox, and the answer lands on Discord in your own voice" width="100%" /></a>
  6. <br><sub>Introducing log, in collaboration with Hermes Agent. <a href="https://x.com/xAccount/status/2120938715820474690">Watch the launch video with sound on X →</a></sub>
  7. </p>
  8. <h3 align="center">One command for every social account you run.</h3>
  9. <p align="center"><b>Read and answer X, Discord, Slack, Instagram, Reddit, LinkedIn and Facebook<br>
  10. from your terminal, or from any agent: Claude Code, Codex, Cursor, Hermes, OpenCode, ChatGPT, Claude and Grok.</b><br>
  11. <a href="docs/useCases/README.md">See every play, step by step →</a></p>
  12. <p align="center">
  13. <a href="https://www.npmjs.com/package/@listeningkit/log"><img src="https://img.shields.io/npm/v/@listeningkit/log?color=cb3837&label=npm&logo=npm" alt="npm: @listeningkit/log" /></a>
  14. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT" /></a>
  15. <a href="docs/mcp.md"><img src="https://img.shields.io/badge/MCP-logMcp-7c3aed" alt="MCP server: logMcp" /></a>
  16. <a href="https://log.listeningkit.com/docs"><img src="https://img.shields.io/badge/docs-log.listeningkit.com-2ea44f" alt="Docs: log.listeningkit.com" /></a>
  17. </p>
  18. ```bash
  19. curl -fsSL https://log.listeningkit.com/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 23 on GitHub
  20. claude mcp add log -- logMcp
  21. ```
  22. <table>
  23. <tr>
  24. <td width="50%" valign="middle">
  25. ### X, from your agent
  26. *"Read my X DMs and tell me who's waiting on me."*
  27. The old inbox and the encrypted X Chat, read as one.
  28. </td>
  29. <td width="50%">
  30. ```bash
  31. log twitter dms --account <name> --waiting
  32. ```
  33. </td>
  34. </tr>
  35. <tr>
  36. <td width="50%" valign="middle">
  37. ### Discord, Slack and Instagram, live
  38. Every new message is pushed to your agent the moment it lands.
  39. </td>
  40. <td width="50%">
  41. ```bash
  42. log discord read --account <name> --channel "<chat>"
  43. log slack read --account <name> --channel "<chat>"
  44. log instagram dms --account <name>
  45. ```
  46. </td>
  47. </tr>
  48. <tr>
  49. <td width="50%" valign="middle">
  50. ### Answers in your own voice
  51. Every draft is checked against how you really write to that person before it goes.
  52. </td>
  53. <td width="50%">
  54. ```bash
  55. log voice --to <handle> --text "<draft>"
  56. ```
  57. </td>
  58. </tr>
  59. <tr>
  60. <td width="50%" valign="middle">
  61. ### Facebook Marketplace and groups
  62. Listings kept live across local accounts, and groups read for people asking for a service.
  63. </td>
  64. <td width="50%">
  65. ```bash
  66. log facebook listings
  67. log facebook join group --account <name> --group <url>
  68. ```
  69. </td>
  70. </tr>
  71. </table>
  72. <p align="center">📖 <a href="https://log.listeningkit.com/docs"><b>Full documentation →</b></a></p>
  73. log runs your social accounts from the command line, or from your AI agent. It reads DMs, group chats, replies and notifications, and it sends messages, replies, likes, follows, reactions and voice notes for you. It's one command, `log`, and one MCP server, `logMcp`, and it runs on your own machine with your own accounts. Nothing acts until you say so: every command that changes something is a dry run until you add `--live`. It's free and open source.
  74. ## Quick start
  75. ### Install
  76. ```bash
  77. curl -fsSL https://log.listeningkit.com/install.sh | sh # macOS and Linux
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 108 on GitHub
  78. irm https://log.listeningkit.com/install.ps1 | iex # Windows (PowerShell)
  79. curl -fsSL https://log.listeningkit.com/install.sh | sh -s -- --skills all # also every play as a skill
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 110 on GitHub
  80. ```
  81. This installs the `log` and `logMcp` commands, and Python with everything the platform engines need. It writes your settings to `~/.logCli/.env`. Already have [Bun](https://bun.sh)? `bun add -g @listeningkit/log` installs just the commands. Already have log? `--skills all --skillsOnly` adds only the skills; on Windows, set `$env:LOG_SKILLS = "all"` before the PowerShell line. More: [docs/install.md](docs/install.md).
  82. ### Connect your accounts
  83. Add the account once, sign it in, then check that the platform still accepts it:
  84. | Platform | How to sign in |
  85. |---|---|
  86. | X | `log twitter cookies save --account <handle>`: paste `auth_token`, `ct0` and `twid` from a cookie-export extension |
  87. | LinkedIn | `log linkedin cookies save --account <publicId>`: paste `li_at` and `JSESSIONID` |
  88. | Slack | `log slack cookies save --account <name>`: paste the `d` cookie |
  89. | Discord, Reddit, Instagram | `log localAccount add --platform <platform> --account <name>`, then `log inspect start --account <name>`, sign in by hand in the window that opens, and `log inspect do stop --account <name>` to save the session |
  90. | Facebook | `log localAccount add --platform facebook --account <name>`, then `log facebook connect --account <name>` |
  91. Then check it with `log <platform> session check --account <name>`, which sends nothing. The answer is `loggedIn`, `loggedOut` or `restricted`. Cookies are always typed into a masked prompt and never passed as flags. More: [docs/accounts.md](docs/accounts.md).
  92. ### Connect your agent
  93. | Agent | How to connect |
  94. |---|---|
  95. | Claude Code | `claude mcp add log -- logMcp` |
  96. | Hermes | `hermes plugins pack install https://log.listeningkit.com/hermes-pack.yaml`: the [log plugin for Hermes](hermesPlugin/README.md), tools, skills, dashboard tab and router hook in one install |
  97. | Codex, Cursor, OpenCode and other MCP clients | add `logMcp` as a stdio MCP server: [docs/mcp.md](docs/mcp.md) |
  98. | Claude, ChatGPT and Grok, or an agent on a server | the hosted server, `https://mcp.listeningkit.com/mcp`, over OAuth |
  99. Then ask in plain words: *"read my X DMs and tell me who's waiting on me"*. log's router names the play for that request, and the agent follows its steps. Every harness, and what each one can do: [Works in every harness](#works-in-every-harness).
  100. ## Platforms
  101. | Platform | What log does | How it talks to the platform |
  102. |---|---|---|
  103. | [X](docs/platformGuides/x.md) | DMs and X Chat, notifications, followers, replies, posts, likes, follows, lists, reactions, voice notes, queues | its own API client, one session per account, no browser |
  104. | [Discord](docs/platformGuides/discord.md) | DMs, groups and server channels, live; sends, reactions, voice notes, files | its own API client and the live gateway, no browser |
  105. | [Slack](docs/platformGuides/slack.md) | DMs and group DMs in every workspace, live; sends, reactions, voice notes | its own API client and the live socket, no browser |
  106. | [Instagram](docs/platforms/instagram/README.md) | DM threads, live; sends, photos, reactions, voice notes | its own API client and the realtime connection, no browser |
  107. | [Facebook](docs/platformGuides/facebook.md) | Marketplace listings, groups, warm-up | the account's own browser, opened once a day through a proxy in its home country |
  108. | [Reddit](docs/platformGuides/reddit.md) | session check (new) | its own API client |
  109. | [LinkedIn](docs/platformGuides/linkedin.md) | session check (new) | its own API client |
  110. ## Highlights
  111. - **Start from a play.** Each [use case](docs/useCases/README.md) is a workflow written step by step: what to run, and what tells you each step worked. With `--skills all`, your agent picks the right one from what you say.
  112. - **Your voice, checked.** A draft is read against how you really write to that person, for AI phrasing and for hidden characters, before it can be sent.
  113. - **One session per account.** Each account keeps one connection open, the way the platform's own app does, never a new one per command.
  114. - **Live inbox.** New messages are pushed into your agent's context as they arrive, and two agents never answer the same chat.
  115. - **Kept human.** Every account has its own daily limits, pacing and local waking hours. A refusal from the platform stops the run, and nothing is retried.
  116. - **Your machine, your data.** Accounts and sessions stay in `~/.logCli`. Many accounts? Keep them in [Twenty](docs/twenty.md), an open-source CRM, so every machine, agent and teammate sees the same ones.
  117. ## Works in every harness
  118. A harness is the agent app you talk to log through. log is the same MCP server in all of them, with the same tools under the same names. What changes is how log's guidance reaches the model and how new messages reach it:
  119. | Harness | Connects | How it's told what to do | How new messages reach it | Views and sign-in |
  120. |---|---|---|---|---|
  121. | [Claude Code](docs/harnesses/claudeApp.md#claude-code) | local or hosted | its prompt hook runs the router on every prompt | hooks on every prompt and after every tool call | text; sign-in in the window on your screen |
  122. | [Codex](docs/harnesses/codex.md) | local or hosted | its prompt hook | hooks on every prompt and around tool calls | text |
  123. | [Hermes](docs/harnesses/hermes.md) | local or hosted | the `logHooks` plugin's `pre_llm_call`, before every model call | the same hook, before every model call | text, plus a **log tab** in the Hermes dashboard |
  124. | [OpenCode](docs/harnesses/README.md) | local | its prompt hook | its plugin's hooks | text |
  125. | [Antigravity](docs/harnesses/README.md) | local | its prompt hook | its hooks | text |
  126. | [Cursor](docs/harnesses/cursor.md) | local or hosted | `getGuide({ ask })` (Cursor's prompt hook can't add context) | `sessionStart` and `postToolUse` hooks | MCP Apps: `report` and `browserView` inline |
  127. | [Claude (web, desktop, mobile)](docs/harnesses/claudeApp.md) | hosted | `getGuide({ ask })` | when it asks | MCP Apps inline |
  128. | [ChatGPT](docs/harnesses/chatgpt.md) | hosted | `getGuide({ ask })` | when it asks | MCP Apps inline |
  129. | [Grok (xAI API)](docs/harnesses/grok.md) | hosted | `getGuide({ ask })` | when it asks | text |
  130. The full table, written from the code (`HARNESSES` in `src/agentHooks/harness/types.ts`), with each hook's text limit and where its hooks live: [docs/harnesses](docs/harnesses/README.md).
  131. ### The log plugin for Hermes
  132. Hermes runs all day, on your machine or a server, and talks to you on Telegram, Slack and its desktop app. The [log plugin](hermesPlugin/README.md) gives it log's tools, every play as a skill, and a log tab in its dashboard. Hermes reads freely, and every send, reply or post asks you first.
  133. ```bash
  134. hermes plugins pack install https://log.listeningkit.com/hermes-pack.yaml
  135. ```
  136. One command installs and enables both halves: `log` (log's tools, every play as a skill, the dashboard's log tab) and `logHooks` (the router hook). Hermes shows what the pack installs, pinned to an exact commit, and asks once. Install log itself first; the hook finds it on its own.
  137. <table>
  138. <tr>
  139. <td width="50%"><img src="hermesPlugin/docs/screenshots/xInbox.jpg" alt="Hermes asks who is waiting for a reply, and log finds the X conversations waiting on you" /></td>
  140. <td width="50%"><img src="hermesPlugin/docs/screenshots/yourVoice.jpg" alt="A draft in your own voice, checked before anything is sent" /></td>
  141. </tr>
  142. <tr>
  143. <td><sub>Who's waiting on you, read from every inbox.</sub></td>
  144. <td><sub>A draft in your own voice, checked before it's sent.</sub></td>
  145. </tr>
  146. <tr>
  147. <td width="50%"><img src="hermesPlugin/docs/screenshots/platforms.jpg" alt="log's platform cards: Slack, Instagram and more, each in your own session" /></td>
  148. <td width="50%"><img src="hermesPlugin/docs/screenshots/dashboard.png" alt="The log tab in the Hermes dashboard: who is waiting, every account's session and today's sends" /></td>
  149. </tr>
  150. <tr>
  151. <td><sub>Every platform you're on, each in your own session.</sub></td>
  152. <td><sub>The log tab: who's waiting, every account's session, today's sends against its limit.</sub></td>
  153. </tr>
  154. </table>
  155. ### One capability, every surface
  156. Each thing log can do has one name and works the same way from the CLI, the MCP server and the log console, on every platform. The platform is something you pass in, never a default:
  157. - **Shared tools.** `log chats list`, `log messages read|send|react|watch` and their MCP tools (`chatsList`, `messagesRead`, `messagesSendLive`) work on X, Discord, Slack, Instagram and Facebook, the platform taken from the account.
  158. - **One sign-in.** `log sessions signIn` (MCP: `sessionsSignIn`) opens the account's own browser, you sign in on the platform's login screen, and the session is saved only once the platform shows you signed in. A signed-out browser never overwrites a good session. `log sessions check` answers for every account at once.
  159. - **The log console.** `log console` is the same operations as a terminal console, or as a web console on your own machine with `--web`. Every console screen has a matching command.
  160. - **Views.** `report` draws a view from log's own data, and `browserView` shows an account's live browser in the chat, where the host draws MCP Apps. Elsewhere both come back as text.
  161. - **Machines, not scripts.** Anything that runs over time (sign-in, a session check, each account's watcher, a send, a queue run) is a state machine, so a crash leaves no half-done state behind.
  162. ## How it works
  163. log keeps everything it needs to answer you on your own machine, in one local database, `~/.logCli/log.db`. The platforms push what happens to it as it happens. So when you or your agent asks "what did they say?", log reads its own database in about a millisecond instead of asking the platform again, which takes seconds.
  164. ### The whole picture
  165. ```mermaid
  166. flowchart LR
  167. subgraph platforms["The platforms"]
  168. X["X and X Chat"]
  169. D["Discord"]
  170. S["Slack"]
  171. I["Instagram"]
  172. end
  173. subgraph machine["Your machine"]
  174. H["One session per account<br/>like the platform's own app"]
  175. W["One live watcher per account<br/>holds the platform's push channel"]
  176. DB[("log.db<br/>every event, once")]
  177. V["Derived tables<br/>messages, people, media text,<br/>transcripts, search"]
  178. P["logMcp<br/>reload proxy"]
  179. M["log MCP server"]
  180. K["Hooks<br/>put new messages in front of the agent"]
  181. end
  182. subgraph agents["Your agent"]
  183. C["Claude Code, Codex, Cursor,<br/>Hermes, OpenCode, ChatGPT..."]
  184. end
  185. X & D & S & I -- "push: new message, reaction, media" --> W
  186. W -- "append once" --> DB
  187. DB --> V
  188. C -- "tool call" --> P --> M
  189. M -- "reads in about 1 ms" --> V
  190. M -- "send, react, voice note" --> H --> X & D & S & I
  191. V --> K --> C
  192. ```
  193. In plain words:
  194. 1. **One session per account.** Each account keeps one open session, the same way the platform's own app does. log never opens a new one for each command.
  195. 2. **One watcher per account.** It holds the platform's own push channel (X Chat's socket, Discord's gateway, Slack's socket, Instagram's realtime connection). Everything that arrives is written to `log.db` once, as an event.
  196. 3. **Everything else is worked out from those events.** That covers the chats, who said what, what a picture or video shows, what a voice note said, and the search index. The chats and messages can be rebuilt from the events at any time.
  197. 4. **Your agent asks the database, not the platform.** A tool call reads the database. The platform is only called to send something, or to catch up after a gap.
  198. 5. **Hooks push new things to your agent.** When someone writes, the agent sees it in its context straight away, without asking.
  199. ### How your agent connects, and why you never restart it
  200. ```mermaid
  201. sequenceDiagram
  202. participant C as Claude Code
  203. participant P as logMcp, the reload proxy
  204. participant A as log server, old code
  205. participant B as log server, new code
  206. C->>P: initialize, then tool calls over stdio
  207. P->>A: passes every call through
  208. Note over P: log's code changes on disk
  209. P->>P: waits until no call or job is running
  210. P->>B: starts the new server and replays initialize
  211. B-->>P: ready
  212. P->>A: stops the old server
  213. P-->>C: tools/list_changed
  214. C->>P: next tool call
  215. P->>B: runs on the new code
  216. ```
  217. Claude Code starts `logMcp` once. `logMcp` is a small proxy that never exits, and it runs the real server as a child process. When log's code changes, it waits until nothing is running, starts the new code, and swaps it in. A long job, like a queue sending over an hour, is never cut off. Your agent keeps working without a restart. This design was picked from four open-source options by a SubQ matrix ([`docs/decisions/mcpReload`](docs/decisions/mcpReload)).
  218. ### How the router tells your agent what to do
  219. Each [play](docs/useCases/README.md) is a workflow written step by step, with the words people use to ask for it. The router matches what you typed against every play, so the agent starts from the right steps instead of guessing:
  220. ```mermaid
  221. flowchart TD
  222. ASK["You: who's waiting on me on X?"] --> HOOK{"Does the harness<br/>have a prompt hook?"}
  223. HOOK -- "yes: Claude Code, Codex, Hermes,<br/>OpenCode, Antigravity" --> H["The hook runs the router<br/>on every prompt, by itself"]
  224. HOOK -- "no: Cursor, Claude, ChatGPT, Grok" --> G["The model calls getGuide({ ask })<br/>the same router, on the server"]
  225. H & G --> R["The router<br/>your words against every play's phrases,<br/>plus a meaning score from a local model"]
  226. R -- "clear match" --> M["PLAY MATCH<br/>the play's steps load with<br/>getGuide({ useCase })"]
  227. R -- "near tie" --> T["MAYBE A PLAY<br/>a short menu, nothing loaded"]
  228. R -- "no match" --> N["No play<br/>the agent answers as usual"]
  229. M --> PG["Play gate<br/>only the sends the loaded play names go through"]
  230. PG --> VG["Voice gate<br/>the draft is checked against how you write"]
  231. VG --> LIVE["Sent as you, only with --live<br/>and your approval"]
  232. ```
  233. 1. **The hook runs it for you.** In a harness with a prompt hook, the router runs before the model sees your message, and its answer is added to the turn. In Hermes this is the `logHooks` plugin's `pre_llm_call`.
  234. 2. **Or the model asks.** Everywhere else, the server's instructions and every tool's description tell the model to call `getGuide({ ask: "<your words>" })` first. It's the same router, so the same prompt gets the same play. A golden set of prompts checks that (`src/useCases/router/fixtures/golden.json`).
  235. 3. **Words, then meaning.** Each play lists how people ask for it. The hook's warm context service adds a meaning score from MiniLM, a small model on your machine, in about 12 ms. If the service is down, the hook falls back to the word score, so a play is still named.
  236. 4. **A clear match loads the play. A near tie doesn't.** A clear match names the play and its steps load with `getGuide({ useCase })`. A near tie shows a short menu and loads nothing. Building or fixing log itself is never a play.
  237. 5. **The play gate.** A send only goes through when the play that's loaded names it. An agent can't wander from "read my DMs" into sending.
  238. ### How notifications stream into your agent
  239. Your agent doesn't have to ask what's new. Every account's watcher holds the platform's own push channel, and the hooks put what arrived in front of the agent before its next step:
  240. ```mermaid
  241. sequenceDiagram
  242. participant P as The platform
  243. participant W as Your account's watcher
  244. participant DB as log.db
  245. participant K as Hook
  246. participant A as Your agent
  247. participant S as Your account's session
  248. Note over K,W: a hook starts any signed-in account's watcher that isn't running
  249. P->>W: push: new message, reaction, notification
  250. W->>DB: append the event once, by its id
  251. A->>K: you type, a tool call ends, or (Hermes) a model call starts
  252. K->>DB: what's new since this session last looked?
  253. K-->>A: NEW MESSAGE, who said what and what to do
  254. K-->>A: each account's session, today's limits, X's unread counts
  255. K-->>A: a gap, a refused catch-up, a second watcher refused
  256. A->>DB: claim the chat, so no other agent answers it
  257. A->>DB: read the conversation, about 1 ms
  258. A->>S: send the reply through the one session
  259. S-->>DB: the platform's answer, recorded with the reply
  260. ```
  261. What your agent sees, added to its turn (the handles here are made up):
  262. ```text
  263. log-cli accounts: each one's session (the platform's own answer) and what its governor allowed today:
  264. twitter yourHandle: session loggedIn, 19/500 requests, 0/240 writes today, its one session open
  265. slack yourWorkspace: session loggedIn, 3/500 requests, 0/40 writes today
  266. >>> PLAY MATCH: the prompt matches the log play twitter/dmInbox (Reading the DM inbox: who is waiting on you).
  267. Its steps load with getGuide({ useCase: "twitter/dmInbox" }).
  268. >>> X LIVE: each X account's unread counts right now, from X's own ViewerBadgeCounts:
  269. @yourHandle: 12 notifications, 0 DMs and 0 X Chat unread
  270. !!! GAPOPENED slack yourWorkspace: behind since its watcher restarted; it catches up through its own session, and a send that needs its context waits for that
  271. ```
  272. - **One watcher per account.** It's the only process holding the platform's push channel (X Chat's socket, Discord's gateway, Slack's socket, Instagram's realtime connection). A second one is refused, and you're told.
  273. - **Every session has its own cursor.** Nothing is shown twice, and nothing is missed between turns.
  274. - **Gaps are caught up, never guessed.** When a connection drops, the watcher pulls what it missed through the account's own session, paced like a person. Until it has, a send that needs that context waits. If the platform refuses, the run stops and you're told.
  275. - **Two agents never answer the same chat.** An agent claims a chat before it drafts, and every claim, send and release is written down in `log.db`.
  276. ### Pictures, voice notes and videos
  277. Every model can read text, even one that can't see images. So every piece of media is turned into text when it arrives and kept in `log.db` with one small preview picture. No media file stays on disk.
  278. ```mermaid
  279. flowchart LR
  280. IN["A picture, voice note or video arrives"] --> REC["Kept in log.db: size, length, a small preview"]
  281. REC --> PIC["Picture: what is in it,<br/>its words read out"]
  282. REC --> AUD["Voice note: what was said"]
  283. REC --> VID["Video: cut where the picture changes,<br/>each scene described,<br/>its sound transcribed"]
  284. PIC & AUD & VID --> TXT["One line of text<br/>any model can read"]
  285. TXT --> DEL["The downloaded file is deleted"]
  286. TXT --> VIEW["A model that can see<br/>asks media view for the preview"]
  287. ```
  288. A video with someone talking reads like this:
  289. ```text
  290. [video 0:32, 4 scenes, speech: [0:00-0:08] screen: a whiteboard that says "Q4 plan" | speech: "so this is the plan" · ...]
  291. ```
  292. A video with no sound, like motion graphics, says `no sound` and is told by what changes on screen. This design takes the best part of three open-source systems that a SubQ matrix ranked out of 17 found on GitHub:
  293. - [openclaw](https://github.com/openclaw/openclaw): every piece is turned into text when it arrives, with a fallback when one model fails.
  294. - [screenpipe](https://github.com/screenpipe/screenpipe): the text rows stay and the media goes.
  295. - [RAG-Anything](https://github.com/HKUDS/RAG-Anything): a video is told scene by scene, with the words on screen.
  296. ### The models it uses
  297. Two models run on your own machine, with no key. Four are hosted, and each needs its key:
  298. | Model | Runs | What it does |
  299. |---|---|---|
  300. | all-MiniLM-L6-v2 (23 MB) | your machine | meaning search over every conversation, your voice index, matching what you typed to a play |
  301. | LFM2.5-VL-450M (352 MB) | your machine | describes every picture and video frame as text |
  302. | SubQ `subq-snap-1.1` | hosted, `SUBQ_API_KEY` | the voice gate: does a draft sound like you |
  303. | Jina embeddings v5 and reranker v3.5 | hosted, `JINA_API_KEY` | the AI tells check, and ranking a chat's history for the gate |
  304. | AssemblyAI | hosted, `ASSEMBLYAI_API_KEY` | what was said in a voice note or a video |
  305. | Inworld or Fish Audio | hosted, `INWORLD_API_KEY` or `FISH_API_KEY` | a voice note in your cloned voice, only when you ask |
  306. ```mermaid
  307. flowchart LR
  308. IN["A message arrives"] --> DB[("log.db")]
  309. IN -->|picture or video| VL["LFM2.5-VL, your machine"] --> DB
  310. IN -->|voice| AA["AssemblyAI"] --> DB
  311. DB --> ML["MiniLM, your machine"] --> IDX["search and voice indexes"]
  312. IDX --> DRAFT["your agent drafts"] --> GATE["voice gate: SubQ and Jina"] --> SEND["sent as you"]
  313. ```
  314. **What your machine needs,** measured here on 2026-11-09 (16 threads, CPU only):
  315. - **A 64-bit machine.** There's no GPU: both local models run on the CPU.
  316. - **About 2 GB of free memory.** The picture model peaked at 1.25 GB and takes 6 to 7 s a picture. It stops itself past 4 GB.
  317. - **About 400 MB of disk** for the two models, downloaded the first time they're needed.
  318. - **ffmpeg on your PATH** for videos and voice notes.
  319. **Building the indexes** on a new machine, in this order:
  320. 1. `log search index` reads every conversation once and builds the keyword and meaning indexes.
  321. 2. `log voice index` builds your voice from what step 1 saved.
  322. 3. `log voice aiIndex` builds the AI tells check.
  323. After that, new messages are added as they arrive, and pictures are described as they land.
  324. Each model, its numbers and how each index works: [docs/models.md](docs/models.md).
  325. ### Built on Designing Data-Intensive Applications
  326. The storage follows the ideas in Martin Kleppmann's *Designing Data-Intensive Applications* (DDIA):
  327. | DDIA idea | What it means | Where it is in log |
  328. |---|---|---|
  329. | The system of record | One place holds the truth, written once | the `events` table: every message, reaction and notification, appended once by its id |
  330. | Derived data | Everything else is worked out from the record, and can be rebuilt | chats, messages, people and who did what, checked and rebuilt from the events by `log storage verify` and `log storage rebuild`; media text and transcripts are kept beside them |
  331. | Idempotence | Doing something twice has the same effect as once | an event is stored by its id, a transcript by its audio's hash, a media row by its message and name |
  332. | Fencing | An old process that wakes up late can't overwrite the new one's work | each account's watcher holds a generation number, and a replaced one's writes are refused |
  333. | Big files outside the database | Keep the bytes in a file store and only a small pointer in the database | log goes one step further: it keeps only the text and a small preview, and drops the file |
  334. ### How fast it is
  335. Measured on this project's own `log.db` on 2026-11-08, not estimated:
  336. | What | p50 | p95 | p99 | p99.9 | Measured with |
  337. |---|---|---|---|---|---|
  338. | Read a Discord chat from `log.db` (1,000 reads) | 0.6 ms | 1.1 ms | 1.6 ms | 3.1 ms | `bun scripts/inbox/benchDbRead.ts` |
  339. | Claim a chat so no other agent answers it | 1 ms | 5 ms | 16 ms | 27 ms | `log timing` (79 claims) |
  340. | Lock the account for one call | 0.2 ms | 0.3 ms | 0.4 ms | 0.5 ms | `log timing` (62 calls) |
  341. | Match what you typed to a play (in the warm service) | 12 ms | 36 ms | 47 ms | n/a | `bun scripts/useCases/benchRouter.ts` |
  342. | Read the same Discord chat from Discord itself | 2.3 s | 3.6 s | 5.1 s | 6.0 s | `log timing` (190 reads) |
  343. That last row is why log reads its own database: asking the platform takes thousands of times longer. Sends are slower again, on purpose. Each account keeps human pacing between actions, and a refusal from a platform stops the run.
  344. Every call is timed: `log timing` shows p50, p95 and p99 for every tool and each step inside it, and `log timing --call <id>` shows one call step by step.
  345. ### Why local first
  346. - **Fast.** Your agent reads a conversation in milliseconds, not seconds.
  347. - **Gentle on your accounts.** The platform isn't asked again every time your agent looks something up. One account was disabled after an agent read a server too much, too fast (rule 94), and reading from `log.db` keeps that from happening.
  348. - **Yours.** Your messages, sessions and media text stay on your machine in one file you can back up.
  349. - **Shareable when you need it.** Accounts can live in [Twenty](docs/twenty.md) so several machines share them. A hosted version, with a login per user, is planned.
  350. ## CLI
  351. ```bash
  352. log --help # every command
  353. log <platform> session check --account <a> # is the session still signed in?
  354. log twitter dms --account <a> [--with <handle>] # the inbox, or one person in full
  355. log twitter dm --account <a> --userId <id> --text "<message>" [--live --approvedBy <who>]
  356. log twitter queue build|plan|run # several sends, at random times
  357. log chats list --account <a> # any platform: the account's chats
  358. log messages read --account <a> --chat "<chat>" # any platform: one chat's messages
  359. log sessions check # every account, the platform's own answer
  360. log sessions signIn --account <a> # sign in from the account's own browser
  361. log console [--web] # the local console, in the terminal or the browser
  362. log watchers # each account's one live watcher
  363. log discord read|send --account <a> --channel "<chat>"
  364. log slack read|send --account <a> --channel "<chat>"
  365. log instagram dms|send --account <a>
  366. log voice --to <handle> --text "<draft>" # check a draft against your voice
  367. log search "<query>" # search every conversation
  368. log inbox # claim a chat, see what was done in it
  369. ```
  370. Every command, flag, MCP tool and hook: [docs/reference.md](docs/reference.md).
  371. ## Documentation
  372. The full docs are at **[log.listeningkit.com/docs](https://log.listeningkit.com/docs)**, built from [docs/](docs/README.md):
  373. | Tab | What's in it |
  374. |---|---|
  375. | Get started | [install](docs/install.md), [add your accounts](docs/accounts.md), [connect your agent](docs/mcp.md), [each harness](docs/harnesses/README.md), [using log well](docs/usingLog.md) |
  376. | Use cases | [the plays, step by step](docs/useCases/README.md) |
  377. | Platforms | [X](docs/platformGuides/x.md), [Discord](docs/platformGuides/discord.md), [Slack](docs/platformGuides/slack.md), [Facebook](docs/platformGuides/facebook.md), [Reddit](docs/platformGuides/reddit.md) and [LinkedIn](docs/platformGuides/linkedin.md) |
  378. | Reference | [every command, MCP tool and hook](docs/reference.md), [error codes](docs/errorCatalog.md), [agent guides](docs/guides) |
  379. | How it works | [how log decides what happened](docs/howItWorks.md), [the models it uses](docs/models.md), Twenty, browsers, proxies, each platform's API and the diagrams |
  380. Where each page sits is set in [docs/site.json](docs/site.json), and a commit check refuses a page that isn't placed.
  381. ## Development
  382. ```bash
  383. git clone https://github.com/matthewdonsemail-lab/log
  384. cd log
  385. bun install # also installs the git hooks
  386. bun link # puts this checkout's log and logMcp on your PATH
  387. bun run check
  388. ```
  389. Every commit and push runs the same checks CI does (lefthook): the docs and reference match the code, the naming and layout are right, there are no comments in code, the specs hold, and the tests pass. The rules agents work by are in [AGENTS.md](AGENTS.md).
  390. ## Referral links
  391. Some plays link to services log works with (treg, Memelord, Inworld, Fish Audio), and those links carry ListeningKit's referral or affiliate code (`ref=` or `aff=`). Using them costs nothing extra; drop the code from the address if you'd rather not. Every skill with such a link says so.
  392. ## License
  393. MIT
  394. ## Star history
  395. <a href="https://star-history.com/#matthewdonsemail-lab/log&Date">
  396. <picture>
  397. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=matthewdonsemail-lab/log&type=Date&theme=dark" />
  398. <img src="https://api.star-history.com/svg?repos=matthewdonsemail-lab/log&type=Date" alt="Stargazers of matthewdonsemail-lab/log over time" width="100%" />
  399. </picture>
  400. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

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