toolbase

The package manager for AI agent toolkits. Install toolkits into isolated environments, curate which tools your agent sees, and serve them to your harness over the Model Context Protocol. Toolkits span any domain, from web and data utilities to scientific categories like astro, hep, and quantum.

A toolkit is the publishable unit. It bundles tools an agent can call and/or skills — short markdown how-to guides surfaced into your harness. Each toolkit installs into its own isolated Python environment, so dependency conflicts between toolkits are never a problem. A toolkit can even ship only skills (a skill pack).

Install toolbase

pip install toolbase     # Python 3.12+

Arm your agent

The loop is install → activate → connect. tb is a short alias for toolbase; both ship with the package and behave identically.

tb install calculator             # download into an isolated environment
tb activate calculator            # expose it to the agent
tb connect claude-code            # write toolbase into Claude Code's MCP config

Now launch your harness (e.g. claude for Claude Code) — or, in an already-running session, reconnect the toolbase MCP server. The tools appear as calculator__add, calculator__multiply, etc. tb install calculator -a installs and activates in one step.

Install ≠ activate. Installing places a toolkit in the global cache but serves nothing — activation is what exposes it to the agent. The binary always lives in the shared cache (~/.toolbase/cache/); only the activation is scoped: tb activate writes to the current directory's .toolbase/ by default, -u writes to the user-wide loadout instead.

tb connect writes the MCP config for you. Claude Code, Codex, OpenCode, Antigravity, and Orchestral are all supported (tb connect --harnesses lists them); the first four are MCP clients (tb connect edits their config file), while Orchestral gets a runnable agent script you launch yourself. It also surfaces the activated toolkits' skills into the harness — see Skills.

Inspect

tb list              # installed toolkits, ✓ active / ✗ inactive
tb list -v           # per-tool view with bundle + config-gating annotations
tb logs              # tool calls, live (best diagnostic for "did it fire?")

Curate what the agent sees

tb activate / deactivate work at four granularities:

tb activate calculator                # the whole toolkit
tb activate calculator/scientific     # one bundle (group of related tools)
tb activate calculator__add           # one specific tool
tb deactivate calculator__quickstart  # one specific skill (see Skills below)

A <toolkit>__<name> item is a skill when it matches a surfaced skill and not a tool; otherwise it's a tool (a name that is both resolves to the tool). A bundle is a self-contained capability an author carves out of a toolkit, with its own deps and skills. tb loadout tools calculator lists what's available. Power users can keep several named loadouts (tb loadout create paper, tb connect claude-code --loadout paper) and switch between them; most users only ever touch the default loadout.

Tools are served namespaced as <toolkit>__<tool> by default, so two active toolkits that both define, say, an add tool stay distinct (calculator__add vs matrix__add). When names do overlap, tb serve, tb list -v, and tb install flag it so it's never a surprise. Prefer bare names? tb serve --bare (or default.bare: true in serve.yaml) advertises the plain <tool>; a name shared by two toolkits stays qualified (both remain callable) with a warning, and the rest are served bare.

Skills: guides that travel with the toolkit

A toolkit can ship skills — markdown how-to guides in skills/ — alongside its tools or on their own. Each is either a file (skills/exact_math.md) or a directory (skills/exact_math/SKILL.md) that carries reference files and scripts beside the guide. tb connect surfaces the activated toolkits' skills into the harness you connect, in that harness's native format and at the scope you connected:

All four load these on demand as native skills, keyed on the description in each guide's frontmatter, and expose each as a /<toolkit>__<skill> slash command. Codex loads a project's skills even before you trust the project — unlike the config.toml beside them.

The surfaced guide is named <toolkit>__<skill> in the harness whatever the author called it, so what you see is what tb deactivate accepts and two toolkits shipping an mg5 guide stay distinct. The slug is lowercase with words separated by -, matching every other skill in the ecosystem: skills/run_cards.md, skills/run-cards/, and skills/Run Cards.md all surface as <toolkit>__run-cards. The author's description is passed through untouched — it's what the model reads to decide when the skill applies.

