# KaibanJS: a Kanban board for agents whose own quick-start example ends mid-identifier

> A JavaScript framework for multi-agent teams with a board UI, a programmatic API, and a documentation example that stops on a half-typed catch call, a client-side environment variable for the API key, and a manifest sitting one patch ahead of the newest release tag.

**kaiban-ai/KaibanJS** — KaibanJS is a JavaScript-native framework for building and managing multi-agent systems  with a Kanban-inspired approach.

- Repository: https://github.com/kaiban-ai/KaibanJS
- Website: https://www.kaibanjs.com/
- Stars: 1,479 · Forks: 159
- Language: TypeScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/kaiban-ai-kaibanjs

## The shipped basic example ends on a half-typed method

The manual usage section is the part most people copy, and the block in it is incomplete. It defines an agent with a name, a role and a goal, creates a task with a description and that agent, builds a team from the two plus an environment object holding the key, and then starts the workflow. The promise chain ends like this:

```js
team
  .start()
  .then((output) => {
    console.log('Workflow completed:', output.result);
  })
  .cat
```

That last line is not valid JavaScript. A catch handler was clearly intended and the text stops partway through the property name, so anyone pasting the example gets a syntax error on the last line of the snippet. The fix is obvious once you see it, but the fact that the canonical example in the documentation is broken is worth knowing before you conclude your setup is at fault.

Everything above that line is coherent and shows the intended shape: agents and tasks are constructed independently, then assembled into a team that owns the run.

## Two ways to pass the key, and one of them is a client-side variable

There are two documented routes to a running system, and they take the credential differently.

The board route is a three-step setup. Run the initializer in your project directory, put the key in an environment file, then restart the board:

```bash
npx kaibanjs@latest init
```

```
VITE_OPENAI_API_KEY=your-api-key-here
```

```bash
npm run kaiban
```

The variable name is the problem. The prefix is the one bundlers use for values that get inlined into client-side code, and the board is a web interface. So the board route asks you to write a key into a file that ends up in a browser bundle, while the library route puts the same key in a plain environment object handed to the team constructor in your own code, where it stays in whatever process you run it in.

If you use the board, treat that file as a secret and check what your build does with it. If you use the library, you control the process and the risk is entirely where you put it.

## The manifest is one patch ahead of the newest tag

The package manifest reads version 0.24.2 while the most recent published tag is 0.24.1. That is a small gap and it means one of two things: a release was cut from a later commit, or a tag was never pushed. Either way, the version in the tree is not the version on the registry, so pinning to the newest tag and pinning to the source give you different code.

The release history behind it is spaced out. The three most recent tags are 0.24.1 in May 2026, 0.23.0 in November 2025 and 0.22.0 in July 2025, so minor versions arrive every few months rather than weekly. The last push is dated 15 May 2026.

Two other manifest details. The badge row at the top of the documentation links a stability guide entry for beta software, so the project labels itself beta rather than stable. And the published tarball contains the build output, the licence, the readme, the manifest and one CLI script, with no source directory, so the initialiser works from the package while the code you would read is only in the repository.

## A script named for the compiler runs the bundler instead

The script table has a naming problem worth one line. There are four scripts that all invoke the bundler: the build, the dev watcher, a script named for the type checker, and the mocked test build. The real type check lives under a different name that invokes the compiler directly. So the script a developer or a continuous integration job would reach for by name does not do what its name says, and the one that does is easy to miss.

The rest of the table is more careful. Tests are split by environment variable: one variant builds with mocked model APIs, another runs integration tests against those mocks, and an end-to-end variant points at real APIs instead. A watch variant and two debug variants exist, the debug ones launching the inspector and running serially. Every Jest invocation is scoped by a test path pattern, so the unit and end-to-end suites are separate directories rather than one suite.

The repository carries six configuration files at the root for five tools, plus two Babel files where one would do, and a hooks directory for pre-commit checks. There is also a build output directory at the root while the manifest ships a different one, which is the kind of leftover that makes a clean checkout and a worked-in tree differ.

## Three abstractions, and the team owns the information flow

The concepts section is short, which is a compliment. An agent is an autonomous entity with a role and a goal, described as executing its task in a loop until it reaches an answer. A task defines what the agent must do, what output is expected, and can mark critical outputs as deliverables when they are the final products rather than intermediate steps. A team coordinates agents and tasks, starts from an initial input, and manages how information flows from one task to the next.

