GitHub - Tokfinity/InfCodeX: A lightweight AI coding agent that actually works. InfCodeX is modular, zero-config, and supports multiple LLM providers out of the box. Use it as a CLI tool or npm library—with session memory, parallel execution, and agent teams. Written in TypeScript.

Source-available AI coding agent on every LLM you can reach.
Anthropic · OpenAI · DeepSeek · Kimi · Zhipu · MiniMax · MiMo · Ark · Qwen · Gemini · Codex.
REPL · CLI · library · Node-free single binary.
InfCodeX keeps the historical KodaX / kodax package and command names for compatibility.

Install · Usage · SDK · Changelog · Roadmap · Discussions · 中文 README

Install in 30 seconds

npm i -g @kodax-ai/kodax

# Pick any one you have an API key for:
export ZHIPU_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY / KIMI_API_KEY /
                                # MINIMAX_API_KEY / MIMO_API_KEY / ARK_API_KEY / QWEN_API_KEY /
                                # DEEPSEEK_API_KEY / GEMINI_API_KEY

kodax

That's it. You're in the REPL — ask anything in natural language.

No-Node target machines: download a Bun-compiled single binary for Windows / macOS / Linux × x64 + arm64 from the GitHub Releases page. See docs/release.md for the build pipeline.

Four ways to use KodaX

Form	Command / Import	When to use it
REPL	`kodax`	Interactive multi-turn coding session with streaming UI, permissions, slash commands
CLI	`kodax -p "your task"`	One-shot scripted task, CI runs, batch processing
Library	`import { runKodaX } from '@kodax-ai/kodax'`	Embed in your own tool / agent / web service
Single binary	`./kodax`	Distribute to machines that don't have Node installed

Why KodaX

🇨🇳 6 China-native LLMs _{Zhipu · Kimi · MiniMax · MiMo · Ark · Qwen} First-class adapters with cross-provider prompt-eval calibration on a canonical 5-alias panel — not OpenAI-compat shims.	📦 Single-file binary _{Bun --compile · Win / macOS / Linux · x64 + arm64} No Node required on the target machine. Drop one file, run anywhere — restricted envs, CI runners, air-gapped boxes.	🌳 Branchable session lineage _{Fork · rewind · parallel edit} Conversation history is a DAG, not a list. Powers the upcoming KodaX Space desktop app.
🤖 Multi-agent by default _{V2 Worker single-loop + Sidecar Verifier + async children} `dispatch_child_task`, `send_message`, `task_stop`, multi-instance auto-coordination with content-hash safety net.	🧩 Skills + self-construction _{Markdown skills, NL triggers} 5-stage self-modification staircase (scaffold → validate → stage → test → activate) gated by an 8-invariant admission contract.	🛠 50+ built-in tools _{File · shell · search · MCP · ACP} Repo intelligence, semantic search, git worktree, web fetch — all addressable through one clean tool surface.

How KodaX compares

Feature	KodaX	Claude Code	Aider	Codex CLI	Cursor	Cline
Source license	⚠️ KAI-FCL, non-commercial	❌ Source-available	✅ Apache 2.0	✅ Apache 2.0	❌ Proprietary	✅ Apache 2.0
Node-free single binary	✅ Bun	❌ Node	❌ Python	✅ Rust	❌ Electron	❌ Extension
Native China providers _{(Zhipu · Kimi · MiniMax · MiMo · Ark · Qwen)}	✅ 6 native	❌	⚠ via LiteLLM	❌ OpenAI-first	❌ no provider menu	⚠ Kimi / Qwen / DeepSeek
Branchable session lineage	✅ fork & rewind	⚠ routines / sessions	❌	❌	❌	⚠ checkpoints
Multi-agent + MCP + 50+ tools	✅ all three	✅ all three	⚠ tools, no MCP	✅ all three	⚠ Composer + MCP	✅ all three

_{Data verified May 2026 against public docs (Claude Code · Aider · Codex CLI · Cursor · Cline). ⚠ = partial / requires extra setup / not first-class. Corrections welcome via PR.}

Detailed Setup

The npm i -g @kodax-ai/kodax one-liner above is the fastest path. This section is for building from source, configuring custom providers, or using KodaX as a library.

1. Build the CLI from source

git clone https://github.com/icetomoyo/KodaX.git
cd KodaX
npm install
npm run build
npm link

To create an InfCodeX-branded npm tarball without changing tracked package metadata, run:

npm run release:infcodex

The command reuses the current single-bundle release pipeline, temporarily packages the unscoped infcodex package with an infcodex CLI command, and restores package.json afterward. The artifact is written as infcodex-<version>.tgz at the repository root.

2. Configure a provider

KodaX reads API keys from environment variables. For built-in providers, the fastest path is:

# macOS / Linux
export ZHIPU_API_KEY=your_api_key

# PowerShell
$env:ZHIPU_API_KEY="your_api_key"

For CLI defaults, create ~/.kodax/config.json:

{
  "provider": "zhipu-coding",
  "effort": "auto"
}

If you need a custom base URL or an OpenAI/Anthropic-compatible endpoint, define a custom provider in the same config file:

{
  "provider": "my-openai-compatible",
  "customProviders": [
    {
      "name": "my-openai-compatible",
      "protocol": "openai",
      "baseUrl": "https://example.com/v1",
      "apiKeyEnv": "MY_LLM_API_KEY",
      "model": "my-model",
      "userAgentMode": "compat",
      "reasoning": {
        "efforts": ["off", "low", "medium", "high", "max"],
        "default": "high"
      }
    }
  ]
}

userAgentMode defaults to "compat", which sends KodaX instead of the official SDK User-Agent. Switch it to "sdk" only when your gateway expects the upstream SDK header. For custom reasoning models, reasoning: { efforts, default } is the preferred v0.7.57 shape; use "reasoning": "none" for models without thinking capability. SDK hosts should render effort pickers from reasoningProfile.supportedEfforts / defaultEffort rather than assuming a fixed five-option ladder.

OpenAI-compatible reasoning providers

Some OpenAI-compatible reasoning models require KodaX to replay the previous assistant turn's reasoning_content on later requests. DeepSeek V4 thinking mode is the known load-bearing case. Built-in DeepSeek already opts in; custom providers must say so explicitly:

{
  "customProviders": [
    {
      "name": "my-deepseek-v4",
      "protocol": "openai",
      "baseUrl": "https://example.com/v1",
      "apiKeyEnv": "MY_DEEPSEEK_API_KEY",
      "model": "deepseek-v4-flash",
      "reasoningPreset": "deepseek-v4-openai",
      "replayReasoningContent": true
    }
  ]
}

Keep replayReasoningContent unset or false for OpenAI proper and gateways that reject unknown assistant-message fields. If one gateway routes mixed models, prefer per-model overrides:

{
  "models": [
    { "id": "deepseek-v4-flash", "replayReasoningContent": true },
    { "id": "gpt-5", "replayReasoningContent": false }
  ]
}

Sidecar verifier judge calls use provider-level forced tool choice when supported. If a compatible endpoint rejects the tool_choice parameter, KodaX retries that verifier request once without forced tool choice and still fails open rather than blocking the main Worker.

Opting a custom provider into image / vision input (FEATURE_134 v0.7.40)

If your custom provider's underlying model supports image input (vision), add a capabilityProfile.multimodalSupport: "image-input" block so KodaX does not artificially block multimodal requests at the SA-path policy gate. Built-in vision-capable aliases (Anthropic, OpenAI, Anthropic-/OpenAI-compatible aliases such as DeepSeek, Kimi, Qwen, Zhipu, MiniMax, MiMo, Ark, plus Gemini-CLI via the CLI's @<path> file-include syntax) already ship with this flag enabled by default; Codex-CLI and custom providers need to opt in when their underlying model supports image input.

{
  "customProviders": [
    {
      "name": "my-vision-provider",
      "protocol": "openai",
      "baseUrl": "https://example.com/v1",
      "apiKeyEnv": "MY_LLM_API_KEY",
      "model": "my-vision-model",
      "capabilityProfile": {
        "transport": "native-api",
        "conversationSemantics": "full-history",
        "mcpSupport": "none",
        "contextFidelity": "full",
        "toolCallingFidelity": "full",
        "sessionSupport": "full",
        "longRunningSupport": "full",
        "multimodalSupport": "image-input",
        "evidenceSupport": "full"
      }
    }
  ]
}

