Skip to content
Back to search

Jixu

Durable single-Agent Harness for TypeScript: recoverable Threads, context continuity, explicit side effects, and a native TUI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joe960913--jixu/badge.svg)](/listings/joe960913--jixu)

HTML

<a href="/listings/joe960913--jixu"><img src="/api/listings/joe960913--jixu/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 245 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="./assets/jixu-readme-hero-wide.png" alt="Jixu — Your Agent picks up where you left off." width="100%" />
  3. </p>
  4. # Jixu
  5. Jixu means *continue* in Chinese.
  6. A small single-Agent Harness for TypeScript. Define one Agent, give it Tools
  7. and Skills, and continue its work in a durable Thread.
  8. The core API stays small: `createHarness`, `createThread`, and `thread.send`.
  9. Underneath it, Jixu records execution, context decisions, and external work so
  10. the same Thread can recover, Replay, or Fork without a second runtime.
  11. > Jixu is pre-1.0. The public API may change before 1.0.
  12. ![Jixu terminal interface](./assets/jixu-tui.webp)
  13. ## Why Jixu
  14. Agent loops are easy to start. Resuming one safely is harder: a Tool call may be
  15. in flight, the process may stop between writes, or the model may run out of
  16. context.
  17. Jixu records the work as ordered Events. State is derived from them, and
  18. external work is recorded before it is dispatched. That is what lets a Thread
  19. recover, Replay, Fork, or continue later.
  20. Each Harness has one immutable Agent definition. Its Threads hold that Agent's
  21. durable history. There is no workflow graph or second execution engine.
  22. ## Start
  23. Install and open the reference TUI:
  24. ```bash
  25. npm install -g jixu-ai
  26. jixu
  27. ```
  28. Global installation also works with `pnpm add -g jixu-ai` and
  29. `bun add -g jixu-ai`. Or run Jixu without installing it:
  30. ```bash
  31. npx jixu-ai
  32. # pnpm dlx jixu-ai
  33. # yarn dlx jixu-ai
  34. # bunx jixu-ai
  35. ```
  36. The package launcher requires Node.js 22.19.0 or newer. The native TUI supports
  37. macOS arm64 and Linux x64 with glibc; Intel macOS is not supported. Bun is not
  38. required at runtime.
  39. The TUI uses the same public Agent, Harness, Thread, Store, and Driver APIs as
  40. any other Jixu application.
  41. ## Use Jixu as a framework
  42. ```bash
  43. npm install jixu-core jixu-llm jixu-store-sqlite
  44. ```
  45. ```ts
  46. import { createHarness, defineAgent } from "jixu-core";
  47. import {
  48. createLLMModelDriver,
  49. resolveLLMModelCapabilities,
  50. } from "jixu-llm";
  51. import { SqliteEventStore } from "jixu-store-sqlite";
  52. const connection = {
  53. api: "openai-chat-completions" as const,
  54. apiKey: process.env.MODEL_API_KEY,
  55. baseURL: "https://api.openai.com/v1",
  56. model: "gpt-5.6-sol",
  57. };
  58. const modelCapabilities = await resolveLLMModelCapabilities(connection);
  59. const agent = defineAgent({
  60. instructions: "Be precise and verify your work.",
  61. model: { provider: "model", model: connection.model },
  62. modelCapabilities,
  63. tools: [],
  64. });
  65. const harness = createHarness({
  66. agent,
  67. modelDrivers: {
  68. model: createLLMModelDriver({
  69. api: connection.api,
  70. apiKey: connection.apiKey,
  71. baseURL: connection.baseURL,
  72. maxOutputTokens: modelCapabilities.maxOutputTokens,
  73. }),
  74. },
  75. store: new SqliteEventStore("./jixu.db"),
  76. });
  77. const thread = await harness.createThread();
  78. const state = await thread.send("Review this design and identify its main risk.");
  79. console.log(state.result);
  80. ```
  81. The Agent definition is immutable. Each `send` continues the same durable
  82. Thread.
  83. ### Progressive Skills
  84. `defineSkill` and `defineAgent({ skills })` are available in Jixu 0.5.0. A Skill supplies
  85. instructions without adding a Tool or granting permissions. The model initially
  86. sees its name, description and version, then activates the relevant body before
  87. using it. The accepted body is durable and participates in Context budgeting,
  88. Replay and Fork. Clear removes active bodies while retaining the catalogue.
  89. The reference TUI adds a local manager under `/config` → **SKILLS** (F2 cycles tabs).
  90. Create, edit, enable or remove Skills, then Apply for a fresh workspace. Existing
  91. Threads retain their original Agent and require matching Skill configuration.
  92. See the [Skill configuration example](packages/core/README.md#progressive-skills)
  93. and [installed-package acceptance](evals/reliability/README.md#progressive-skills).
  94. ## Thread operations
  95. The public Harness creates, opens, and lists Threads. A Thread exposes one
  96. coherent surface for ordinary work and continuity operations:
  97. | Operation | Meaning |
  98. | --- | --- |
  99. | `send(input)` | Durably accepts ordered text and image input. Input received while work is running is queued in Event order. |
  100. | `state()` | Returns the current deterministic projection of the Thread's Events. |
  101. | `events()` | Reads the immutable durable facts behind that State. |
  102. | `stream()` | Observes committed Events and transient Signals through one ordered surface. |
  103. | `wait()` | Waits until the Thread is no longer `running`. |
  104. | `pause()` | Records pause intent and settles at a safe append/dispatch boundary. |
  105. | `continue()` | Durably continues a paused Thread before dispatch resumes. |
  106. | `interrupt()` | Stops the current turn without turning it into resumable paused work. |
  107. | `resolveToolOutcome({ effectId, resolution })` | Records an operator fact for one retained unknown Tool outcome. Resolution is `occurred`, `not_occurred`, or `abandoned_unknown`. |
  108. | `clear()` | Advances the model-visible context boundary while retaining the Thread and its durable history. |
  109. | `replay()` | Rebuilds State from Events with zero live Driver calls. |
  110. | `fork({ at, input })` | Creates a new child Thread from the exact State at one selected Event. |
  111. | `setMode(mode)` | Durably selects `standard` or the strongest compatible `ultra` reasoning effort without changing the Agent or model. |
  112. ## One authoritative execution path
  113. ```text
  114. durable Event -> pure Reducer -> explicit Effect -> Driver -> durable Event
  115. ```
  116. The Kernel reduces Events into State and Effects without performing I/O. Drivers
  117. execute external work and append the result as another Event. Replay only
  118. reduces recorded Events; it never calls a live model or Tool.
  119. Jixu retries only when the Effect's delivery contract makes that safe:
  120. - a deterministic Tool failure is recorded and returned to the Agent as a
  121. failed Tool result so the same turn can recover or explain;
  122. - an unknown non-idempotent outcome is retained and enters `waiting` rather
  123. than being silently repeated;
  124. - a retained unknown outcome resumes only after an explicit operator decision;
  125. that decision is durable context, not an invented Tool result or an automatic
  126. retry;
  127. - `allow`, `ask`, and `deny` Tool policy decisions are resolved before Driver
  128. dispatch, and approvals are durable decisions for one exact pending Effect.
  129. Jixu does not claim generic exactly-once execution. That guarantee requires an
  130. enforceable idempotency contract in the downstream system.
  131. ## Context engineering
  132. Each model request is assembled from the Thread's durable material: Agent
  133. instructions, relevant Events, the active Plan, Skills, Tool schemas, Artifacts,
  134. and recent work. A redacted Context Manifest records what was selected and why.
  135. Jixu resolves the model's context window and output limit before Agent creation.
  136. If capacity is unknown, it stops instead of guessing. When older work must be
  137. compacted, Jixu writes a source-linked Continuity Handoff and keeps a bounded
  138. tail of complete recent operations. The underlying Events are not rewritten.
  139. ## Plans
  140. A Plan is optional Event-backed coordination data. It can record acceptance
  141. criteria, steps, evidence, blockers, and the next safe action, but it cannot
  142. dispatch Effects, approve a Tool call, or widen user scope.
  143. A Thread has at most one Plan and one active step. Changes are validated and
  144. committed before related Effects can dispatch; rejected changes remain visible
  145. in Event history. The Plan is a current hypothesis rather than a fixed schedule:
  146. completed work and the current step stay protected, while pending steps may be
  147. rewritten as evidence changes. If a model returns only Plan or progress control,
  148. Jixu durably gives it one execution-only continuation with ordinary Tools and no
  149. reserved controls; the control plane cannot loop indefinitely or permanently
  150. block the requested work.
  151. ## Inspectable execution
  152. Jixu keeps operational facts inside the same durable model:
  153. - logical model and Tool calls remain distinct from dispatch attempts;
  154. - reported token usage stays distinct from unavailable values, and unknown
  155. pricing remains unknown instead of rendering as zero;
  156. - ordered text and image input is preserved, while image bytes live in verified
  157. immutable Artifacts rather than Events;
  158. - Secrets never enter Events, State, Checkpoints, errors, or Signals.
  159. ## Packages
  160. | Package | Purpose |
  161. | --- | --- |
  162. | [`jixu-ai`](https://www.npmjs.com/package/jixu-ai) | Framework entry point and installable reference TUI. |
  163. | [`jixu-core`](https://www.npmjs.com/package/jixu-core) | The single-Agent Harness, Thread API, deterministic Kernel, and public ports. |
  164. | [`jixu-llm`](https://www.npmjs.com/package/jixu-llm) | Provider-neutral model Drivers for OpenAI Chat Completions and Anthropic Messages. |
  165. | [`jixu-store-jsonl`](https://www.npmjs.com/package/jixu-store-jsonl) | Inspectable local JSONL Event Store. |
  166. | [`jixu-store-sqlite`](https://www.npmjs.com/package/jixu-store-sqlite) | Local SQLite Event Store. |
  167. | [`jixu-tools-node`](https://www.npmjs.com/package/jixu-tools-node) | Opt-in Node file and unsandboxed local shell Tools. |
  168. | [`jixu-tools-jina`](https://www.npmjs.com/package/jixu-tools-jina) | Opt-in Jina-backed Web Search and URL Reader Tools. |
  169. | [`jixu-testkit`](https://www.npmjs.com/package/jixu-testkit) | Deterministic fixtures and shared Store contracts for adapter authors. |
  170. > [!WARNING]
  171. > Jixu's Bash Tool is not OS-sandboxed and runs with the permissions of the Jixu
  172. > process. Permission controls approve Tool calls, not individual shell
  173. > operations. Keep Bash on `ASK` and use a backed-up or disposable workspace.
  174. Model providers, Tools, Stores, and UIs use the runtime's public ports. Thread
  175. state still belongs to the core runtime.
  176. ## What Jixu is not
  177. Jixu is not a multi-Agent orchestrator, workflow engine, or hosted control
  178. plane. It does not add Agent graphs, supervisors, queues, schedulers, or a
  179. generic exactly-once guarantee. External systems remain ordinary Tools and do
  180. not change the single-Agent model.
  181. ## Documentation
  182. - [Documentation](https://jixu.dev/docs)
  183. - [Specification](./SPEC.md)
  184. - [Contributing](./CONTRIBUTING.md)
  185. - [npm package](https://www.npmjs.com/package/jixu-ai)
  186. ## License
  187. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.