@nexrall/code-core

Core agent loop, tools, and extension primitives for Nexrall Code — embed an AI coding agent in any Node.js application.

npm install @nexrall/code-core

What's inside

| Module | Description | |--------|-------------| | @nexrall/code-core | Everything via the root export | | @nexrall/code-core/agent | runAgentLoop — the main agentic loop | | @nexrall/code-core/tools | executeTool — built-in tool executor (bash, file I/O, search…) | | @nexrall/code-core/symbols | getSymbols, getWorkspaceSymbols — regex-based LSP-lite scanner | | @nexrall/code-core/checkpoint | CheckpointManager — persistent rewind / rollback | | @nexrall/code-core/commands | loadSlashCommands, expandCommand — slash command loader & expander | | @nexrall/code-core/plugins | loadPlugins, pluginHooks, pluginMcpServers — plugin system | | @nexrall/code-core/permissions | loadSettings, evaluatePermission — 4-tier permission rules | | @nexrall/code-core/mcp | McpManager — MCP server manager (stdio / HTTP / SSE) | | @nexrall/code-core/api | streamChat — streaming chat API client | | @nexrall/code-core/types | Shared TypeScript types |

Quick start

import { runAgentLoop } from '@nexrall/code-core/agent';
import type { AgentLoopOptions } from '@nexrall/code-core';

const messages = [
  { role: 'user', content: [{ type: 'text', text: 'List the files in src/ and summarise what this project does.' }] }
];

const opts: AgentLoopOptions = {
  model: 'turbo',          // 'turbo' (Sonnet) | 'pro' (Opus) | 'ultra' (Fable 5)
  workDir: process.cwd(),
  env: { platform: 'node', cwd: process.cwd(), shell: 'bash' },
  clientType: 'cli',
  mode: 'auto',
  onText:       (t) => process.stdout.write(t),
  onThinking:   () => {},
  onThinkingDelta:    () => {},
  onThinkingProgress: () => {},
  onToolUse:    (name, input) => console.error(`[tool] ${name}`, input),
  onToolResult: (name, res)   => console.error(`[tool result] ${name}`, res.error ?? '✓'),
  onInjectedInput: () => {},
  onUsage:      () => {},
  requestPermission: async () => true,   // auto-approve everything
};

const history = await runAgentLoop(messages, opts);
console.log('Done —', history.length, 'messages');

Requires authentication. The agent streams through the Nexrall API — users must be logged in via nexrall-code login (or set NEXRALL_TOKEN env var).

Agent loop options

interface AgentLoopOptions {
  model: 'turbo' | 'pro' | 'ultra';
  workDir: string;
  env: EnvContext;
  clientType?: 'cli' | 'vscode';
  mode?: 'auto' | 'ask' | 'edit' | 'plan';
  effort?: 'low' | 'medium' | 'high' | 'extra';
  nexrallMd?: string;            // project instructions (nexrall.md contents)
  maxIterations?: number;        // default 500, ceiling 2000
  autoContinue?: boolean;        // auto-extend budget when agent is mid-task (default: true)
  autoCompact?: boolean;         // auto-summarise history at 80% context window (default: true)
  abortSignal?: { aborted: boolean };
  checkpointManager?: CheckpointManager;
  mcpManager?: McpManager;
  // Stream callbacks
  onText: (text: string) => void;
  onThinking: (text: string) => void;
  onThinkingDelta: (text: string) => void;
  onThinkingProgress: (tokens: number) => void;
  onToolUse: (name: string, input: Record<string, unknown>, isSubTask?: boolean) => void;
  onToolResult: (name: string, result: ToolResult, isSubTask?: boolean) => void;
  onInjectedInput: (text: string) => void;
  onUsage: (usage: UsageStats) => void;
  requestPermission: (req: PermissionRequest) => Promise<boolean>;
  // Optional: inject follow-up messages while the agent is running
  takePendingInput?: () => string[];
  // Optional: handle tools not in the built-in executor (e.g. VS Code LSP tools)
  executeExternalTool?: (name: string, input: Record<string, unknown>) => Promise<ToolResult | null>;
}

Plugin system

Drop a folder into .nexrall/plugins/<name>/ (project) or ~/.nexrall/plugins/<name>/ (global):

.nexrall/plugins/my-plugin/
  plugin.json          # { "name", "version", "description" }
  commands/review.md   # custom /review slash command
  agents/reviewer.md   # custom sub-agent type
  hooks.json           # PreToolUse / PostToolUse hooks
  mcp.json             # { "mcpServers": { ... } }

Precedence: project > global > plugin > builtin.

import { loadPlugins, pluginHooks, pluginMcpServers } from '@nexrall/code-core/plugins';

const plugins = loadPlugins(process.cwd());
// [{ name: 'my-plugin', version: '1.0.0', dir: '...', scope: 'project' }]

Slash commands & agents

import { loadSlashCommands, expandCommand, findSlashCommand } from '@nexrall/code-core/commands';
import { loadAgentTypes, findAgentType } from '@nexrall/code-core/agent-types';

// Built-in /review command is always available (overridable)
const cmds = loadSlashCommands(process.cwd());
const review = findSlashCommand(cmds, 'review');
const prompt = expandCommand(review, 'main..feature-branch', process.cwd());

// Built-in 'reviewer' agent (read-only, usable as subagent_type: 'reviewer')
const agents = loadAgentTypes(process.cwd());
const reviewer = findAgentType(agents, 'reviewer');

Checkpoint / rewind

import { CheckpointManager } from '@nexrall/code-core/checkpoint';

// Scoped per session — persists to ~/.nexrall/checkpoints/<hash>/
const cp = new CheckpointManager(workDir, sessionId);
cp.beginTurn('refactor auth module', messages.length);
// ... agent runs and mutates files ...
cp.commitTurn();

// Roll back files + conversation
const result = cp.restore(cp.list()[0].id);
// result.restored      → absolute paths rolled back
// result.bashCount     → shell commands NOT undone (with warning)
// result.gitStashHashes → git stash create recovery points

Requirements

• Node.js ≥ 18
• A Nexrall account (sign up at nexrall.com)

License

MIT © Nexrall