The serializer layer (packages/llm/src/providers/anthropic.ts:770 for Anthropic-compat, openai.ts:904 for OpenAI-compat) forwards image blocks automatically through base-class inheritance. The flag only gates whether KodaX's policy layer pre-rejects multimodal requests — the model-level vision contract remains your upstream provider's responsibility. If the model is actually text-only, you'll see the real upstream API error instead of a KodaX-side rejection.

3. Start in REPL or run a one-shot task

# Interactive REPL
kodax

# Then ask naturally inside the REPL
Read package.json and summarize the architecture
/mode
/help

# One-shot CLI usage
kodax "Review this repository and summarize the architecture"
kodax --session review "Find the riskiest parts of src/"
kodax --session review "Give me concrete fix suggestions"

4. Use it as a library

Library usage still expects API keys from environment variables. If you want custom provider names or base URLs in code, register them explicitly:

import { registerCustomProviders, runKodaX } from '@kodax-ai/kodax';

registerCustomProviders([
  {
    name: 'my-openai-compatible',
    protocol: 'openai',
    baseUrl: 'https://example.com/v1',
    apiKeyEnv: 'MY_LLM_API_KEY',
    model: 'my-model',
    userAgentMode: 'compat',
  },
]);

const result = await runKodaX(
  {
    provider: 'my-openai-compatible',
    effort: 'auto',
  },
  'Explain this codebase'
);

Embedding KodaX inside another app? (KodaX Space, IDE extensions, custom CLIs) See docs/SDK_EMBEDDER_GUIDE.md for the runtime-mutation surface (startKodaX + RunningSession), MCP popout manager API (McpManager), Skill !`cmd` host hook, and per-app data dir namespacing (getAppDataDir).

Runtime SDK and daemon

SDK hosts can use @kodax-ai/kodax/runtime in three forms: inline embedded for lowest latency, Worker-hosted embedded for private state plus hard V8 disposal, or a local daemon shared by REPL, Space, IDE adapters, and custom SDK clients. All three expose the same KodaXRuntime services.

import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';

const isolated = await createKodaXRuntime({
  mode: 'embedded',
  isolation: 'worker',
  requirements: { hardDispose: true },
});

Inline is private and lowest-overhead; Worker is private and hard-disposable; daemon is process-isolated and shared. runtime.close() closes private inline/Worker ownership, but only detaches one daemon client. Contradictory isolation options fail instead of silently selecting a weaker mode. Worker isolation is a V8 fault boundary, not a security sandbox.

Because a daemon is intentionally persistent, tests that auto-start one must also run kodax daemon stop --home <dir> --profile <name> (or send authenticated runtime.shutdown) before deleting their temporary home. A remaining Node process is not safe to kill by name alone; verify its command line and owner.

kodax daemon start
kodax daemon stop --profile default
kodax --runtime-mode daemon
kodax -p "Review this repository" --runtime-mode daemon

All CLI task forms now use the same Runtime path: interactive REPL, positional prompts, slash-command prompts, and kodax -p. Select the persistent default in ~/.kodax/config.json:

{
  "runtimeMode": "daemon"
}

Resolution order is explicit CLI/SDK option > environment variable > config.json > built-in default (embedded). KODAX_RUNTIME_MODE=daemon is a temporary environment override. The same rule applies to other paired settings, for example provider ↔ KODAX_PROVIDER and effort ↔ KODAX_EFFORT. JSON names stay camelCase while environment names use KODAX_UPPER_SNAKE_CASE.

By default, daemon state, config, and runtime session storage are scoped under the OS user home directory, so kodax --runtime-mode daemon and SDK clients using createKodaXRuntime({ mode: 'daemon' }) converge on the same local daemon profile. The high-level createKodaXRuntime({ mode: 'daemon' }) API starts or reuses that daemon unless you pass an explicit endpoint/transport or autoStartDaemon: false. Pass --home <dir> or homeDir only when you intentionally want an isolated daemon namespace for tests, CI, or project-local experiments.

v0.7.71 packaged Electron patch: packaged/asar Electron hosts can use daemon auto-start without relaunching the GUI. ELECTRON_RUN_AS_NODE is limited to a bootstrap-only child exec boundary and removed before daemon or ordinary user child code loads. The default-enabled Electron RunAsNode fuse is required; hosts that disable it must start the daemon through ordinary Node/KodaX CLI and connect in attach-only mode. For SDK calls, homeDir is the CLI-style base directory that owns .kodax, not the .kodax path itself.

One daemon owns many sessions. Different sessions may run concurrently; starts within the same session are queued so that only one run is active for that session. Multiple kodax processes can attach to the same daemon and open or observe the same session. FEATURE_269 adds atomic snapshot-plus-stream joining, durable idempotent mutations, revision-safe settings and grants, transport-safe AskUser/permission responses, run-scoped credential and Host Tool bridges, and one daemon/inline Coder owner fence. In-flight external effects are never blindly replayed after a crash; clients receive explicit interrupted/unknown terminal facts and resync when runtimeId changes.

Space and IDE hosts should require these capabilities through the Runtime SDK. Partner remains on its private inline Runtime and must use a distinct product data/session root. A missing daemon capability is an error, not permission to silently fall back to inline Coder.

For the full host-integration contract, including inline/Worker/daemon selection, multi-client permission handling, config/catalog/MCP admin APIs, artifacts, context diagnostics, and daemon protocol schemas, see docs/SDK_EMBEDDER_GUIDE.md §17.

The Space/IDE shared-daemon contract is documented in SDK Embedder Guide section 23.

Repo Intelligence

KodaX ships with built-in repo intelligence (repo_overview, module_context, symbol_context, process_context, impact_estimate, and related tools) that helps the coding agent understand large codebases without ad-hoc grep/glob exploration.

Use /repo-intel status in the REPL to inspect the active engine. The former standalone repointel host skill has been removed; repo intelligence is built into KodaX and requires no external installation.

# Pick a runtime mode (auto | full | light | off)
kodax --repo-intelligence full --repo-intelligence-trace

Architecture

KodaX uses a monorepo architecture with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package @kodax-ai/kodax with 11 SDK subpath exports (/agent, /llm, /coding, /media, /repl, /skills, /mcp, /session, /runtime, /a2a, /experimental-memory; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):

KodaX/
├── packages/                # 4 workspace packages (FEATURE_194 v0.7.43)
│   ├── llm/                 # @kodax-ai/llm - LLM abstraction (15 built-in provider aliases)
│   │   └── providers/       # Anthropic, OpenAI, DeepSeek, Kimi, MiMo, MiniMax, Zhipu, Ark, …
│   │
│   ├── agent/               # @kodax-ai/agent - Generic Agent framework
│   │   ├── orchestration/   # Runner, runFanOut, runWithIdleYield, ChildTaskRegistry
│   │   ├── session-lineage/ # branchable session tree (inline v0.7.43)
│   │   ├── capabilities/
│   │   │   ├── mcp/         # MCP integration (inline v0.7.43)
│   │   │   └── skills/      # Skills standard implementation + builtin (inline v0.7.43)
│   │   └── tracing/         # tracing / observability (inline v0.7.43)
│   │
│   ├── coding/              # @kodax-ai/coding - Coding Agent (tools + prompts)
│   │   ├── tools/           # 50+ tools: read, write, edit, bash, glob, grep, undo,
│   │   │                    #   dispatch_child_task, send_message, task_stop,
│   │   │                    #   ask_user_question, repo-intelligence, …
│   │   └── repo-intelligence/ # incl. protocol.ts (inline v0.7.43)
│   │
│   └── repl/                # @kodax-ai/repl - Interactive terminal UI (Ink TUI)
│
├── src/                     # CLI entry + SDK subpath entries
│   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}
│
└── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports

Package Dependencies

                    ┌──────────────────┐
                    │  kodax (root)    │
                    │  CLI Entry       │
                    └────────┬─────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
              ▼                             ▼
       ┌──────────────┐              ┌────────────────┐
       │@kodax-ai/repl│              │@kodax-ai/coding│
       │  UI Layer    │              │ Tools+Prompts  │
       └──────┬───────┘              └──────┬─────────┘
              │                             │
              │              ┌──────────────┴──────────────┐
              │              │                             │
              ▼              ▼                             ▼
       ┌──────────────┐ ┌──────────────────────────┐ ┌──────────────┐
       │@kodax-ai/    │ │@kodax-ai/agent           │ │@kodax-ai/llm │
       │coding (via   │ │Runner + fan-out +        │ │LLM Abstract  │
       │above)        │ │idle-yield + session-     │ │(15 aliases)  │
       │              │ │lineage + skills + mcp +  │ │              │
       │              │ │tracing (FEATURE_194)     │ │              │
       └──────────────┘ └──────────────────────────┘ └──────────────┘

Package Overview

Source-side workspace package names (@kodax-ai/*). npm consumers install the single bundled @kodax-ai/kodax package and import from SDK subpaths — see Source-side vs npm-published surface and SDK Usage below.

Workspace package	Purpose	Key Dependencies
`@kodax-ai/llm`	LLM abstraction (15 built-in provider aliases + custom registration)	@anthropic-ai/sdk, openai
`@kodax-ai/agent`	Generic Agent framework — Runner, fan-out, idle-yield, media/input artifacts, session-lineage, capabilities (mcp + skills), tracing (ADR-036 v0.7.43 consolidation; subpaths: `/media`, `/session-lineage`, `/capabilities/mcp`, `/capabilities/skills`, `/tracing`)	@kodax-ai/llm, js-tiktoken, fflate, jimp, yaml
`@kodax-ai/coding`	Coding Agent — 50+ tools (incl. `dispatch_child_task` / `send_message` / `task_stop`) + role prompts + auto-continue + repo-intelligence protocol	@kodax-ai/llm, @kodax-ai/agent
`@kodax-ai/repl`	Complete interactive terminal UI (Ink/React, permission modes, commands, streaming)	@kodax-ai/coding, ink, react

Source-side vs npm-published surface

KodaX has two layers that consumers should understand separately:

Source-side: 4 workspace packages above (what developers see when reading the repo).
npm-published: a single bundled package @kodax-ai/kodax with 11 SDK subpaths (what SDK consumers import from). The subpaths are split into two roles:
- Full-package subpaths (/agent, /llm, /coding, /repl) — each one maps 1:1 to a source workspace and exposes its complete public API.
- Integration and narrow subpaths (/media, /skills, /mcp, /session, /runtime, /a2a, /experimental-memory) — focused host surfaces. /a2a composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to /agent.

Source package	npm subpath	Type	What you get	Example consumer
`packages/llm`	`@kodax-ai/kodax/llm`	Full package	15-alias LLM abstraction (108 exports)	Standalone LLM clients
`packages/agent`	`@kodax-ai/kodax/agent`	Full package	Runner / fan-out / external-agent plane / session-lineage / capabilities / tracing (331 exports)	Custom agent frameworks
`packages/agent`	`@kodax-ai/kodax/skills`	Narrow subset	Skills system only — `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` / ... (26 exports = pre-v0.7.43 `@kodax-ai/skills` complete API)	Skill loaders, IDE plugins
`packages/agent`	`@kodax-ai/kodax/mcp`	Narrow subset	MCP only — `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` / ... (23 exports)	MCP server hosts
`packages/agent`	`@kodax-ai/kodax/media`	Narrow subset	Structured image/file/video input-artifact helpers (22 exports)	Desktop hosts and multimodal clients
`packages/agent`	`@kodax-ai/kodax/experimental-memory`	Experimental subset	Thin F228-backed `MemoryAgent` / `MemorySession` contracts for scoped recall, deliberate query, observations, and outcomes	SDK hosts explicitly evaluating FEATURE_260
`packages/coding`	`@kodax-ai/kodax/coding`	Full package	Coding agent + 50+ tools + repo-intelligence (505 exports)	Build a Claude Code-shape product
`packages/repl`	`@kodax-ai/kodax/repl`	Full package	Ink TUI + permission modes + commands (217 exports)	Terminal-UI consumers
`packages/repl`	`@kodax-ai/kodax/session`	Narrow subset	Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports)	IDE plugins and desktop hosts reading session history
`src`	`@kodax-ai/kodax/runtime`	Host API	Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports)	SDK hosts, Space/IDE clients, daemon clients
`src`	`@kodax-ai/kodax/a2a`	Integration edge	A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server	Agent orchestrators and KodaX hosts

Rule of thumb: if you need Runner / Agent / fan-out, import from /agent. If you only need skills or mcp APIs, import from /skills or /mcp to get a smaller bundle. The narrow subsets are subsets of the full packages — they do not expose extra symbols.

Dynamic Workflows (FEATURE_217, v0.7.49): the domain-neutral workflow runtime is part of /agent — import { createWorkflowRuntime, runWorkflow, WorkflowAbortError, WorkflowLimitError } from '@kodax-ai/kodax/agent'. The coding-side integration (agent backend + built-in workflows + saved-workflow discovery/generation: createCodingWorkflowBackend, runWorkflowFromOptions, parallelInvestigation, discoverSavedWorkflows, generateWorkflowFromOptions, …) is part of /coding. FEATURE_217 is the v0.7.49 home for the full Dynamic Workflow product loop: /workflow create <request> generates restricted scripts, /workflow save <runId> <name> stores .workflow.json rerunnable workflows, generated/saved scripts coordinate agents through WorkflowApi, run lifecycle state stays observable, opt-in isolation:"worktree" routes selected children to parent-managed worktrees, and all file/shell effects still pass through agent tools and the existing permission gates. There is no separate @kodax-ai/kodax/agent/workflow root-package subpath; source-package consumers of @kodax-ai/agent can still use that package's ./workflow subpath.

Workflow Process Surface (FEATURE_229, v0.7.50): workflow progress is now a reusable Agent-layer process contract rather than private REPL text. SDK hosts can subscribe to WorkflowProcessEvent/poll WorkflowProcessSnapshot, use createWorkflowRunManager and createWorkflowLifecycleController for stop/pause/resume/result/artifact/delete/prune/identity/preflight controls, and receive ANSI-free provenance fields (source, sourceRunId, sourceWorkflowName, savedWorkflowName, revisionOf) plus resultSummary. /coding owns the coding workflow backend and run graph, /repl renders the same snapshots, and the terminal UI is not the hidden source of truth. KodaXEvents callbacks also take an optional metadata arg (KodaXToolEventMeta / KodaXActivityEventMeta / KodaXWorkflowEventMeta) so a host can attribute every child-agent tool/thinking/progress event to its workflow run and child id without a second event protocol, and generated/saved workflow scripts pass validateRestrictedWorkflowSource (compile + source-policy check) plus a generator repair/smoke loop before they run. See docs/ADR.md ADR-040 for the layering rationale.

Host Reads Persisted History (FEATURE_230 + FEATURE_234, v0.7.51; v0.7.63 hardening): additive closures for hosts that read persisted state. Durable tool transcript replay — a resumed session now replays the tool cards the assistant used instead of degrading to text-only. messages / lineage stay canonical; SessionData.uiHistory becomes a bounded, sanitized, terminal-only replay cache. The SDK transcript contract is explicit: loadSession() = active model context, loadFullTranscript() = append-order host scrollback with typed entries (message / compaction / branch_summary / rewind_marker / client_notice / task_result) plus clone provenance (logicalId / sourceEntryId), uiHistory = optional replay cache, and tool cards can always be reconstructed from canonical messages. Hosts can persist local slash output with appendClientNotice() without entering model context, and workflow/child completions expose structured taskResults[] instead of requiring <task-completed> parsing. rewind_marker is an audit entry for host scrollback only and is excluded from model-context messages. Workflow run host attribution — WorkflowProcessTrackerOptions / WorkflowProcessSnapshot gain a host-owned opaque hostMetadata?: Record<string, string> that the SDK stores, persists to run.json, and echoes back (including after a restart) without interpreting it, so a host can map a run to the session/surface that launched it with zero side table. Unstamped/legacy runs honestly echo hostMetadata === undefined. See docs/features/v0.7.51.md.

Inline Workflow Authoring (FEATURE_246, v0.7.58): in AMA/AMAW the Worker can now author and run a workflow inline via a model-callable run_workflow tool — it scouts the codebase with its own tools first, then bakes concrete findings into each child prompt, and runs the script through the unchanged sandbox + static-validation + postcondition-verification pipeline. This replaces the context-blind sideQuery generator as the primary interactive path (the generator survives only as a fallback for the explicit /workflow create command and non-interactive / CI hosts that have no investigating Worker). It adds structured child output (outputSchema), the no-barrier wf.pipeline staged primitive, same-session resume (resumeFromRunId), nested wf.workflow(...), and a /workflow create redirect to Worker-authored scouting; run_workflow is async / idle-yield so the turn is not blocked. The neutral run-lifecycle manager (createWorkflowRunManager / getDefaultWorkflowRunManager) now lives in @kodax-ai/kodax/agent for non-coding SDK hosts. See docs/features/v0.7.58.md and docs/ADR.md ADR-044/046/047/048/049.

Workflow Activation Tiers (FEATURE_248 + FEATURE_249, v0.7.59): the three agent modes now have a coherent workflow posture. AMAW carries a mode-level ORCHESTRATION DEFAULT standing directive (mirroring the reference "ultracode" posture): substantive work — a multi-file investigation, a design decision, anything costly to get wrong — defaults to orchestrating multiple cross-checking agents, with a PLAN-TIME COMMITMENT flow-fix that front-loads the orchestrate-vs-solo call to turn 0. AMA hosts the same run_workflow tool but with no standing directive — it activates a workflow when you ask for orchestration in natural language, never on complexity alone. SA stays solo. The directive is leak-closed via amawOrchestrationAvailable, so AMA and SA prompts stay byte-identical. See docs/features/v0.7.59.md.

Progressive Disclosure on the Managed Tool Path (FEATURE_250, v0.7.60): the deferred-tool progressive-disclosure mechanism — previously SA-path-only — now applies to the AMA/AMAW managed path too. Cache-cold managed turns carry one-line search hints instead of full descriptions for the 13 non-mcp deferred tools (repo-intelligence + web/code + goal); each tool's input_schema is unchanged, so it stays directly callable and the full description is fetched on demand via tool_search. mcp_* stay resident and run_workflow is untouched. Transparent to users; validated by two 5-alias eval panels (DEFER_SAFE 5/5, 0% read/grep fallback). See docs/features/v0.7.60.md.

Context-Efficient Tool Results + Workflow Quality Preflight (FEATURE_251 + FEATURE_252, v0.7.61; corrected 2026-07-14): local tools collect complete output and apply only contract-equivalent normalization that is strictly shorter; command-specific lossy Bash filters are off by default, and compound Bash uses no semantic adapter. One owner evaluates the complete parallel-result batch against the final provider request: it solves the largest final input Pmax for which Pmax + output reserve + max(2048, 3% of Pmax) <= context window, then admits only the remaining physical capacity. Results stay verbatim whenever they fit; only real overflow persists the complete value and emits KODAX_RESULT_INCOMPLETE. History follows the same physical-capacity rule: no default lossy microcompaction below capacity, summary-first at actual pressure, and typed failure without silent message deletion when a recoverable request cannot be formed. Static early percentages are explicit opt-ins. FEATURE_252's deterministic pre-start workflow contract lint is unchanged. See docs/features/v0.7.61.md and docs/ADR.md ADR-050.

External Agent SDK Plane (FEATURE_258, v0.7.67): /agent exports the protocol-neutral executor, registration, policy, credential-broker, artifact-policy, catalog, and durable task contracts. /runtime exposes the installed plane through admin.agentRegistrations, agents, and agentTasks, with the same DTO service methods over embedded and daemon clients. Executor factories are host functions: install them in an inline owner or while creating a new in-process daemon owner; they cannot be injected through an existing daemon connection or across a Runtime Worker boundary. Plane shutdown is terminal: pending waits and all later service calls reject. Restricted Workflow scripts preserve validated phase and external target routing. See the complete owner/consumer recipes and safety contract.

Cost-Disciplined Workflow SDK (FEATURE_259, v0.7.67): SDK callers configure run-scoped modelTiers and workflow.maxConcurrency, while workflow authors express semantic fast / balanced / deep intent. Terminal workflow events expose resolved tier/source/fallback/usage/duration facts, and each durable run.json contains an efficiencyReport with token coverage, role/tier starts, packet-read topology, review waves, and quality-gate outcomes. See the routing and telemetry contract.

Paged Session Listing (FEATURE_261, v0.7.67): both /session listSessions() and runtime.sessions.list() accept an exact surface filter and opaque continuation cursor; each returned summary carries the cursor for the next page. Filtering happens before the page limit, so a host does not need to over-fetch mixed surfaces. See the pagination recipes.

Experimental Memory Agent SDK (FEATURE_260, v0.7.68): /experimental-memory exposes the thin agent-layer MemoryAgent and scoped MemorySession lifecycle over the existing governed F228 plane. Passive recall is zero-wait; query() is read-only and deliberate; durable changes still require the proposal/preview/fingerprint/apply path. The Action LLM remains the final decision maker, recalled content stays low-authority, and safety/scope gates remain deterministic. See the direct session and boundary guide.

Bidirectional A2A 1.0 (FEATURE_267, v0.7.69): /a2a discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as external:<name> in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. The same module can publish the Runtime default or one validated ~/.kodax/agents/*.md Agent behind an authenticated Runtime facade. The built-in listener is loopback-only; public deployment uses handle() behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the client/server recipes and security boundaries.

v0.7.70 interoperability hardening keeps a discovered A2A interface on the trusted Agent Card origin and sends a credential only when the Card advertises Bearer authentication. a2a serve now resolves its provider from CLI, then environment, config, and the built-in default; a Markdown Agent can pin its own provider. Input continuation resumes the original Runtime run, task history and retention are bounded with stable cursor pagination, and authenticated SSE is correlated before falling back to polling after an early normal EOF. Only direct remote artifacts, broker-staged outputs, and outputs from a successfully admitted Skill script can be published; ordinary workspace writes and local paths stay private.

v0.7.70 MCP discovery hardening uses exact capability IDs and revisioned cursors while admitting results against real physical capacity. Compact CJK queries are segmented, and a cross-language lexical zero match either returns a lossless bounded grouped inventory or one concise retry in the catalog language. Partial provider failure remains explicit rather than disappearing into an apparently complete result.

The complete built-in path is available without writing TypeScript:

# Call another A2A Agent
kodax a2a add research https://agent.example/.well-known/agent-card.json --effect read
kodax a2a test research
kodax a2a call research "Summarize this topic"

# Expose the Runtime default Agent, or pass a name from ~/.kodax/agents/*.md
export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
kodax a2a expose                 # or: kodax a2a expose document-agent
kodax a2a serve                  # loopback http://127.0.0.1:8765

MCP, A2A, and Extension declarations live in one user file per domain under ~/.kodax/integrations/. Use kodax config template <mcp|a2a|extensions>, kodax integrations migrate --apply, and the kodax mcp, kodax a2a, or kodax extensions commands to manage them. Migration imports only legacy config.json#mcpServers and config.json#extensions; A2A has no legacy source. It never overwrites an existing destination. The first MCP/Extension mutation can stage legacy entries. Remove legacy keys only with --apply --cleanup-legacy, after reviewing destination files and literal-secret warnings. Running CLI/daemon hosts retain the last valid revision, atomically replace the complete MCP provider, reconcile Extensions per entry, and hot-register outbound A2A Agents. a2a serve loads its configured MCP/Extension capability surface before listening and pins that execution authority; it hot-reloads publication, authentication, and limits. Agent, Skill, Extension-tool authority, workspace, tool-policy, or task-store changes require an explicit server restart. Managed A2A contexts default to ~/kodax_a2a_server_workspace/<profile>/contexts/. Exact Skill scripts require the opt-in isolated policy and a passing kodax sandbox doctor (kodax sandbox setup performs the explicit Windows one-time provisioning).

Features

Modular Architecture - Use as CLI, as a library, or as a Node-free single binary
15 Built-in Provider Aliases - Anthropic, OpenAI, DeepSeek, Kimi, Kimi Code, Qwen, Zhipu, Zhipu Coding, Zai Coding, MiniMax Coding, MiMo Coding, MiMo, Ark Coding, Gemini CLI, Codex CLI - plus user-defined OpenAI/Anthropic-compatible providers
Dynamic Workflows + SDK Process Surface - Generate/reuse capability-routed workflows, observe live progress through WorkflowProcessSnapshot, and control workflow lifecycle from SDK hosts without parsing REPL output
V2 Worker single-loop + Sidecar Verifier (default) - Single-agent main loop with an out-of-band Sidecar Verifier as Stop-hook (claudecode-shape; FEATURE_184 v0.7.42, ADR-030). Verifier returns accept/revise/blocked verdict on Worker text-only termination. The pre-v0.7.43 V1 chain is retired, emit_handoff is deleted, accept-verdict UI silently passes through, and content-aware gating skips trivial-chat sidecar calls. Async child steering uses dispatch_child_task + send_message + task_stop with idle-yield wait; specialist routing uses subagent_type.
Reasoning Effort - Effort-first control (off/auto/low/medium/high plus model-supported extras) across providers
Streaming Output - Real-time response display
Session Management - JSONL format with branchable session lineage tree
Skills System - Natural language triggering, extensible, role-projected in AMA
Repo Intelligence - Built-in full/light repository intelligence with native KodaX auto-injection lane
Rich Tool Surface - 50+ built-in tools across file ops, shell, search, repo intelligence, MCP capabilities, git worktree, and agent control
Permission Control - 3 permission modes with pattern-based control
Standalone Binary - bun --compile releases for Win/macOS/Linux x64+arm64, no Node.js required on target machines
Cross-Platform - Windows/macOS/Linux
TypeScript Native - Full type safety and IDE support

Installation

As CLI Tool

# Clone repository
git clone https://github.com/icetomoyo/KodaX.git
cd KodaX

# Install dependencies (includes workspace packages)
npm install

# Build the monorepo
npm run build

# Link globally (development mode)
npm link

# Now you can use 'kodax' anywhere
kodax "your task"

As Standalone Binary (no Node required on target)

KodaX can be packaged into a single executable + a small builtin/ sidecar directory using bun --compile. The target machine does not need Node.js or any other runtime.

Supported targets: win-x64, linux-x64, linux-arm64, darwin-x64, darwin-arm64. Win7 / pre-glibc-2.27 distros / LoongArch are not supported.

Build locally:

# Install Bun once on your build machine
npm i -g bun                  # or scoop/brew/curl install — see docs/release.md

npm run build:binary          # Current host platform (fastest)
npm run build:binary:all      # All five targets in sequence
node scripts/build-binary.mjs --target=linux-arm64   # Specific target

Output lives under dist/binary/<target>/:

dist/binary/linux-x64/
├── kodax                          # ~60 MB Bun-compiled executable
├── builtin/                       # Sidecar built-in skills
├── provider-capabilities.json
├── semantic-worker.js             # Repo-intelligence Worker
├── runtime-worker.js              # SDK Runtime Worker
└── constructed-handler-worker.js  # Constructed-tool Worker

Smoke-test: dist/binary/<host>/kodax --version.

Automated release: pushing a v* git tag triggers .github/workflows/release.yml, which builds all five targets on native runners, runs smoke tests, and publishes a GitHub Release with archives + SHA256SUMS. Use the workflow_dispatch button in the Actions UI to test the pipeline without tagging.

See docs/release.md for full details on build flags, archive layout, troubleshooting, and the build-time KODAX_BUNDLED / KODAX_VERSION defines.

As Library

npm install @kodax-ai/kodax

import { runKodaX } from '@kodax-ai/kodax';

process.env.ZHIPU_API_KEY = process.env.ZHIPU_API_KEY ?? 'your_api_key';

const result = await runKodaX({
  provider: 'zhipu-coding',
  effort: 'auto',
  events: {
    onTextDelta: (text) => process.stdout.write(text),
    onComplete: () => console.log('\nDone!'),
  },
}, 'your task');

console.log(result.lastText);

SDK Subpath Imports (v0.7.39+)

For smaller surface and tree-shake-friendly imports, the SDK is also exposed via subpath exports — pick only the package(s) you need:

import { Runner } from '@kodax-ai/kodax/agent';                // agent runtime
import { getProvider } from '@kodax-ai/kodax/llm';              // LLM abstraction (15 aliases)
import { runKodaX } from '@kodax-ai/kodax/coding';              // coding tools + prompts
import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifacts
import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config / session helpers
import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client/server edge

All 12 SDK entries (root + 11 subpaths) share internal code via ESM chunk splitting — importing from /agent does not pull in /repl's Ink + React surface.

For the complete host-facing contract — including embedded/Worker/daemon ownership, external-agent registration and task control, session cursor pagination, workflow model-tier routing, and efficiency telemetry — see the SDK Embedder Integration Guide.

ESM-only. The SDK is published as ES Modules. In a CommonJS context (Electron main process, legacy Webpack CJS bundles, require()-based code) you must use await import(...) instead of require(). See docs/SDK_EMBEDDER_GUIDE.md §5 for the canonical recipe + the technical reason most subpaths cannot ship a dual ESM/CJS build.

For CLI users, provider defaults live in ~/.kodax/config.json. For library users, API keys are still read from environment variables; if you need custom base URLs or provider aliases, use registerCustomProviders() as shown above.

Usage

REPL Quickstart

Running kodax with no prompt starts the interactive REPL.

kodax

Inside the REPL you can type normal requests or slash commands:

Read package.json and summarize the architecture
/model
/mode
/help

CLI Quickstart

# Set API key
export ZHIPU_API_KEY=your_api_key

# Basic usage
kodax "Help me create a TypeScript project"

# Choose a provider explicitly
kodax --provider openai --model gpt-5.4 "Create a REST API"

# Use higher reasoning effort
kodax --effort high "Review this architecture"

Session Workflows

Use a session when you want memory across turns. Without a session, each CLI call is independent.

# No memory: two separate calls
kodax "Read src/auth.ts"
kodax "Summarize it"

# With memory: same session
kodax --session my-project "Read package.json"
kodax --session my-project "Summarize it"
kodax --session my-project "How should I fix the first issue?"

# Session management
kodax -r                    # Search, page, and select a non-empty session
kodax -r <session-id>       # Resume a known session directly
kodax -r "Review runtime"   # Resume a unique exact title; duplicates open the picker
kodax --session list        # List up to 50 non-empty sessions
kodax --session cleanup-acp # Preview strictly matched empty ACP-test pollution

Bare -r opens an interactive picker with incremental search, arrow/PageUp/PageDown navigation, Tab completion, full selected-session ID display, and Enter-to-resume. An explicit value checks the complete session ID first, then an exact case-insensitive title; duplicate titles open a narrowed picker instead of silently choosing one. Cleanup is preview-only unless --apply-session-cleanup is also provided; matching sessions are archived rather than permanently deleted.

Session Patterns

# ❌ No memory: two independent calls
kodax "Read src/auth.ts"           # Agent reads and responds
kodax "Summarize it"               # Agent doesn't know what to summarize

# ✅ With memory: same session
kodax --session auth-review "Read src/auth.ts"
kodax --session auth-review "Summarize it"        # Agent knows to summarize auth.ts
kodax --session auth-review "How to fix first issue"  # Agent has context

Workflow Examples

# Code review (multi-turn conversation)
kodax --session review "Review src/ directory"
kodax --session review "Focus on security issues"
kodax --session review "Give me fix suggestions"

# Project development (continuous session)
kodax --session todo-app "Create a Todo application"
kodax --session todo-app "Add delete functionality"
kodax --session todo-app "Write tests"

CLI Reference

kodax                    Start the interactive REPL
-h, --help [topic]   Show help or topic help
-p, --print <text>   Run a single task and exit
-c, --continue       Continue the most recent conversation in this directory
-r, --resume [value] Resume by ID/exact title, or open the searchable picker
-m, --provider       Provider to use
--model <name>       Override the model
--reasoning <mode>   off | auto | quick | balanced | deep
-t, --thinking       Compatibility alias for --reasoning auto
-s, --session <op>   Session ID or legacy session operation
-j, --parallel       Enable parallel tool execution
--max-iter <n>       Max iterations

Permission Control

KodaX provides 3 permission modes for fine-grained control:

Mode	Description	Tools Need Confirmation
`plan`	Read-only planning mode	All modification tools blocked
`accept-edits`	Auto-accept file edits	bash only
`auto-in-project`	Full auto within project	None (project-scoped)

# In REPL, use /mode command
/mode plan          # Switch to plan mode (read-only)
/mode accept-edits  # Switch to accept-edits mode
/mode auto-in-project  # Switch to auto-in-project mode
/auto                  # Alias for auto-in-project

# Check current mode
/mode

Features:

In accept-edits mode, choosing "always" can persist safe Bash allow-patterns
Plan mode includes system prompt context for LLM awareness
Permanent protection zones: .kodax/, ~/.kodax/, paths outside project
Pattern-based permission: Allow specific Bash commands (e.g., Bash(npm install))
Unified diff display for write/edit operations

CLI Help Topics

Get detailed help for specific topics:

# Basic help
kodax -h
kodax --help

# Detailed topic help
kodax -h sessions      # Session management details
kodax -h init          # Long-running project initialization
kodax -h project       # Project mode / harness workflow
kodax -h auto          # Auto-continue mode
kodax -h provider      # LLM provider configuration
kodax -h thinking      # Thinking/reasoning effort and compatibility modes
kodax -h team          # Multi-agent parallel execution
kodax -h print         # Print configuration

Environment Variables

KodaX recognizes a number of environment variables for tuning runtime behavior. The most commonly used ones are listed below; for the full list, search the repo for process.env.KODAX_.

`KODAX_MAX_OUTPUT_TOKENS`

Overrides the per-turn max_tokens value sent to every provider (Anthropic, OpenAI, Zhipu, Kimi, MiniMax, Qwen, DeepSeek, MiMo, Gemini, Codex, …). Set to a positive integer; unset or non-numeric values are ignored. This is an explicit user intent: when set, it wins over the provider's model descriptor cap, over the provider config default, and over the global KODAX_MAX_TOKENS fallback. RST defense is handled at the provider config layer (streamMaxDurationMs watchdog + non-streaming fallback in packages/llm/src/providers/registry.ts), so this variable is purely an output-budget knob.

# Allow up to 48K output tokens per turn (use a higher cap when generating long files)
export KODAX_MAX_OUTPUT_TOKENS=48000
kodax "generate the full implementation"

# Unset to restore default behavior
unset KODAX_MAX_OUTPUT_TOKENS

Precedence used by every provider's getEffectiveMaxOutputTokens() (see packages/llm/src/providers/base.ts):

One-shot per-request override (agent-loop escalation / context-overflow recovery — internal)
KODAX_MAX_OUTPUT_TOKENS (this variable, explicit user intent)
Active model descriptor's maxOutputTokens (FEATURE_098 per-model cap)
Provider config default
Global KODAX_MAX_TOKENS fallback

Related variables: KODAX_MAX_TOKENS (global fallback when no provider/model cap applies), KODAX_ESCALATED_MAX_OUTPUT_TOKENS (escalation budget used by the agent loop when a turn returns stop_reason: max_tokens).

Retired in v0.7.42: KODAX_RST_PRONE_PROVIDERS and KODAX_WRITE_TURN_MAX_TOKENS (the v0.7.28 P2b write-turn cap mechanism) are no longer recognized. The 2026-04 bench measured RST as time-based (zhipu-coding 308s server kill window), not payload-size-based, so the cap was retired in favor of the per-provider streamMaxDurationMs watchdog + non-streaming fallback chain (configured in registry.ts). Existing env exports become silent no-ops; remove them from shell profiles when convenient.

Sidecar verifier diagnostics

Use these when diagnosing Worker text-only completion stalls or custom provider verifier behavior:

export KODAX_VERIFIER_LOG=1
export KODAX_VERIFIER_PROVIDER=anthropic
export KODAX_VERIFIER_MODEL=claude-haiku-4-5-20251001

KODAX_VERIFIER_LOG=1 shows verifier gate/elapsed/trace information and is equivalent to "verifierLog": true in ~/.kodax/config.json.
KODAX_VERIFIER_PROVIDER + KODAX_VERIFIER_MODEL route the verifier to a separate provider/model instead of inheriting the main Worker model. Set both together.
KODAX_VERIFIER_ALWAYS=1 forces the verifier to fire on every text-only completion for debugging/regression sweeps.

SDK/headless hosts can observe actionable Sidecar Verifier messages via KodaXEvents.onSidecarMessage; JSONL output emits the same payload as sidecar.message. Only revise and blocked verdicts are surfaced; accept stays silent.

Advanced Library Usage

Simple Mode (runKodaX)

import { runKodaX, KodaXEvents } from '@kodax-ai/kodax';

const events: KodaXEvents = {
  onTextDelta: (text) => process.stdout.write(text),
  onThinkingDelta: (text) => console.log(`Thinking delta: ${text.length} chars`),
  onToolResult: (result) => console.log(`Tool ${result.name}: ${result.content.slice(0, 100)}`),
  onSidecarMessage: (event) => console.log(`[sidecar:${event.verdict}] ${event.content}`),
  onComplete: () => console.log('\nDone!'),
  onError: (e) => console.error(e.message),
};

const result = await runKodaX({
  provider: 'zhipu-coding',
  effort: 'auto',
  events,
}, 'What is 1+1?');

console.log(result.lastText);

Continuous Session (KodaXClient)

import { KodaXClient } from '@kodax-ai/kodax';

const client = new KodaXClient({
  provider: 'zhipu-coding',
  effort: 'auto',
  events: {
    onTextDelta: (t) => process.stdout.write(t),
  },
});

// First message
await client.send('Read package.json');

// Continue same session
await client.send('Summarize it');

console.log(client.getSessionId());

Custom Session Storage

import { runKodaX, KodaXSessionStorage, KodaXMessage } from '@kodax-ai/kodax';

class MyDatabaseStorage implements KodaXSessionStorage {
  async save(id: string, data: { messages: KodaXMessage[]; title: string; gitRoot: string }) {
    // Save to your database
  }
  async load(id: string) {
    // Load from your database
    return null;
  }
}

await runKodaX({
  provider: 'zhipu-coding',
  session: {
    id: 'my-session-123',
    storage: new MyDatabaseStorage(),
  },
  events: { ... },
}, 'task');

Library Modes Comparison

Feature	runKodaX	KodaXClient
Message Memory	❌ No	✅ Yes
Call Style	Function	Class instance
Context	Independent each time	Accumulates
Use Case	Single tasks, batch processing	Interactive dialogue, multi-step tasks

SDK Usage

KodaX ships as a single npm package @kodax-ai/kodax with 11 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 /media + v0.7.64 /runtime + v0.7.68 /experimental-memory + v0.7.69 /a2a). Each subpath is tree-shake-friendly so consumers pull only what they need:

npm install @kodax-ai/kodax

import { runKodaX } from '@kodax-ai/kodax';                       // root: CLI helpers + runKodaX
import { Runner, runFanOut } from '@kodax-ai/kodax/agent';        // generic Agent framework
import { getProvider } from '@kodax-ai/kodax/llm';                // 15-alias LLM abstraction
import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + prompts + agent loop
import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifact helpers
import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';     // Ink TUI entrypoint
import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep skill loader
import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 client/server edge
import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in experimental memory SDK

The SDK is ESM-only. CommonJS consumers (Electron main / Webpack CJS / require() callers) must use await import('@kodax-ai/kodax/...') — see docs/SDK_EMBEDDER_GUIDE.md §5.

`@kodax-ai/kodax/llm` — LLM Abstraction

15 built-in provider aliases (Anthropic, OpenAI, DeepSeek, Kimi, Kimi-Code, Qwen, Zhipu, Zhipu-Coding, Zai-Coding, MiniMax-Coding, MiMo, MiMo-Coding, Ark-Coding, Gemini-CLI, Codex-CLI) + custom provider registration.

import { getProvider, KodaXBaseProvider } from '@kodax-ai/kodax/llm';

const provider = getProvider('anthropic');
const stream = await provider.streamCompletion(
  [{ role: 'user', content: 'Hello!' }],
  { onTextDelta: (text) => process.stdout.write(text) }
);

for await (const result of stream) {
  if (result.type === 'text') { /* … */ }
  else if (result.type === 'tool_use') { /* … */ }
}

Key Features: unified provider interface · streaming · reasoning effort (off/auto/low/medium/high plus model-supported extras) · per-provider retry + error handling · zero business-logic dependencies.

`@kodax-ai/kodax/agent` — Agent Framework (standalone-consumable)

ADR-021 standalone-consumable: @kodax-ai/agent has zero inbound @kodax-ai/coding dependency — you can wire any tool surface on top of it.

import {
  Runner,
  runFanOut,
  runWithIdleYield,
  registerChildTask,
  type ChildTaskRegistry,
  generateSessionId,
  estimateTokens,
  DefaultSummaryCompaction,
} from '@kodax-ai/kodax/agent';

// Bounded-concurrency fan-out with abort + structured progress events (v0.7.39 FEATURE_120)
const result = await runFanOut({
  bundles: [{ id: 'a', task: 'audit-foo' }, { id: 'b', task: 'audit-bar' }],
  maxParallel: 4,
  run: async (bundle) => doWork(bundle),
});

// Idle-yield wait — pause when out of useful work, resume when a wake event arrives
await runWithIdleYield({ runOnce, computeSnapshot, registry, messageQueue, agentId });

// Pluggable compaction policy (FEATURE_081)
const policy = new DefaultSummaryCompaction({ thresholdRatio: 0.8, keepRecent: 10 });

