indusagi

A terminal-first AI coding-agent framework — a unified multi-provider LLM gateway, an agent runtime with tool-calling, a built-in tool set, an MCP bridge, multi-agent crews, a SaaS-connector bridge, an agent-builder, and homegrown tracing. Clean-room implementation.

The indusagi npm package is the framework. The companion CLI agent ships separately as indusagi-coding-agent. The framework is designed and written from scratch — its code reuses no third-party application source. See PROVENANCE.md for the independent-creation log.

This folder documents the public surface of indusagi: the capability layers, the CLI it bundles, and every subpath export. For a hands-on walkthrough, start with Getting Started.

Table of Contents

• What it is
• Capability layers
• Install / build / test
• Use the CLI
• Embed the framework
• Documentation map

What it is

indusagi is an ESM-only package ("type": "module") that targets Node 20 or newer. Its public surface is organized by capability layer; each layer is also reachable through its own subpath export (for example indusagi/llmgateway or indusagi/runtime). The package also ships a CLI binary, indusagi (dist/cli.js), that turns a command line into a running agent.

The root entry (src/index.ts) re-exports each layer as a namespace:

import { gateway, runtime, capabilities, interop, saas, swarm, smithy, tracing, shell } from "indusagi";

Capability layers

Each layer is a self-contained subsystem with its own index.ts barrel and its own subpath export.

The framework also exposes a set of facade subpaths (indusagi/ai, indusagi/agent, indusagi/mcp, indusagi/memory) and TUI subpaths (indusagi/tui, indusagi/react-ink, indusagi/react-host). See Package Exports for the complete map.

Install / build / test

npm install
npm run typecheck     # tsc -p tsconfig.json --noEmit  (the type gate)
npm run test          # vitest --run
npm run build         # node build.mjs  (esbuild bundles + tsc declarations -> dist/)
npm run lineage-scan  # node scripts/lineage-scan.mjs  (source-hygiene gate)

npm run prepublishOnly chains the type gate, the test suite, and the build. The published tarball ships dist/, CHANGELOG.md, CREDITS.md, NOTICE, and README.md (the files whitelist).

Use the CLI

The package installs an indusagi binary that maps to dist/cli.js. Every flag is described once in the shell app's flag table (src/shell-app/invocation/flags.ts); the parser selects one of the print, wire, or repl runners.

node dist/cli.js --help                          # show usage and exit
node dist/cli.js -m <model> -p "explain this repo"  # one-shot print mode (-p / --print)
node dist/cli.js -m <model> --json               # JSON line protocol (wire/RPC mode)
node dist/cli.js -m <model>                       # interactive REPL (default)

Selected flags (see --help for the full table):

Set the provider key for your model (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY). Attach one or more MCP servers by repeating --mcp.

Embed the framework

The root namespaces compose a runnable agent in a few lines. The runtime's createAgent takes an AgentConfig (model, optional tools, system, compaction, …) and the capabilities layer's toolBox assembles a runnable tool set backed by the real Node filesystem and shell.

import { runtime, capabilities } from "indusagi";

const agent = runtime.createAgent({
  model: "claude-sonnet-4",
  tools: capabilities.toolBox("coding"),
});

const snapshot = await agent.submit("list the TODOs in this repo");
console.log(snapshot.phase);

agent.submit(...) drives one prompt to settlement and resolves a RunSnapshot; agent.subscribe taps the live RunEvent stream. See Getting Started for a fuller example.

Documentation map

• Getting Started — install, build, CLI quickstart, and a tiny embedding example
• Architecture — how the capability layers fit together
• Package Exports — the complete exports map and source mapping

Subsystems

• LLM Gateway
• Runtime
• Capabilities
• Interop / MCP
• SaaS Connectors
• Swarm
• Smithy
• Tracing
• Shell App
• React-Ink

Facades

• AI — the indusagi/ai model facade
• Agent — the indusagi/agent bot loop facade
• MCP — the indusagi/mcp client/server facade
• Memory — the indusagi/memory facade
• TUI — terminal-UI primitives

Use cases

• Security Testing — authorized, defensive security workflows with the built-in tools

License

MIT — see NOTICE and CREDITS.md.