hbedit

hbedit

Unofficial. Not made by or affiliated with Heptabase. Built entirely on top of the official heptabase CLI — it never touches Heptabase's database, storage, or internal files.

📖 繁體中文 README →

What it is

hbedit lets you (or an AI agent) edit an existing Heptabase card as if it were a plain markdown file — pull it down, edit it, push it back. Same card, same ID, links into it stay intact.

The simplest case: you want to ask Claude to fix a typo or reorder the sections of a card you already have. The official heptabase CLI can create cards and append to them, but it can't rewrite the middle of an existing one from plain text. That gap is the entire reason hbedit exists.

If all you want is to make a new card or add one line at the bottom, just use the official CLI directly — it's simpler.

How the rewrite actually works (scratch-card trick, conflict guard, per-machine cache) is in Architecture below.

Install

You need:

• Python 3.9+ (stdlib only — no pip deps)
• The Heptabase desktop app, v1.91.0 or newer, running
• The official heptabase CLI enabled inside the app at Settings → AI Features → CLI (it ships with the desktop app — not npm, not brew). macOS adds it to PATH automatically; Windows users get a one-time PATH-setup command from the app. Full steps: https://support.heptabase.com/en/articles/14715462-how-to-use-heptabase-cli

Then pick your agent:

Claude Code (two lines, inside Claude):

/plugin marketplace add davidleitw/hbedit
/plugin install hbedit@hbedit

Codex CLI (one line):

curl -fsSL https://raw.githubusercontent.com/davidleitw/hbedit/master/install.sh | sh -s codex

opencode (one line):

curl -fsSL https://raw.githubusercontent.com/davidleitw/hbedit/master/install.sh | sh -s opencode

Verify in a new shell:

hb doctor

"status": "ok" means you're set. Anything else, follow the detail field (usually: install heptabase CLI, update it to 0.3.x, or launch the desktop app). Manual install steps and curl | sh audit instructions are in INSTALL.md.

How to use it

You don't run hbedit commands directly — just talk to your agent in plain language. The skill recognizes when it should kick in. Here are the scenarios it handles:

1. Edit an existing card

The main case. You have a card and want to change something inside it.

"In my React Hooks card, useEffec is a typo — fix it to useEffect, and reorder the sections so useState comes first."

The agent runs hb pull to fetch the card as markdown, edits the file locally, then hb push to send it back. The original card's block IDs are preserved, so anything linking to that card still points at the right place.

2. Start tracking a local markdown file

You wrote some markdown in your vault and want it to live as a Heptabase card you'll keep editing.

"I just added notes/rust-ownership.md to this vault — push it to Heptabase, I'll keep editing it from here."

The agent runs hb push, which creates a new card and records the path → cardId binding in .hbedit/state.json. From then on you edit the local .md and hb push to sync.

3. Pick up editing on another machine (after git clone)

You committed .hbedit/state.json to git on machine A. On machine B you clone the repo — the bindings come with the clone, but the per-machine sync cache doesn't.

"Just cloned this repo on my laptop, I want to keep editing docs/mm.md."

The agent runs hb pull docs/mm.md (single-arg "smart sync" form). If the local file matches what's on Heptabase, you get baseline-established and can start editing. If it diverged, you get a conflict with the remote version dropped to docs/mm.conflict.md for you to reconcile — your local copy is never silently overwritten.

4. Change tags on a card without disturbing others

"Add algorithm and hashmap tags to my Two Sum card."

The agent runs hb tag add. Existing tags on the card stay exactly where they are.

5. Just dump a card, no tracking needed

The escape hatch — when you want a one-off card and don't want hbedit to get involved.

"Just dump today's meeting notes into a new Heptabase card — don't track it, fire and forget."

The skill steps aside and the agent uses the base heptabase note create instead. No state.json entry, no per-machine cache, no cleanup needed.

Architecture & how it works

It's an Agent Skill

hbedit ships as a Claude Code plugin / Agent Skill. The skill manifest (SKILL.md) tells your agent when to use it and how; behind that is a Python CLI called hb. No daemon, no server — just a stdlib-only Python script that shells out to the official heptabase CLI.

The vault model

Run hb init in a directory and that directory becomes a vault. Vault state is deliberately split into two pieces: