Hilbana + Claude Code
Connect Claude Code to Hilbana: the plugin or a plain MCP connection, how to check it works and your first work loop.
Hilbana + Claude Code
Two ways to connect Claude Code to Hilbana. Pick one; you don’t need both.
| Plugin (recommended) | Plain MCP | |
|---|---|---|
| What you get | The MCP server, persistent memory with automatic hooks, per-task token accounting, and the /hilbana:… commands |
The MCP server and its tools, nothing else |
| Setup | Two commands + an API key | One command |
| Best for | Working daily with agents on a team’s board | Trying Hilbana, or a client other than Claude Code |
Option A · The plugin
Requires Node 18+ on your PATH (the hooks run under node; without it they
simply don’t run and your session is unaffected).
-
Create an API key in Hilbana: Settings → API keys, in the workspace you work in. The tools and the memory operate on that key’s workspace, so a key from the wrong workspace lands your work in the wrong place. Keys look like
hil_…. -
Install, inside Claude Code:
/plugin marketplace add hilbana/claude-plugin /plugin install hilbana@hilbana -
When asked, paste the API key. Leave base URL empty unless you self-host.
-
Restart Claude Code.
Check that it works
- Run
/mcp: you should see a server namedplugin_hilbana_hilbanaas connected. - Type
/hilbana:and the commands appear (claim-next,finish,plan, …). - Open a repo and ask: “What do you know about this project from memory?” The
SessionStarthook has already told the agent to load it withmem_context.
Your first loop
/hilbana:plan <a goal in plain text> → issues with definitions of done
/hilbana:claim-next → an agent takes the next ready issue
… the agent works …
/hilbana:finish → verifies, leaves it in review, saves memory
/hilbana:review → you (or another agent) approve or send back
Each step is explained in REFERENCE.md. Starter prompts you can paste are in prompts.
Option B · Plain MCP, with OAuth
No plugin, no API key to copy. Claude Code opens a browser window and you approve the connection (OAuth with dynamic client registration):
claude mcp add --transport http hilbana https://app.hilbana.com/mcp
Then run /mcp inside Claude Code and authenticate the hilbana server.
If you’d rather use an API key (for a CI job, say):
claude mcp add --transport http hilbana https://app.hilbana.com/mcp \
--header "Authorization: Bearer hil_your_key_here"
Never commit a key. Keep it in your local Claude Code configuration, not in the repo.
Memory, in one minute
Memory is organised by scope = the name of the repo folder and shared by everyone
in the workspace. The agent saves decisions, fixed bugs (with their root cause),
conventions and gotchas with mem_save, and loads them again in the next session with
mem_context. See examples/memory for what a good memory looks
like.
Troubleshooting
- The commands don’t appear. Restart Claude Code, or run
/reload-plugins. 401or “invalid credential”. The key is incomplete, revoked or expired. Create a new one and paste it whole; it is shown only once.- The agent’s work shows up in the wrong workspace. The key belongs to another workspace. Create one in the right one.
- Hooks do nothing. Check
node --versionis 18 or higher.
More: Claude Code plugin docs · MCP and API.
Want to try it? Start for free: 14 days of Pro when you sign up, no card.
Related: Hilbana + Claude Code · Hilbana + Beads · Hilbana + engram · Agent memory · Claude Code plugin.