Key Features: Runner + per-step lifecycle · runFanOut (bounded-concurrency + abort + progress events) · runWithIdleYield (chat-while-waiting) · ChildTaskRegistry / TaskAbortRegistry · session-id generation · tiktoken-based token estimation · CompactionPolicy interface.

`@kodax-ai/kodax/skills` — Skills System

Zero external dependencies. Markdown-based skill files with natural-language triggers and variable resolution.

import {
  SkillRegistry,
  discoverSkills,
  executeSkill,
  type SkillContext,
} from '@kodax-ai/kodax/skills';

const skills = await discoverSkills(['/path/to/skills']);
const registry = new SkillRegistry();
await registry.registerSkills(skills);

const result = await executeSkill({
  skillId: 'code-review',
  arguments: { target: 'src/' },
  workingDirectory: process.cwd(),
});

Key Features: zero deps · markdown-based skill files · natural-language triggering · variable resolution · built-in skills included.

`@kodax-ai/kodax/coding` — Coding Agent

Complete coding agent: 50+ tools (read/write/edit/bash/grep/glob/dispatch_child_task/send_message/task_stop/...) + Worker role prompt + Sidecar Verifier (out-of-band Stop-hook) + agent loop + auto-continue + session management.

import { runKodaX, KodaXClient, KODAX_TOOLS } from '@kodax-ai/kodax/coding';

