# Helixent ships one compiled binary, and its library surface does not ship at all

> MagicCube/helixent is a Bun and TypeScript agent framework with a ReAct loop, middleware, a skills loader and a coding agent, published to npm as a single compiled executable. The README teaches you to import from helixent/coding, but the package's files array contains only that binary.

**MagicCube/helixent** — Helixent is a small library for building ReAct-style AI agent loops based on the Bun stack.

- Repository: https://github.com/MagicCube/helixent
- Stars: 678 · Forks: 107
- Language: TypeScript
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/magiccube-helixent

## The published package is dist/bin/helixent and nothing else

This is the single most consequential line in the manifest, because it decides what npm consumers actually get. The files array contains one entry, dist/bin/helixent, which is also the bin target, so the tarball is a compiled executable and nothing else. There is no exports map, and the module field points at index.ts, the TypeScript entry in the repository rather than a built artefact. That combination matters because the README's worked example imports createCodingAgent from helixent/coding, a subpath that requires an exports map and shipped JavaScript to resolve. Neither is in the package. So the CLI is genuinely installable and runnable, the library surface is source-only, and anyone planning to embed the agent loop in their own TypeScript project has to vendor the repository or build it locally with the build:js script.

## Two ways to run, and both end inside your project

Running it is deliberately short, and the two documented options differ only in whether the package lands on disk:

```bash
npm install -g helixent@latest
cd path/to/your/project
helixent
helixent --help
```

The alternative skips the global install and uses npx with the same latest tag. In both cases the step that matters is the change of directory. The CLI is meant to be started from inside a project, because that is where two of its inputs come from: an AGENTS.md at the repository root is picked up automatically as project guidance, and skills are discovered relative to the current project as well as in your home directory. Start it from your home directory and you get the general agent with none of the project context, which is a different tool from the one the documentation is describing.

## Skills load from four directories and duplicate names are allowed

The skills system follows the standard agent skill format published at agentskills.io, and discovery is a search path rather than a single location. Four directories are scanned: ~/.agents/skills and ~/.helixent/skills under your home directory, and .agents/skills and .helixent/skills under the current project. The two prefixes are deliberately parallel, one following the cross-tool convention and one following Helixent's own, which means a skill written for another agent tool can sit beside a Helixent-specific one. Duplicates are permitted rather than treated as an error, so the same skill name can exist in two folders without a collision, and resolution order is left to the loader. Layered on top of that is long-term memory in the simplest possible form: an AGENTS.md at the project root, read automatically. The coding agent also has a todo-list-based plan mode, so structured work is the default shape rather than an add-on.

## The loop runs tools in parallel and can stop for approval

The architecture is three layers with a fourth area for adapters. Foundation holds the primitives everything else builds on: Model, a unified abstraction over providers so you define a model once and swap backends without touching agent code; Message, a single transcript type described as the source of truth for the conversation; and Tool, the definitions and execution plumbing for the actions an agent may invoke. The agent loop on top of it is ReAct-style, maintaining state over the transcript and orchestrating think, act and observe steps. Two details shape how it behaves. Tool calls are invoked in parallel and the observations are fed back into the next reasoning step, so a turn can issue several calls at once rather than serialising them. And the loop is middleware-ready, with state, tool orchestration and skills as extension points, plus human-in-the-loop approval for tool calls. The coding agent above it is the domain layer, pre-configured with the file and shell tools a developer workflow needs.

## One provider adapter ships, and it speaks to any compatible endpoint

The community area holds optional, decoupled adapters that implement the Foundation interfaces for specific providers, and exactly one is documented. community/openai provides an OpenAIModelProvider backed by the openai SDK, described as compatible with any OpenAI-compatible endpoint, which is the same property that makes it useful against local servers and gateways rather than only against the vendor's own API. The complete example in the documentation creates a coding agent with such a provider and runs a whole turn through it. The architecture note is that this layer depends only on Foundation and remains generic, not tied to a domain, which is what keeps the third layer swappable. In practice the trade-off is that the framework's provider coverage is thin out of the box, so a second backend means writing an adapter against the Model contract rather than changing configuration.

## The documented test command has no matching script

Quality gates are described twice, and once they point at something that is not in the manifest. The documentation says to run bun run check before committing so changes pass linting, type checking and tests, and offers bun run test for running the tests only. The script list in package.json has check, defined as tsc --noEmit followed by eslint and then bun test, plus check:types for the type check alone and lint and lint:fix. There is no test script, so the documented shortcut for tests alone does not resolve to anything. Everything else in that list is concrete: build:bin removes dist/bin and compiles index.ts into a single executable with bun build --compile, build:js produces split JavaScript targeting Bun, prepublishOnly runs the binary build, and the two release scripts bump the version with npm version and publish. There is also a hooks:install script that points core.hooksPath at the .githooks directory, which is what makes the pre-commit gate real.

## Version 1.3.1 on npm, no release tag, and a committed test log

A few details around the edges are worth knowing. The npm package is at version 1.3.1 with public publish access, while the repository publishes no GitHub releases at all, so the version history lives only on the registry and in the package itself. The last commit to the repository was 21 May 2026, and the manifest version has not been republished since. Licensing is inconsistent in a way that matters for adoption: package.json declares MIT, while the licence carried by the repository itself is empty. The tree also shows how the project dogfoods what it supports, with a skills directory, an AGENTS.md, a CLAUDE.md and both .claude/ and .cursor/ configuration directories. Two housekeeping artefacts are unusual: a test.log committed at the repository root, and a .markdownlint.json beside a .prettierrc and an eslint.config.js, with the lint scripts still passing an --ext flag alongside that flat configuration.

## Conclusion

Helixent is worth using as a CLI, because the coding agent, the four-directory skills loader, project AGENTS.md memory and the parallel-tool ReAct loop are all reachable from one executable with no runtime of its own to provision. Do not plan to consume it as a library from npm, since the published files array carries only the binary and the helixent/coding subpath in the README's example will not resolve from an install. Two smaller checks before you commit to it. The documented test-only command has no matching script in the manifest, so use bun run check. And the repository declares MIT in package.json while the licence attached to the repository itself is absent.

## FAQ

### How do I install and run Helixent?

Install it globally with npm install -g helixent@latest, change into your project directory, then run helixent, with helixent --help for the command list. To avoid installing anything, run npx helixent@latest from the same project directory. Starting inside the project is what lets the CLI pick up a root AGENTS.md and project-local skills.

### Where does Helixent keep its configuration?

In ~/.helixent/config.yaml. Models are managed through the CLI with helixent config model list, helixent config model add, helixent config model remove and helixent config model set-default. The remove and set-default commands take an optional model name, and running them without one selects from the list of configured models.

### How do I build the Helixent CLI from source?

Run bun install, then bun run dev for development mode or bun run build:bin to compile a single executable at dist/bin/helixent. Before committing, run bun run check, which runs tsc --noEmit, eslint and bun test. Running hooks:install sets core.hooksPath to .githooks so the same check blocks commits locally.

### Can I import Helixent as a library in my own TypeScript project?

Not from the npm package as published. The files array in package.json contains only dist/bin/helixent, and there is no exports map, so the helixent/coding subpath used in the README's example will not resolve from an install. Build from a checkout with the build:js script, or vendor the repository, if you need the agent loop as a dependency.

## Sources

- [Issues](https://github.com/MagicCube/helixent/issues)
- [MagicCube/helixent on GitHub](https://github.com/MagicCube/helixent)
- [README](https://github.com/MagicCube/helixent/blob/main/README.md)

---

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