Use the official Heptabase plugin to work with your cards, journals, whiteboards, and tag databases from ChatGPT or Codex. You do not need to turn on Developer mode, set up an MCP server, or install the Heptabase CLI.
Install and connect Heptabase
ChatGPT and Codex share the same Plugins Directory:
Open the Plugins Directory in ChatGPT or Codex.
Search for Heptabase and install the plugin.
Sign in to Heptabase, review the permissions, and approve the connection.
Start a new chat or Codex task. Ask the assistant to use Heptabase, or type @Heptabase to select it.
In Codex CLI, enter /plugins to install Heptabase, then start a new session.
The steps may change as OpenAI updates its apps. See OpenAI's plugin guide for the latest instructions.
Get started
Describe what you want, and the assistant uses Heptabase for you. For example:
"Find my cards about Mindstorms, summarize the main ideas, and show me the most relevant cards."
"Append the key takeaways from this discussion to today's journal."
"Save this paper as a PDF card and summarize its first section: https://arxiv.org/pdf/1706.03762"
"Open my 'Mindstorms' whiteboard and group its cards into sections by theme."
After the assistant finds, creates, or edits a card, you can ask it to show the card. Select a card preview to open it, then select Open in Heptabase to continue in the app. Watch the short demo to see it in action.
Open a whiteboard in ChatGPT and Codex
In ChatGPT and the Codex app, the assistant can open one of your whiteboards right inside the chat. You can browse and edit it there, and watch the assistant's changes appear as it works. Ask, for example, "Open my 'Mindstorms' whiteboard." You can switch whiteboards and open cards in it at any time; the assistant checks what you have open before it acts on "this whiteboard" or "this card".
What the plugin can do
Search and read cards, journals, whiteboards, tag databases, PDFs, images, highlights, and backlinks.
Create and edit note cards and journals, including images, videos, audio, and attachments.
Create PDF, image, audio, video, web, and YouTube cards from files or links.
Create and edit tag databases, add or remove cards in them, set card properties, organize tags, and trash or restore cards.
Read and organize your Inbox, and read or set your Space Instructions.
Create whiteboards, sections, connections, and mind maps, and arrange the objects on them.
Show cards in the chat, and open a whiteboard inside ChatGPT and the Codex app.
Whiteboard editing and a few other actions run in the Heptabase app. In ChatGPT and the Codex app, the assistant opens Heptabase inside the chat when it needs to. In Codex CLI, keep the Heptabase desktop app or the web app open and signed in to the same account.
Uploading a file from your computer needs an assistant that can run commands, such as Codex. In ChatGPT, the assistant can save files from links. Codex CLI shows results as text instead of interactive previews.
See the Heptabase MCP tool reference for every supported action.
Permissions and connection issues
What the assistant can do depends on the permissions you grant when you connect. A read-only connection can search and read, but cannot create or edit content.
If the plugin is not working as expected:
Start a new chat or Codex task after installing the plugin.
If the assistant is not using Heptabase, type @Heptabase to select it.
If actions seem missing or outdated, select Refresh in the plugin settings, then start a new chat.
If the assistant cannot find your content, check that you connected the right Heptabase account.
If the connection has expired, reconnect it. If this keeps happening, contact support with the app you use, the time of the error, and the error message.
Never send passwords, API keys, or authorization tokens to Heptabase support.
Other connection methods
To connect another AI service, see Heptabase MCP. For coding agents that work in a terminal next to the Heptabase desktop app, see Heptabase CLI.
If you still need help, contact Heptabase support.