// Single-task helper
const result = await runKodaX({
  provider: 'zhipu-coding',
  effort: 'auto',
  events: { onTextDelta: (text) => process.stdout.write(text) },
}, 'Read package.json and explain the dependencies');

// Continuous session
const client = new KodaXClient({
  provider: 'anthropic',
  effort: 'auto',
  events: { /* … */ },
});
await client.send('Create a new file');
await client.send('Add a function to it'); // Has context from previous message

Key Features: 50+ built-in tools (see Tools) · V2 Worker single-loop + Sidecar Verifier (FEATURE_184 v0.7.42 / V1 chain fully retired by FEATURE_193 v0.7.43) · async child steering via send_message / task_stop (FEATURE_120, v0.7.39) · idle-yield wait mechanic (FEATURE_155, v0.7.38) · specialist routing via subagent_type (FEATURE_191, v0.7.43) · auto-continue · session lineage.

`@kodax-ai/kodax/repl` — Interactive Terminal UI

Ink/React-based interactive REPL. Permission modes, command system, themed streaming display.

import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';

// Usually used via the `kodax` bin command; can be embedded:
// - Interactive terminal UI (Ink components)
// - Permission control (auto/plan/accept-edits modes)
// - Command system (/help, /mode, /clear, /status, …)
// - Skills integration
// - Theme support
await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });

Key Features: Ink-based React components · 3 permission modes (auto / plan / accept-edits) · built-in commands · real-time streaming display · context-usage indicator.

Package Dependency Graph (workspace internal)

@kodax-ai/llm    (zero business-logic deps)
    ↓
@kodax-ai/agent  (depends @kodax-ai/llm; ADR-021 standalone-consumable;
                  inlines session-lineage + capabilities/{mcp,skills} +
                  tracing per ADR-036 v0.7.43)
    ↓
@kodax-ai/coding (depends llm + agent; inlines repo-intelligence/protocol per ADR-036)
    ↓
@kodax-ai/repl   (depends coding + ink + react)

Subpath Recommendations:

Use Case	Subpath	Why
Only need LLM abstraction	`@kodax-ai/kodax/llm`	Minimal deps; 15 built-in aliases
Building custom agent	`@kodax-ai/kodax/agent`	Runner + fan-out + idle-yield + session-lineage + capabilities
Coding tasks	`@kodax-ai/kodax/coding`	Complete coding agent + tools
Terminal app	`@kodax-ai/kodax/repl`	Full interactive experience
Runtime host / daemon client	`@kodax-ai/kodax/runtime`	Sessions, runs, events, permissions, catalog, MCP, artifacts, diagnostics
Experimental governed memory	`@kodax-ai/kodax/experimental-memory`	Scoped `MemoryAgent` / `MemorySession` recall and outcome contracts

Provider	Environment Variable	Reasoning Support	Default Model
anthropic	`ANTHROPIC_API_KEY`	Native	claude-sonnet-4-6 (`claude-opus-4-6` / `claude-haiku-4-5` via `/model`)
openai	`OPENAI_API_KEY`	Native	gpt-5.3-codex (`gpt-5.4` / `gpt-5.3-codex-spark` via `/model`)
kimi	`KIMI_API_KEY`	Native	kimi-k2.6 (`kimi-k2.7-code` 256K / `k2.5` via `/model`)
kimi-code	`KIMI_CODE_API_KEY`	Native	kimi-for-coding
qwen	`QWEN_API_KEY`	Native	qwen3.5-plus
zhipu	`ZHIPU_API_KEY`	Native	glm-5 (`glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo` via `/model`)
zhipu-coding	`ZHIPU_CODING_API_KEY`	Native	glm-5 (`glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo` via `/model`)
zai-coding	`ZAI_CODING_API_KEY`	Native	glm-5.2 (Zhipu Coding Plan overseas mirror via `api.z.ai`, Anthropic-compat — same model lineup as `zhipu-coding`, served from outside CN)
minimax-coding	`MINIMAX_CODING_API_KEY`	Native	MiniMax-M2.7 (`MiniMax-M3` Frontier Coding, native multimodal + 1M ctx, plus `MiniMax-M2.7-highspeed` via `/model`)
mimo	`MIMO_API_KEY`	Native	mimo-v2.5-pro (Xiaomi MiMo pay-per-token, Anthropic-compat)
mimo-coding	`MIMO_CODING_API_KEY`	Native	mimo-v2.5-pro (Xiaomi Token Plan, Anthropic-compat)
ark-coding	`ARK_CODING_API_KEY`	Native	glm-5.2 (Volcengine Ark Coding Plan — GLM-5.2 (alias: `glm-latest`) · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code)
deepseek	`DEEPSEEK_API_KEY`	Native	deepseek-v4-flash (`deepseek-v4-pro` via `/model`)
gemini-cli	`GEMINI_API_KEY`	Prompt-only / CLI bridge	(via gemini CLI)
codex-cli	`OPENAI_API_KEY`	Prompt-only / CLI bridge	(via codex CLI)

Custom providers: any OpenAI- or Anthropic-compatible endpoint can be added via customProviders[] in ~/.kodax/config.json (CLI) or registerCustomProviders() (library). See the Quick Start for the configuration shape.

Examples

# Use Zhipu Coding
kodax --provider zhipu-coding --thinking "Help me optimize this code"

# Use OpenAI
export OPENAI_API_KEY=your_key
kodax --provider openai "Create a REST API"

# Resume last session
kodax --session resume

# List all sessions
kodax --session list

# Parallel tool execution
kodax --parallel "Read package.json and tsconfig.json"

