DEEN

DocsAutomate

Node.js and ACP

Drive Alran Code from your own program, or plug it into any editor that speaks the Agent Client Protocol.

How do I drive Alran Code from my own program?

Entry pointCommandUse it for
Interactive TUIalran [prompt]Working with the agent yourself
Headlessalran exec [prompt]Scripts, CI, batch work, evaluations
ACPalran acpEditors and clients that speak the Agent Client Protocol

From Node.js

alran exec --output-format stream-json writes one JSON event per line, which any language can read:

js
import { spawn } from 'node:child_process';
import { createInterface } from 'node:readline';

const run = spawn('alran', ['exec', '--output-format', 'stream-json', 'Fix the failing test']);
for await (const line of createInterface({ input: run.stdout })) {
  const event = JSON.parse(line);
  console.log(event.type);
}

ACP

bash
alran acp

Runs Alran Code as an Agent Client Protocol server over stdio. An editor starts it and talks to it; tools, permissions, skills, plugins, MCP, subagents, goals and sessions behave exactly as in the terminal, because the same runtime runs them. The VS Code extension works this way.

Change the agent's prompt

Every entry point takes the same switches for one process:

OptionWhat it does
--append-system-prompt <text>Add text after the agent's identity
--append-system-prompt-file <path>The same, from a file
--system-prompt <text>Replace the identity section
--system-prompt-file <path>The same, from a file

Project instructions (AGENTS.md), the environment, memory and skills stay in either case.

Common questions

How do I call Alran Code from my own program?

There are three ways in: the interactive TUI with alran, the headless mode with alran exec for scripts, CI and batch work, and the Agent Client Protocol with alran acp for editors and clients that speak it. For a script, spawn alran exec --output-format stream-json and read its output line by line: it writes one JSON event per line, which any language can read.

What is the Agent Client Protocol and when should I use it?

alran acp runs Alran Code as an Agent Client Protocol server over stdio. An editor starts it and talks to it, and tools, permissions, skills, plugins, MCP, subagents, goals and sessions behave exactly as in the terminal, because the same runtime runs them. The VS Code extension works this way.

How do I change the system prompt of the agent?

Every entry point takes the same switches for one process: --append-system-prompt and --append-system-prompt-file add text after the identity of the agent, --system-prompt and --system-prompt-file replace that identity section. Project instructions in AGENTS.md, the environment, memory and skills stay in either case.