That last clause is where the orchestration actually lives. Neither the agent nor the task knows about its successors; the team does. So the framework's shape is closer to a scheduler with a visual metaphor than to a conversation between agents, and the loop-versus-graph distinction matters if you were expecting the latter.

The role-based design example makes the same point from the other side. Three agents are configured for a software team, each with a distinct role, a goal and a background string: a developer who writes and reviews code, a product manager who owns vision and roadmap, and a QA specialist who guards quality and consistency. Specialisation is expressed as configuration rather than as separate classes, and the background field is free text the model reads.

## The board is optional, and two playgrounds ship with the repo

The framework states that it is not limited to the board. You can import it directly into a project, build your own interface, or run agents with no interface at all, and the documentation points at separate tutorials for React and Node.js integration. The board is described as the visualisation layer rather than the runtime.

The repository backs that up. A playground directory holds a React application and a Node.js example, and the script table has three entry points for them: one starts the React dev server, one starts its component explorer, and one runs the Node.js example directly. So the two integration paths in the tutorials are the two things you can actually execute from a clone.

The initialiser serves the same purpose from the other side. Because the package ships the CLI script inside the tarball, a single npx call can scaffold a project without cloning anything, which is why the quick start claims it takes under a minute. The cost is that the scaffold is opinionated around a web build, so the board route and the server route are not equally well served by that first step.

## The metaphor is borrowed on purpose and stated as such

The opening of the documentation explains where the idea comes from: the Kanban methodology from software project management, the one people meet through Trello, Jira or ClickUp, adapted to the management of agents. The playground is pitched the same way, as a board that works like Trello or Asana but for agents and humans together.

Stating the source is useful, because it sets expectations about what the abstraction buys you. A Kanban board gives you visible state and a shared vocabulary for where work is stuck. What it does not give you is a different execution model, and this framework's execution model is the three objects above: a role and goal, a task with a deliverable flag, and a team that routes between them.

So the board earns its place when a team needs to watch and discuss runs, and the library earns its place when one process needs to call an agent. Both are shipped, the documentation says so in the integration section, and the version history suggests the library side is the one that has been iterating.

## Conclusion

KaibanJS is worth a look if you want to see multi-agent runs rather than infer them from logs. The board makes the state of every task visible, the same three abstractions are available as a plain library, and the package ships an initializer so a first run does not need a project to exist first.

Three things to check before you build on it. Decide where the API key lives, because the board path and the library path take it in different ways and one of them is a client-side build variable. Treat the version as moving, since the manifest sits a patch ahead of the newest tag and the project carries a beta stability badge. And do not copy the basic example verbatim, because the block as published ends on a half-typed catch call and will not parse.

The library path itself is small and legible: one agent with a role and a goal, one task bound to that agent, one team holding both and an environment. If your orchestration is more conditional than that, you will be reaching for the tasks yourself, and the board becomes a viewer rather than the scheduler.

## FAQ

### How do I run KaibanJS for the first time?

Run the initializer in your project directory, add your provider key to an environment file, then start the board with the npm script. The library path is separate: install the package, construct an agent, a task and a team, and call start on the team.

### Which environment variable does the KaibanJS board read?

A VITE_ prefixed variable holding the provider key, written into an environment file in the project. The prefix is the bundler convention for values inlined into client-side code, so the board path places the key in the browser build.

### What are the three core KaibanJS objects?

Agent, for a role and goal executed in a loop until an answer; Task, for the action, the expected output and whether the output is a deliverable; and Team, which coordinates agents and tasks from an initial input and manages information flow between them.

### Is the KaibanJS board required?

No. The framework can be imported directly, driven through a custom interface, or run with no interface, and the documentation links separate tutorials for React and Node.js. The repository ships a React playground and a Node.js example.

## Sources

- [kaiban-ai/KaibanJS on GitHub](https://github.com/kaiban-ai/KaibanJS)
- [License: MIT](https://github.com/kaiban-ai/KaibanJS/blob/main/LICENSE)
- [Project website](https://www.kaibanjs.com/)
- [README](https://github.com/kaiban-ai/KaibanJS/blob/main/README.md)
- [Releases](https://github.com/kaiban-ai/KaibanJS/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kaiban-ai-kaibanjs