# Adaptive multi-agent (AMA) mode — V2 Worker single-loop with `dispatch_child_task` fan-out
kodax --agent-mode ama "Analyze code structure, check test coverage, find bugs"

Tools

KodaX ships 50+ built-in tools, grouped below. They are registered as a single flat tool surface to the LLM; the categories here are just for navigation.

File operations

Tool	Description
`read`	Read file contents (supports offset/limit)
`write`	Write a new file or fully rewrite an existing one
`edit`	Exact string replacement (supports `replace_all`)
`multi_edit`	Atomic batch of independent edits to one file
`insert_after_anchor`	Insert content after a unique anchor without rewriting the file
`undo`	Revert the last file modification

Shell & search

Tool	Description
`bash`	Execute a shell command (supports `run_in_background`; complete capture with recoverable capacity fallback)
`glob`	Find files by pattern
`grep`	Regex content search (context lines, multiline, file-type filter, pagination)
`code_search`	Lower-noise code search (extension-provider aware)
`semantic_lookup`	Symbol/module/process-aware search backed by repo intelligence
`web_search`	Discovery-oriented web search with trust + freshness signals
`web_fetch`	Fetch a specific URL with provenance hints

Repo Intelligence (working tools)

Tool	Description
`repo_overview`	Summarize structure, key areas, entry hints, intelligence snapshot
`changed_scope`	Which files/areas/categories the current diff touches
`changed_diff`	Paged diff slice for a single file
`changed_diff_bundle`	Paged diff slices for multiple files in one call
`module_context`	Module capsule (deps, entries, symbols, tests, docs)
`symbol_context`	Definition + probable callers/callees + alternatives
`process_context`	Approximate static execution capsule for an entry
`impact_estimate`	Blast radius for a symbol/path/module

MCP capabilities (when MCP servers are configured)

Tool	Description
`mcp_search` / `mcp_describe` / `mcp_call`	Discover and invoke MCP tools through the shared capability runtime
`mcp_read_resource` / `mcp_get_prompt`	Read MCP resources and prompts

Git worktree

Tool	Description
`worktree_create`	Create a new worktree on an isolated branch for safe agent work
`worktree_remove`	Remove a worktree (with safety checks)

Agent control & UX

Tool	Description
`dispatch_child_task`	Spawn a sub-agent for an independent investigation/edit task. Optional `model_hint: 'fast' \| 'balanced' \| 'deep'` (advisory; routing no-op until FEATURE_102 v0.7.45).
`send_message`	Append an instruction to an in-flight child's queue — surfaces as `<coordinator-instruction>` at the child's next turn boundary. Coordinator-only. (FEATURE_120, v0.7.39)
`task_stop`	Request graceful exit of a specific child. Current tool finishes atomically, then the child sees a `<coordinator-stop-request>` and emits a final summary. Coordinator-only. (FEATURE_120, v0.7.39)
`ask_user_question`	Single/multi-select or free-text prompt back to the user
`exit_plan_mode`	Present a finalized plan for approval (REPL only)
`run_workflow`	Author and run a workflow script inline. Hosted in AMAW (self-activates on complexity via the ORCHESTRATION DEFAULT directive) and AMA (activates on an explicit natural-language request); not in SA. Scouts the codebase first, then bakes findings into child prompts; structured output via `outputSchema`, same-session `resumeFromRunId`, nested `wf.workflow(...)`. Async / idle-yield. (FEATURE_246 v0.7.58; FEATURE_248/249 v0.7.59)
`emit_managed_protocol`	Internal managed-task protocol side-channel for role payloads (verdict). V2 Worker single-loop + Sidecar Verifier is the default since v0.7.42 (FEATURE_184); V1 chain retired in v0.7.43 (FEATURE_193).

Skills System

KodaX includes a built-in Skills system that can be triggered by natural language:

# Natural language triggering (no explicit /skill needed)
kodax "帮我审查代码"           # Triggers code-review skill
kodax "写测试用例"             # Triggers tdd skill
kodax "提交代码"               # Triggers git-workflow skill

# Explicit skill command
kodax /skill:code-review

Built-in skills include:

code-review - Code review and quality analysis
tdd - Test-driven development workflow
git-workflow - Git commit and workflow automation

Skills are stored in ~/.kodax/skills/ and can be extended with custom skills.

Commands (CLI)

Commands are /xxx shortcuts in CLI:

kodax /review src/auth.ts
kodax /test

Commands are stored in ~/.kodax/commands/:

.md files → Prompt commands (content used as prompt)
.ts/.js files → Programmable commands

API Exports

// Main functions
export { runKodaX, KodaXClient };

// Types
export type {
  KodaXEvents, KodaXOptions, KodaXResult,
  KodaXMessage, KodaXContentBlock,
  KodaXSessionStorage, KodaXToolDefinition
};

// Tools
export { KODAX_TOOLS, KODAX_TOOL_REQUIRED_PARAMS, executeTool };

// Providers
export { getProvider, KODAX_PROVIDERS, KodaXBaseProvider };

// Utilities
export {
  estimateTokens,
  getGitRoot, getGitContext, getEnvContext, getProjectSnapshot,
  checkPromiseSignal
};

Development

# Development mode (using tsx)
npm run dev "your task"

# Build
npm run build

# Optional: only build workspace packages
npm run build:packages

# Build standalone binary (current platform / all platforms)
npm run build:binary
npm run build:binary:all

# Run tests
npm test

# Eval-driven development tests (provider matrices, identity round-trip, etc.)
npm run test:eval

# Clean
npm run clean

Repo Intelligence cache directories

KodaX uses one repo-intelligence cache root with separate built-in engine profiles:

.agent/repo-intelligence/
- Full-engine repo-intelligence artifacts and existing task-engine snapshots.
.agent/repo-intelligence/light/
- Light-mode heuristic index artifacts.

They are intentionally separated so:

full and light profiles can be rebuilt independently.
light-mode confidence/capability state cannot be mistaken for full-engine state.
future cache migrations can delete one profile without corrupting the other.

.agent/repo-intelligence/ is local generated state and should not be committed.

Code Style

Comment Guidelines

KodaX uses an English-first comment style with selective Chinese brief notes for complex logic.

Situation	Style	Example
Import/Export	English only	`// Import dependencies`
Simple constants	English only	`// Max retry count`
Simple logic	English only	`// Return if null`
Business rules	English + Chinese	`// Skip tool_result - 跳过工具结果块`
Platform compatibility	English + Chinese	`// Windows path handling - Windows 路径处理`
Performance optimization	English + Chinese	`// Debounce to prevent flicker - 防抖避免闪烁`

Documentation

README_CN.md - Chinese Documentation
docs/release.md - Standalone binary build & release pipeline
docs/PRD.md - Product Requirements
docs/ADR.md - Architecture Decisions
docs/HLD.md - High-Level Design
docs/DD.md - Detailed Design
docs/FEATURE_LIST.md - Feature Tracking
docs/test-guides/ - Feature-specific test guides
CHANGELOG.md - Version History (v0.7.0+; archive for older)

License

KAI-FCL is source-available / fair-core, not OSI open source. Commercial, enterprise, managed deployment, paid service, or customer redistribution use requires KodaX-AI authorization and a valid entitlement where required.

Official KodaX 0.7.70 and later distributions use KAI-FCL or accompanying KodaX-AI customer terms. Historical tags, archives, binaries, npm packages, or other copies already distributed with Apache-2.0 notices remain Apache-2.0 for those specific copies.

Name		Name	Last commit message	Last commit date
Latest commit History 2,555 Commits
.github/workflows		.github/workflows
assets		assets
benchmark		benchmark
clients		clients
config-templates		config-templates
docs		docs
examples		examples
packages		packages
scripts		scripts
site		site
src		src
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.mailmap		.mailmap
.npmrc		.npmrc
AGENTS.md		AGENTS.md
AUTHORS		AUTHORS
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
README_CN.md		README_CN.md
config.example.jsonc		config.example.jsonc
docker-compose.yml		docker-compose.yml
kodax-hd.gif		kodax-hd.gif
package-lock.json		package-lock.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.eval.config.ts		vitest.eval.config.ts
vitest.setup.queue.ts		vitest.setup.queue.ts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation