{"id":48534087,"url":"https://github.com/magiccube/helixent","last_synced_at":"2026-04-13T06:01:33.358Z","repository":{"id":349687800,"uuid":"1202683003","full_name":"MagicCube/helixent","owner":"MagicCube","description":"Helixent is a small library for building ReAct-style agent loops based on the Bun stack.","archived":false,"fork":false,"pushed_at":"2026-04-11T01:44:39.000Z","size":308,"stargazers_count":148,"open_issues_count":2,"forks_count":30,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T04:29:49.309Z","etag":null,"topics":["agent","agent-loop","bun","cli","coding","skills"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MagicCube.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-06T09:34:58.000Z","updated_at":"2026-04-11T01:44:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"254dc5bb-3011-4d7c-8daa-8604d6d133d5","html_url":"https://github.com/MagicCube/helixent","commit_stats":null,"previous_names":["magiccube/helixent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MagicCube/helixent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fhelixent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fhelixent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fhelixent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fhelixent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MagicCube","download_url":"https://codeload.github.com/MagicCube/helixent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MagicCube%2Fhelixent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31704492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"online","status_checked_at":"2026-04-12T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agent-loop","bun","cli","coding","skills"],"created_at":"2026-04-08T01:02:25.222Z","updated_at":"2026-04-12T05:01:03.853Z","avatar_url":"https://github.com/MagicCube.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://github.com/user-attachments/assets/9b4b7b72-45f4-4ae5-8fd5-5fb48d615481)\n\n# Helixent\n\n[![npm](https://img.shields.io/npm/v/helixent?label=npm\u0026logo=npm\u0026color=CB3837)](https://www.npmjs.com/package/helixent)\n[![Check](https://github.com/magiccube/helixent/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/magiccube/helixent/actions/workflows/check.yml)\n[![Bun](https://img.shields.io/badge/Bun-000000?logo=bun\u0026logoColor=ffffff)](https://bun.com)\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript\u0026logoColor=ffffff)](https://www.typescriptlang.org)\n[![Ink](https://img.shields.io/badge/Ink-000000?logo=npm\u0026logoColor=ffffff)](https://github.com/vadimdemedes/ink)\n[![React](https://img.shields.io/badge/React-61DAFB?logo=react\u0026logoColor=000000)](https://react.dev)\n\nHelixent is a blue rabbit that writes code. It includes an Agent Loop, a Coding Agent, and a nice CLI.\n\n## Demo\n\nhttps://github.com/user-attachments/assets/4ad89f14-e338-43e4-82ce-91cb83d58be2\n\n## Index\n\n- [Get Started](#get-started)\n  - [Key Features](#key-features)\n  - [Install and Run](#install-and-run)\n    - [Option 1: Install and Run](#option-1-install-and-run)\n    - [Option 2: Run without Installing](#option-2-run-without-installing)\n- [Model Configuration](#model-configuration)\n  - [List Configured Models](#list-configured-models)\n  - [Add a New Model](#add-a-new-model)\n  - [Remove a Model](#remove-a-model)\n  - [Set the Default Model](#set-the-default-model)\n- [How to Contribute](#how-to-contribute)\n  - [Develop \u0026 Build from Source](#develop-build-from-source)\n    - [1. Install Dependencies](#1-install-dependencies)\n    - [2. Run in Development Mode](#2-run-in-development-mode)\n    - [3. Build the Binary](#3-build-the-binary)\n  - [Architecture](#architecture)\n    - [Layer 1: Foundation](#layer-1-foundation)\n    - [Layer 2: Agent Loop](#layer-2-agent-loop)\n    - [Layer 3: Coding Agent](#layer-3-coding-agent)\n  - [Community](#community)\n    - [How to Build a Coding Agent from Scratch](#how-to-build-a-coding-agent-from-scratch)\n  - [Middleware](#middleware)\n    - [Available Hooks](#available-hooks)\n  - [Why Bun?](#why-bun)\n- [Roadmap](#roadmap)\n\n---\n\n## Get Started\n\n### Key Features\n\n- **Model Foundation**\n  - A stable core `Model` abstraction plus provider-facing contracts, designed to keep model integrations clean and reusable.\n  - Multiple models are supported.\n- **Agent Loop (Middleware-Ready)**\n  - A reusable ReAct-style agent loop.\n  - First-class middleware support for extending behavior (state, tool orchestration, skills, etc.).\n  - Human-in-the-loop support for approval of tool calls.\n  - See [Middleware](#middleware)\n- **Skills Support**\n  - The [standard agent skill](https://agentskills.io/) format is supported.\n  - Skills are discovered and loaded from:\n    - `~/.agents/skills`\n    - `~/.helixent/skills`\n    - `${current_project}/.agents/skills`\n    - `${current_project}/.helixent/skills`\n  - Duplicate skill names in different folders are allowed.\n\n- **Long-term memory**\n  - **Project root `AGENTS.md` support**: if an `AGENTS.md` exists at the repository root, it is automatically picked up as project guidance.\n- **Coding Agent**\n  - A coding-focused agent layer with practical tools (e.g. `bash`, `read_file`, `write_file`, `str_replace`, `list_files`, `glob_search`, `grep_search`, `apply_patch`, `file_info`, `mkdir`, `move_path`, etc.) for developer workflows.\n  - Todo-list-based **plan mode** is supported.\n- **CLI**\n  - A CLI (with TUI support) for running agents interactively and iterating quickly.\n\nHelixent is now available on [`npm`](https://www.npmjs.com/package/helixent), so you can install globally and run, or choose to run via npx without installing:\n\n### Install and Run\n\n#### Option 1: Install and Run\n\n```bash\nnpm install -g helixent@latest\ncd path/to/your/project\nhelixent\nhelixent --help\n```\n\n#### Option 2: Run without Installing\n\n```bash\ncd path/to/your/project\nnpx helixent@latest\nnpx helixent --help\n```\n\n## Model Configuration\n\nHelixent stores your CLI configuration in:\n\n- `~/.helixent/config.yaml`\n\n### List Configured Models\n\n```bash\nhelixent config model list\n```\n\n### Add a New Model\n\n```bash\nhelixent config model add\n```\n\n### Remove a Model\n\n```bash\nhelixent config model remove \u003cmodel_name\u003e\n```\n\nOr select from the list of configured models:\n\n```bash\nhelixent config model remove\n```\n\n### Set the Default Model\n\n```bash\nhelixent config model set-default \u003cmodel_name\u003e\n```\n\nOr select from the list of configured models:\n\n```bash\nhelixent config model set-default\n```\n\n---\n\n## How to Contribute\n\n### Develop \u0026 Build from Source\n\nThis section shows how to build Helixent from source and link the `helixent` CLI into your global PATH on **macOS**.\n\n#### 1. Install Dependencies\n\n```bash\nbun install\n```\n\nAll pushes and pull requests run `bun run check` in GitHub Actions. Local commits are also blocked by the pre-commit hook until the same check passes.\n\n#### 2. Run in Development Mode\n\n```bash\nbun run dev\n```\n\n#### 3. Build the Binary\n\n```bash\nbun run build:bin\n```\n\nAfter the build completes, you should have:\n\n- `dist/bin/helixent`\n\n#### 4. Before Commit\n\nMake sure your changes pass all the linting, type checking, and tests by running:\n\n```bash\nbun run check\n```\n\nOr run tests only by running:\n\n```bash\nbun run test\n```\n\n\u003e This is also run automatically by the pre-commit hook. This also causes the committing process a little bit slower,\n\u003e but we think it's worth it. After all, in an AI-dominated GitHub universe, we should be able to handle the last mile of code quality.\n\n### Architecture\n\nHelixent is organized into three layers, plus a `community` area for third-party integrations.\n\n```\nsrc/\n├── foundation/    # Layer 1 – Core primitives\n├── agent/         # Layer 2 – Agent loop\n├── coding/        # Layer 3 – Coding agent (domain-specific)\n└── community/     # Third-party integrations (e.g. OpenAI)\n```\n\n#### Layer 1: Foundation\n\nCore primitives that everything else builds on:\n\n- **Model** — A unified abstraction over LLM providers. Define a model once, swap providers without changing agent code.\n- **Message** — A single transcript type that flows end-to-end through the system — the single source of truth for the conversation.\n- **Tool** — Tool definitions and execution plumbing (the \"actions\" an agent can invoke).\n\n#### Layer 2: Agent Loop\n\nA reusable **ReAct-style agent loop**:\n\n- Maintains state over a conversation transcript.\n- Orchestrates \"think → act → observe\" steps in a loop.\n- Invokes tool calls in parallel and feeds observations back into the next reasoning step.\n- Supports **middleware** for extending behavior (see below).\n\nThis layer depends only on Foundation and remains generic — not tied to any specific domain.\n\n#### Layer 3: Coding Agent\n\nA domain-specific agent built on top of the generic agent loop, pre-configured with coding-oriented tools (`read_file`, `write_file`, `str_replace`, `bash`, `list_files`, `glob_search`, `grep_search`, `apply_patch`, `file_info`, `mkdir`, `move_path`, etc.) and the skills middleware.\n\n### Community\n\nOptional, decoupled adapters that implement Foundation interfaces for specific providers:\n\n- `community/openai` — `OpenAIModelProvider` backed by the `openai` SDK, compatible with any OpenAI-compatible endpoint.\n\n#### How to Build a Coding Agent from Scratch\n\nHere is a complete example that creates a coding agent using an OpenAI-compatible provider:\n\n```ts\nimport { createCodingAgent } from \"helixent/coding\";\nimport { OpenAIModelProvider } from \"helixent/community/openai\";\nimport { Model } from \"helixent/foundation\";\n\n// 1. Set up a model provider (any OpenAI-compatible endpoint works)\nconst provider = new OpenAIModelProvider({\n  baseURL: \"https://api.openai.com/v1\",\n  apiKey: process.env.OPENAI_API_KEY,\n});\n\n// 2. Create a model instance with your preferred options\nconst model = new Model(\"gpt-4o\", provider, {\n  max_tokens: 16 * 1024,\n  thinking: { type: \"enabled\" },\n});\n\n// 3. Create the agent — tools and skills are wired up automatically\nconst agent = await createCodingAgent({ model });\n\n// 4. Stream the agent's response\nconst stream = await agent.stream({\n  role: \"user\",\n  content: [{ type: \"text\", text: \"Create a hello world web server in the current directory.\" }],\n});\n\nfor await (const message of stream) {\n  for (const content of message.content) {\n    if (content.type === \"thinking\" \u0026\u0026 content.thinking) {\n      console.info(\"💡\", content.thinking);\n    } else if (content.type === \"text\" \u0026\u0026 content.text) {\n      console.info(content.text);\n    } else if (content.type === \"tool_use\") {\n      console.info(\"🔧\", content.name, content.input.description ?? \"\");\n    }\n  }\n}\n```\n\n### Middleware\n\nHelixent provides a **middleware** system that lets you observe and mutate the agent's behavior at every stage of the loop. Middleware hooks are invoked sequentially in array order.\n\n#### Available Hooks\n\n| Hook | When it runs |\n|---|---|\n| `beforeAgentRun` | Once after the user message is appended, before the first step |\n| `afterAgentRun` | Once when the agent is about to stop (no tool calls) |\n| `beforeAgentStep` | At the start of each step, before the model is invoked |\n| `afterAgentStep` | At the end of each step, after all tool calls complete |\n| `beforeModel` | Before the model context is sent to the provider |\n| `afterModel` | After the model response is received |\n| `beforeToolUse` | Immediately before a tool is invoked |\n| `afterToolUse` | Immediately after a tool invocation resolves |\n\nEach hook receives the current context and can return a partial update to merge back in, or `void` to leave it unchanged.\n\n### Why Bun?\n\nAgent loops are inherently asynchronous — the model thinks, tools execute, results stream back, often in parallel. JavaScript/TypeScript has **native async/await** baked into the language and runtime, making concurrent orchestration straightforward without the callback gymnastics or `asyncio` boilerplate you'd face in Python.\n\nAmong JS runtimes, we chose [**Bun**](https://bun.com/) specifically because:\n\n- **Same runtime as Claude Code** — Bun powers Claude Code and a growing number of TypeScript-first tools. It's built for speed, and a compiled build is a single native executable.\n- **Performance** — HTTP, filesystem I/O, and cold starts are all noticeably faster than Node's, which adds up when an agent loop issues dozens of tool calls per run.\n- **Standalone executables** — `bun build --compile` outputs one self-contained binary. Shipping a CLI is as simple as handing users a single file—no separate runtime install.\n- **Batteries included** — Test runner, bundler, and TypeScript support ship with Bun, so there's no separate toolchain to wire up.\n\n---\n\n## Roadmap\n\n- **Sub-agent** — Spawn child agents from within a run to handle subtasks independently, each with their own context and tool set.\n- **Agent Team** — Multi-agent collaboration where agents can coordinate, delegate, and share results to tackle complex problems together.\n- **Print Mode** — A Claude Code-style rendering mode that streams the agent's thinking, tool calls, and outputs in a rich, human-friendly terminal UI.\n- **Sessioning** — A local, file-based session store for the agent's context and history.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagiccube%2Fhelixent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagiccube%2Fhelixent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagiccube%2Fhelixent/lists"}