Development Workflow
The complete development loop: link, configure, test, iterate. Every command explained.
Quick reminder
A Kazibee plugin is a TypeScript module that exports a main(env) function returning an object of methods. Each method becomes a tool that AI agents can call. During development, you link your local directory so Kazibee loads your code directly — no publishing required.
The development loop
Building a plugin is an iterative cycle. You do not need to publish anything to test your code. The typical flow looks like this:
Link your local directory so Kazibee can find it
Verify that Kazibee loaded your plugin correctly
Configure environment variables (API keys, credentials)
Preview what AI agents will see (your LLM documentation)
Test your methods in the sandbox
Test your CLI commands
Inspect install path, type, and env vars
Let's walk through each step. You will repeat steps 2–5 frequently as you write code.
Step 1 — Link your plugin for local development
Before Kazibee can load your plugin, it needs to know where the code lives. The kazibee link command creates a symlink from Kazibee's internal registry to your local project directory. Think of it like npm link — it tells the system "this plugin lives here, load it from this folder."
This is different from kazibee install, which clones a plugin from GitHub for production use. During development, you always want link because it points to your live working directory — every code change is picked up immediately without reinstalling.
dev@local:~/workspace $ kazibee link my-plugin ./my-plugin
# Creates a symlink: Kazibee now loads from ./my-plugin
# If your plugin has permissions.json, you'll be prompted to grant variables
The first argument is the name you want to register (this is how you will refer to it in all future commands). The second argument is the path to your plugin directory.
Step 2 — Verify it loaded correctly
After linking, run kazibee show to confirm Kazibee can actually load your plugin. This command reads your entry point, executes main(), and prints back the methods it found, along with their parameter types and return types.
This is your first sanity check. If something is wrong with your export, your types, or your package.json configuration, this is where you will find out.
dev@local:~/workspace $ kazibee show my-plugin
# Prints your plugin's methods, parameter types, and return types
# Example output:
hello(name: string) => Promise<string>
If you see your methods listed, your plugin is loading correctly. Run this again after every change to your method signatures to verify the types are what you expect.
Step 3 — Set environment variables
If your plugin connects to external services (APIs, databases, etc.), it needs credentials. Plugins run inside a sandbox and cannot access process.env directly — Kazibee injects only the specific variables you declared in permissions.json and that the user has granted.
Use kazibee env --set to provide those values. Think of this as setting secrets for your plugin — Kazibee stores them securely and passes them to main(env) at runtime.
dev@local:~/workspace $ kazibee env my-plugin --set API_KEY=sk-your-key
# You can set multiple variables at once:
dev@local:~/workspace $ kazibee env my-plugin --set CLIENT_ID=xxx CLIENT_SECRET=yyy
You only need to do this once per variable. The values persist across sessions. To check what is currently set, run kazibee env my-plugin without the --set flag. For a deeper explanation of how credentials flow through the system, see the Authentication page.
Step 4 — Preview LLM documentation
AI agents do not read your source code. They read a generated document called llm.txt that describes your plugin's methods, parameters, and usage examples. The kazibee llm command shows you exactly what an AI agent will see when it tries to use your plugin.
This matters because if the documentation is unclear, the AI will call your methods incorrectly. Review this output and ask yourself: "Would someone who has never seen my code understand how to use these methods?" If not, improve your llm.txt file (see LLM Instructions).
dev@local:~/workspace $ kazibee llm my-plugin
# Prints the full LLM documentation that AI agents receive
# Includes: method signatures, descriptions, and usage examples
Step 5 — Test in the sandbox
The kazibee exec command runs code inside the exact same sandbox environment that AI agents use. This is important because the sandbox has restrictions (no process.env, no filesystem access) that might cause code to behave differently than it would in a normal Node.js process.
Pipe in a JavaScript expression that calls your plugin's methods. The expression has access to a tools object where each key is a registered plugin name and the value is the object returned by that plugin's main().
dev@local:~/workspace $ echo 'return await tools["my-plugin"].hello("world")' | kazibee exec
"Hello, world!"
If the method returns data, it will be printed as JSON. If it throws an error, you will see the full stack trace. This is the fastest way to verify your plugin works end-to-end — from loading, through credential injection, to actual execution.
Step 6 — Test CLI commands
If your plugin exports functions from command.ts (like login, setup, or any custom commands), you can run them directly. Unlike sandbox methods, CLI commands run on the host machine with full access — they can open browsers, read files, and interact with the terminal.
The syntax is kazibee <plugin-name> <command>. Kazibee looks up the named export in your command.ts file and calls it.
dev@local:~/workspace $ kazibee my-plugin login
# Runs the "login" export from your command.ts
# Commands run on the host machine, not in the sandbox
Step 7 — Check plugin info
The kazibee info command shows you metadata about a registered plugin: where it is installed, whether it is linked or installed from GitHub, and what environment variables are currently configured.
This is useful for debugging — especially when you are not sure if Kazibee is loading the right directory, or if you want to double-check which env vars are set.
dev@local:~/workspace $ kazibee info my-plugin
# Shows: install path, type (linked/installed), env vars
Troubleshooting
If something is not working, start here. These are the most common issues developers hit during the dev loop.
Plugin not loading?
Check the "main" field in your package.json. It must point to your entry file (e.g. "./src/index.ts"). Also make sure "type" is set to "module". Run kazibee info my-plugin to verify the path Kazibee is using.
Methods not showing up in kazibee show?
Make sure your index.ts has a export default function main() that returns an object. Each property on that object becomes a method. If you are using named exports instead of a default export, Kazibee will not find your methods.
Auth not working?
Run kazibee env my-plugin to see what variables are currently set. If a variable is missing, use kazibee env my-plugin --set KEY=value to add it. Also check that your permissions.json declares the variable and that package.json points to permissions.json via the "kazibee.permissions" field.
Changes not taking effect?
If you linked your plugin, code changes should be picked up automatically. If they are not, try unlinking and re-linking: kazibee unlink my-plugin then kazibee link my-plugin ./my-plugin.