Claude Code plugin

The Hilbana plugin for Claude Code is the shortest path to working with Hilbana from your own repository: a single install wires up the MCP server, per-project memory, per-task token accounting and the cycle commands (/hilbana-claim-next, /hilbana-finish, …).

It installs from its public marketplace: github.com/hilbana/claude-plugin. If you’d rather have the why before the how, we wrote it up on the blog: your agents stop starting from scratch.

Which route you want

There are three ways to connect Hilbana with Claude, and they don’t compete: each one is for a different place.

• Plugin (this page): for Claude Code, working inside your repo. It’s the only route that brings automatic memory, cycle commands and spend measurement.
• Connector: for claude.ai (web and desktop), OAuth, no keys to manage. For reading and operating it yourself.
• API key: for your own agents and services or headless / CI setups, where you register the MCP by hand with a Bearer hil_….

Requirements

• Claude Code installed.
• Node 18+ on your PATH. The hooks run under node, and the session-close one uses the global fetch (available from Node 18 on). Without Node the hooks simply don’t run: your session works the same, but you lose automatic memory and token accounting.

Language note: the plugin’s commands and skills are written in Spanish. Claude reads them fine and answers in whatever language you use, so it doesn’t change how you work, but expect Spanish prose if you open the files to edit them.

Install

In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add hilbana/claude-plugin
/plugin install hilbana@hilbana

Then restart Claude Code (or run /reload-plugins).

Configuration

On install, Claude Code asks you for two things:

• api_key (required): create it under Settings → API keys in any workspace you belong to. The format is hil_…. The key identifies you: it reaches all of your workspaces, and that one is just the default — the one used when a call doesn’t say otherwise (see API & MCP). It’s stored only in your local configuration and marked as sensitive.
• base_url (optional): leave it empty to use https://app.hilbana.com. You only need it if you self-host, and it goes without a trailing /mcp (the plugin appends that itself).

What you get

MCP server auto-registered. No claude mcp add needed: the plugin declares the server and authenticates it with your key.

Per-project memory. A SessionStart hook reminds the agent to load prior context when you open the repo, and a SessionEnd one saves a summary on close. The scope is the repo folder’s name, so it works in any repo, not just those tracked as projects in Hilbana. See Agent memory.

Per-task token accounting. The Stop and SessionEnd hooks compute real spend by reading the transcript and report it on their own. The server bills it to whichever issue the agent has claimed at that moment; with no claim it’s recorded as unattributed. Having the hook measure it rather than the agent is deliberate: a model doesn’t know what it consumes, and if you ask, it makes the number up.

Cycle commands. They implement the pull model of the workflow framework: the tracker is the queue and the worker pulls from it.

Command	What it’s for
/hilbana-claim-next	Pull the next agent-ready issue and start it.
/hilbana-finish	Close your turn at In Review, with verification, telemetry and memory.
/hilbana-review	Review what’s In Review: approve to Done or send it back.
/hilbana-plan	Compile a goal into a graph of sub-issues and queue the frontier.
/hilbana-trabajar-issue	Work one specific issue end to end.
/hilbana-crear-docs	Bootstrap a project’s docs from your repo.
/hilbana-memoria-switch	Move your agent memory from engram to Hilbana.

Rule of the cycle: a worker never closes its own work to Done, it stops at In Review. Whoever reviews is who closes.

Skills. hilbana-memoria (the memory protocol) and hilbana-mcp (the MCP tools and the queue flows). You don’t invoke them: they load themselves when relevant.

Verify it works

1. /plugin list → hilbana shows as enabled.
2. In a fresh session, check that the memory tools exist. Installed as a plugin they carry the namespaced prefix: mcp__plugin_hilbana_hilbana__mem_*.
3. Smoke test: ask it to “load the memory context”. The agent should call mem_context with the current repo’s scope.

Updating

Versions ship as repository releases. Claude Code doesn’t notify you on its own: it only surfaces an update when you open /plugin. To hear about them, set the repo to Watch → Custom → Releases.

/plugin marketplace update hilbana
/plugin install hilbana@hilbana

Then restart Claude Code.

Common problems

The plugin doesn’t show up. Almost always a missing restart after installing, or the marketplace wasn’t added (repeat /plugin marketplace add).

The tools can’t see your issues. Listing tools use the key’s default workspace. If the issues live in another one you belong to, pass workspaceId (get it from list_workspaces) or use a key created in that workspace. If you’re not a member, there’s nothing to configure: someone has to invite you.

The MCP won’t connect. Check that base_url has no trailing /mcp. The plugin appends it, so https://app.hilbana.com/mcp ends up duplicated.

No memory saved and no spend recorded. Node 18+ is missing from your PATH. The hooks fail silently by design, so they never break your session.

Related: Prompts · Connect with Claude · API & MCP · Agents · Agent memory.