Connect Codex to Threadgehog

Codex can read your Threadgehog projects, draft and edit posts, approve them and send the queue, from the same CLI you already use to code. Connect it once in Settings, Agents, and Threadgehog opens a private server on this Mac that only an agent with your token can reach. Codex is a separate tool with its own ChatGPT plan or API billing; when it asks Threadgehog to write or generate something, that still runs through the AI and image provider you set up in Threadgehog's own Settings. Want Threadgehog to write its drafts with your ChatGPT Plus or Pro plan through Codex? That's a separate setting in Settings > AI; see the ChatGPT plan guide.

How to set up Codex

  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.

    Settings, Agents tab, with Allow agents on this Mac to use Threadgehog turned on

  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.

    The Address and the hidden Token, each with a Copy button, and Regenerate

  4. Connect an agent

    Under "Connect an agent", pick Codex 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 Codex uses it.

    Connect an agent with Codex picked, showing the setup to copy

  5. Add Threadgehog to Codex

    Add this table to ~/.codex/config.toml. tool_timeout_sec matters: Codex cuts off a tool call at 60 seconds by default, and generating ideas can take longer than that.

    [mcp_servers.threadgehog]
command = "/usr/local/bin/threadgehog"
args = ["mcp-stdio"]
tool_timeout_sec = 600

  6. Confirm it's connected

    Run codex mcp list (or codex mcp get threadgehog) in Terminal, or type /mcp inside a Codex session.

    codex mcp list

  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
    The Install the threadgehog command button with Installed next to it

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 Codex. Codex runs on your own ChatGPT plan or OpenAI API billing, separate from Threadgehog; see OpenAI's pricing pages for current Codex plans. Drafts, ideas and images Codex 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. Codex 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 ~/.codex/config.toml is what Codex 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 Codex 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.
  • Codex's default tool timeout is 60 seconds; without tool_timeout_sec = 600 in the config, a slower call such as generating ideas can time out on Codex's side even though Threadgehog is still working on it.

Troubleshooting

"Threadgehog isn't running with agents enabled. Open Threadgehog, then Settings > Agents, and turn on Allow agents."

Why: The threadgehog command found no running server: either Threadgehog is closed, or the Allow agents toggle in Settings, Agents is off. Only the threadgehog command prints this message; Codex shows its own connection error for the same problem.

Fix: Open Threadgehog, go to Settings, Agents, and turn on Allow agents. Keep the app open while you use the agent.

Right after someone clicks Regenerate in Settings, Agents, every Threadgehog call from Codex fails as unauthorized (Threadgehog answers HTTP 401).

Why: Codex is connected through the optional Direct (HTTP) setup and is still sending the old token. The default snippet is not affected. The threadgehog command is not affected, because it reads the current token from the app each time it runs.

Fix: In Settings, Agents, click Copy next to Token, then update your config or snippet with the new value and reconnect.

No Agents tab in Settings.

Why: This Threadgehog version doesn't have agent support yet.

Fix: Open the Threadgehog menu and choose Check for Updates…, install the update, then reopen Settings.

"Only pending posts can be approved; <id> is published."

Why: approve_post only moves a draft still waiting for approval into the queue. This post already moved past pending, so a repeat approval is refused instead of resending it.

Fix: Check the post's current status with get_post or list_pending before approving it again.

"Unknown tool: <name>"

Why: The agent called a tool name that isn't one of Threadgehog's supported tools, for example a misspelled or made-up name.

Fix: Reconnect the agent, or restart the session, so it reloads the current tool list.

A tool call such as generate_ideas times out around 60 seconds even though Threadgehog is still working.

Why: Codex's default tool_timeout_sec is 60 seconds, shorter than some Threadgehog calls can take.

Fix: Add tool_timeout_sec = 600 under [mcp_servers.threadgehog] in ~/.codex/config.toml, as shown above, then reconnect.

Questions

Do I need to turn on Agents to use Threadgehog normally?

No. Agents are optional. Everything in Threadgehog still works from its own buttons with Agents off; turning it on adds a way for Codex, or another MCP client you connect, to drive the same actions.

Can Threadgehog write its drafts with my ChatGPT plan through Codex?

Yes, from Threadgehog 1.1. That's set in Settings > AI, not here: pick Use my Claude or ChatGPT subscription, then ChatGPT subscription (Plus or Pro). You don't need Agents turned on for it. The ChatGPT plan guide has the steps.

Can Codex answer questions about how Threadgehog works?

Yes, in Threadgehog 1.0.4 or later. Ask Codex something like "how do I connect Buffer" and it looks the answer up in the help built into your copy of Threadgehog. When something isn't working, it also checks your app's live status, such as a scheduler or AI key that stopped working or posts waiting on a setting. That help ships inside the app and is updated with every release. It runs on Codex, so nothing extra is sent to Threadgehog.

Does connecting Codex cost anything extra in Threadgehog?

No, Threadgehog doesn't charge anything extra to connect an agent. Codex is a separate tool with its own plan, though. When it asks Threadgehog to draft text, generate ideas or make an image, that still runs through the AI provider and image provider set up in Threadgehog's own Settings, billed the same way a click in the app would be.

Can Codex publish to Threads or X directly?

No. Codex can approve a post into Threadgehog's queue and tell Threadgehog to send the queue now, but Threadgehog only publishes through the scheduler you've connected under Settings, Publishing, or not at all if you use Export only. Codex never talks to Threads or X directly.

Can Codex send posts without me clicking anything in Threadgehog?

Yes. approve_post moves a pending draft into the queue without a click, and those posts go out on your send schedule. For an agent to send right away with send_queue_now, turn on Let agents send posts in Settings, Agents (it starts off). Click Regenerate there any time to cut a connected agent off.

Will this work with ChatGPT, Manus or Perplexity's Computer agent?

Threadgehog connects to agents that run on your Mac: Claude Code, Codex, Cursor, Claude Desktop or Gemini CLI.

What happens if I close Threadgehog while Codex is connected?

Every call fails until you reopen Threadgehog with Agents still turned on. The threadgehog command line shows "Threadgehog isn't running with agents enabled..." in that case, and Codex will see a similar connection error.

Why does a slow call fail in Codex but work from the threadgehog command line?

Codex cuts off a tool call after tool_timeout_sec, 60 seconds by default, while the threadgehog command line waits up to 10 minutes for a reply. Add tool_timeout_sec = 600 to the [mcp_servers.threadgehog] entry in ~/.codex/config.toml, as shown above, to match.

Other guides