Connect Gemini CLI to Threadgehog

How to set up Gemini CLI

1. Open Settings, Agents

   In Threadgehog, press Cmd+, (or Threadgehog menu, Settings), then click the Agents tab. It sits right after Publishing.

2. Turn on agents

   Switch on "Allow agents on this Mac to use Threadgehog". This starts a private server on this Mac only, at 127.0.0.1. Agents can read your projects, write and edit drafts, approve posts and send the queue. They use the same AI provider, image provider and scheduler as the buttons in the app; nothing else leaves your Mac. The line under it adds that your agent can also answer questions about Threadgehog, using the help built into this version and your app's live status.

   

3. Copy the address and token

   With agents on, the tab shows Address (http://127.0.0.1:47331/mcp, or another port if 47331 is taken) and a masked Token. You need these only for the optional Direct (HTTP) setup; the snippet in the next step reads them itself. Regenerate issues a new token if you ever need one; a Direct (HTTP) connection will need the new value.

   

4. Connect an agent

   Under "Connect an agent", pick Gemini CLI from the list. Threadgehog fills in a ready-made snippet that starts the threadgehog command (no token goes in your config), plus a Copy button and a Setup guide link to this page. Threadgehog must stay open while Gemini CLI uses it.

   

5. Add Threadgehog to Gemini CLI

   Add this to ~/.gemini/settings.json. If you use the optional Direct (HTTP) setup instead, use httpUrl, not url: that's the key Gemini CLI expects for a local streamable HTTP server.

   {
     "mcpServers": {
       "threadgehog": {
         "command": "/usr/local/bin/threadgehog",
         "args": ["mcp-stdio"]
       }
     }
   }

6. Confirm it's connected

   Start a Gemini CLI session and type /mcp. threadgehog should show as CONNECTED with its tools listed.

   /mcp

7. Optional: install the threadgehog command

   Still in Settings, Agents, click "Install the threadgehog command". It asks for your Mac password once and creates /usr/local/bin/threadgehog. If you'd rather run it yourself, click Copy fallback for the exact command for your Mac. Once installed, threadgehog status checks the connection, threadgehog mcp prints the address, header and the Claude Code, Codex and Cursor snippets, and threadgehog help answers a question from the help built into the app.

   sudo mkdir -p /usr/local/bin && sudo ln -sf "<helper path>" /usr/local/bin/threadgehog
   threadgehog status
   threadgehog mcp
   threadgehog help how do I connect Buffer

   

What you get

• List your projects and their publishing settings
• Check your writing plan and how much capacity is left
• List posts waiting for approval in a project
• List posts waiting in the publishing queue, for one project or all of them
• Get one post by ID to see its full text and status
• Generate new draft post ideas for a project
• Write post text from a prompt without saving it, so you can review it first
• Save text you already wrote as a new draft
• Replace a post's text
• Revise a post's wording from feedback, keeping its idea
• Approve a pending draft into the publishing queue
• Reject a pending or queued post
• Attach a local image or video file to a post (png, jpg, gif, webp, mp4 or mov)
• Generate an image for a post
• Set the order of posts waiting in the queue
• Send eligible queued posts right now, once Let agents send posts is on in Settings, Agents
• Check the app's live status: version, plan, AI and image providers, connected schedulers, queue counts and anything that needs attention
• Answer how-to, setup and troubleshooting questions about Threadgehog from the help built into your version

What it costs

Threadgehog doesn't charge anything extra to connect Gemini CLI. Gemini CLI itself is free and open source; it runs on your own Google account's free tier or on paid API billing, separate from Threadgehog, depending on how you sign in. Drafts, ideas and images Gemini CLI asks Threadgehog for still use the AI provider and image provider you've set up in Threadgehog's own Settings, and are billed the same way a click in the app would be.

Your key and your data

Threadgehog's agent server only listens on 127.0.0.1, this Mac, on the port shown in Settings, Agents (47331 by default, or another free port if that one is taken). Every request needs the bearer token from that tab, and a request with the wrong Origin header is refused too. Gemini CLI connects to that address directly over HTTP, since it runs on this Mac already. Threadgehog stores the token in the macOS Keychain, and also writes it with the port to ~/Library/Application Support/Threadgehog Public/agent.json (readable only by your Mac user account) so the threadgehog command can find the server. That file stays on disk, even after you quit Threadgehog, until you turn Allow agents off. The copy you paste into ~/.gemini/settings.json is what Gemini CLI uses to authenticate, so treat that file like it holds a password. Click Regenerate in Settings, Agents any time to issue a new token, which immediately invalidates the old one everywhere it was used. Agent calls run entirely between Gemini CLI and Threadgehog on your Mac, through the same AI provider, image provider and scheduler you already configured; Threadgehog's own servers never see this traffic, and no keys or tokens are ever returned to an agent.

Limits to know

• Works only on this Mac: the server listens on 127.0.0.1, so no other device can reach it.
• Threadgehog must be open with Agents turned on in Settings, Agents, or every call fails.
• Works with agents that run on your Mac: Claude Code, Codex, Cursor, Claude Desktop and Gemini CLI.
• approve_post only works on posts still pending, and reject_post only on posts pending or queued; neither can touch a post that already published.
• Media attachments must already exist under your home folder, as png, jpg, gif, webp, mp4 or mov files.

Troubleshooting

Questions

Links

• Gemini CLI MCP server docs
• Gemini CLI on GitHub
• Threadgehog support

Other guides

• Claude Code
• Codex
• Cursor
• Claude Desktop
• All integrations