Skills go where the server entry goes, so a tool and its guide reach the same agents. Every harness reads both scopes at once, so a project connect adds to whatever you surfaced with -u; tb connect says so when the other scope is holding skills.

Skills follow the same curation as tools: a guide is surfaced only when its toolkit is active, and you toggle a single one with the activation grammar.

tb deactivate calculator__advanced_guide   # stop surfacing this one guide
tb activate   calculator__advanced_guide   # bring it back

A connect is a sync, not an append. It writes what should be there and removes the toolbase-owned entries that shouldn't — a toolkit you deactivated, a guide you toggled off, a bundle whose config gate closed, a guide a new version dropped. Skills you wrote yourself are never touched. Re-run tb connect <harness> after changing what's active and the surface catches up.

tb connect --no-skills wires the MCP server without touching the skill surface in either direction; tb disconnect removes the surfaced skills for that scope (--all for both). Surfacing is a connect-time step, so tb install alone reports a toolkit's skills but doesn't surface them — connect (and the set you've activated) decides what lands in the harness.

A toolkit that ships only skills is a skill pack: it declares no tools and serves nothing over MCP, but its guides surface through tb connect exactly like any other toolkit's.

Share a project without sharing your machine

Toolkits that need configuration (an API key, a path to an external binary) read it from three layers, later winning key-by-key:

tb config set calculator precision 10                  # committed
tb config set calculator solver_path /opt/bin --private  # yours alone

Toolkit versions split the same way, via tb use, and they live in the loadout beside the tool selection — so one file says both which tools an agent gets and which build of them. -p writes the committed loadouts/default.yaml, --private the gitignored default.local.yaml. tb install writes neither: it only fills the shared cache, and without a pin the newest installed version serves.

Authoring a toolkit

tb init my-toolkit             # scaffold from template
cd my-toolkit
# write tools in tools/ and skills in skills/
# (a toolkit may ship only skills — a skill pack — and omit tools entirely)
tb validate                    # check structure
tb login                       # one-time browser-flow auth
tb publish                     # ship it (auto-registers on first run)

Iterating locally. Develop a toolkit's code without a publish→install round-trip by installing it editable:

cd my-toolkit
tb install -e . -a             # live symlink to this source dir, and activate

Edits to your tool source appear on the next serve; rerun tb install -e . to rebuild the env when dependencies change.

If a published version of the same toolkit is also installed, that one keeps serving until you say otherwise — -e links the checkout without selecting it, because the cache is shared by every directory on your machine. tb use my-toolkit@editable opts in where you're working; install tells you when this applies.

For the full author guide — tool conventions, skills, bundles, configuration, setup.py — see https://toolbase-ai.com/docs/authoring. For the agent-assisted authoring flow (recommended for first toolkits), see https://toolbase-ai.com/docs/scaffold-with-an-agent.

Commands

Full reference with all flags: https://toolbase-ai.com/docs/reference/commands.

See CHANGELOG.md for the full release history.

Architecture

Three pieces:

• CLI (this package) — installed locally, manages toolkit environments and serves tools.
• Backend (api.scitoolkit.org) — registry, auth, tarball storage.
• Website (toolbase-ai.com) — discover and manage published toolkits.

Each installed toolkit runs in its own subprocess in its own Python environment. toolbase serve aggregates them and exposes the union as a single MCP server upstream; failures in one toolkit don't affect others.

Contributing

Issues and PRs are welcome at https://github.com/alexr314/toolbase.

License

MIT. See LICENSE.

Links

• Website: https://toolbase-ai.com
• Docs: https://toolbase-ai.com/docs
• Backend API: https://api.scitoolkit.org
• GitHub: https://github.com/alexr314/toolbase
• Issues: https://github.com/alexr314/toolbase/issues