Package Exports
- @nexrall/code-core
- @nexrall/code-core/agent
- @nexrall/code-core/agent-types
- @nexrall/code-core/api
- @nexrall/code-core/checkpoint
- @nexrall/code-core/commands
- @nexrall/code-core/mcp
- @nexrall/code-core/permissions
- @nexrall/code-core/plugins
- @nexrall/code-core/symbols
- @nexrall/code-core/tools
- @nexrall/code-core/types
Readme
@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-coreWhat'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 setNEXRALL_TOKENenv 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 pointsRequirements
- Node.js ≥ 18
- A Nexrall account (sign up at nexrall.com)
License
MIT © Nexrall