Getting Started · TypeScript Framework

indusagi is the terminal-first AI coding-agent framework. It ships both a CLI binary and an embeddable library surface organized by capability layer. This guide covers both.

Install
Build and verify
CLI quickstart
Embed the framework
Notes

Install

npm install indusagi

The package is ESM only ("type": "module") and requires Node 20 or newer. Installing it also provides the indusagi CLI binary (mapped to dist/cli.js).

Build and verify

When working from a checkout of the framework, the standard gates are:

npm install
npm run typecheck     # tsc -p tsconfig.json --noEmit
npm run test          # vitest --run
npm run build         # node build.mjs  -> dist/
npm run lineage-scan  # source-hygiene gate

CLI quickstart

Set the provider key for the model you intend to run, then invoke the CLI. The runner is selected from your flags: -p for one-shot print mode, --json for the wire protocol, and the bare invocation for the interactive REPL.

export ANTHROPIC_API_KEY="sk-..."

# Show usage (derived from the flag table)
node dist/cli.js --help

# One-shot: print a single answer and exit
node dist/cli.js -m claude-sonnet-4 -p "summarize the package.json in this repo"

# Wire mode: speak the JSON line protocol over stdio (also reachable as --rpc / --wire)
node dist/cli.js -m claude-sonnet-4 --json

# Interactive REPL (the default when no print/wire flag is present)
node dist/cli.js -m claude-sonnet-4

Attach external Model Context Protocol servers by repeating --mcp; disable all tools with --no-tools; override the system prompt with --system.

node dist/cli.js -m claude-sonnet-4 --mcp ./my-server --mcp ./other-server -p "what tools do you have?"

Embed the framework

The root entry exposes each capability layer as a namespace. A minimal agent needs two of them: the runtime (which owns createAgent) and the capabilities layer (which assembles a runnable tool set with toolBox).

import { runtime, capabilities } from "indusagi";

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

// Tap the live event stream.
const unsubscribe = agent.subscribe((event) => {
  console.log(event.kind);
});

// Drive one prompt to settlement; resolves the terminal RunSnapshot.
const snapshot = await agent.submit("list the TODO comments in this repo");
console.log(snapshot.phase);

unsubscribe();

createAgent accepts an AgentConfig: model (a catalog id) is required, and tools, system, maxOutputTokens, thinking, compaction, and maxTurns are optional. submit takes a bare string (sugar for one user turn) or a list of Turns and returns a RunSnapshot.

Reaching a single layer

Each layer is also importable on its own subpath, which keeps a consumer's dependency graph small:

import { models, estimateCost } from "indusagi/llmgateway";
import { createAgent } from "indusagi/runtime";
import { toolBox } from "indusagi/capabilities";

For the full list of namespaces and subpaths, see Package Exports.

Notes

The package is ESM only ("type": "module"); Node 20 or newer is required.
The CLI binary is indusagi and maps to dist/cli.js.
The framework is indusagi; the standalone coding-agent CLI ships as indusagi-coding-agent.

Table of Contents