← All docs

DOCS

  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
DOCS
  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
ON THIS PAGE
  1. Quick Start
  2. Extension Locations
  3. Available Imports
  4. Events
  5. Lifecycle Overview
  6. Key Events
  7. ExtensionContext (ctx)
  8. ExtensionAPI Methods (neo)
  9. Custom Tools
  10. Custom UI
  11. Dialogs
  12. Widgets & Status
  13. Custom Components
  14. State Management
  15. Provider Registration
  16. Error Handling
  17. Mode Behavior

Extensions

Extensions are TypeScript modules that extend Neo Code's behavior. They can subscribe to lifecycle events, register custom tools callable by the LLM, add commands, and more.

Placement for /reload: Put extensions in ~/.neo-code/agent/extensions/ (global) or .neo-code/extensions/ (project-local) for auto-discovery. Use neo -e ./path.ts only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with /reload.

Key capabilities:

  • Custom tools — Register tools the LLM can call via neo.registerTool()
  • Event interception — Block or modify tool calls, inject context, customize compaction
  • User interaction — Prompt users via ctx.ui (select, confirm, input, notify)
  • Custom UI components — Full TUI components with keyboard input via ctx.ui.custom()
  • Custom commands — Register commands like /mycommand via neo.registerCommand()
  • Session persistence — Store state that survives restarts via neo.appendEntry()
  • Custom rendering — Control how tool calls/results and messages appear in TUI

#Quick Start

Create ~/.neo-code/agent/extensions/my-extension.ts:

import type { ExtensionAPI } from "@neosantara/code";
import { Type } from "typebox";

export default function (neo: ExtensionAPI) {
  neo.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  neo.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  neo.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });

  neo.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
    },
  });
}

Test with --extension (or -e) flag:

neo -e ./my-extension.ts

#Extension Locations

Security: Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.

LocationScope
~/.neo-code/agent/extensions/*.tsGlobal (all projects)
~/.neo-code/agent/extensions/*/index.tsGlobal (subdirectory)
.neo-code/extensions/*.tsProject-local
.neo-code/extensions/*/index.tsProject-local (subdirectory)

Additional paths via settings.json:

{
  "packages": ["npm:@foo/bar@1.0.0", "git:github.com/user/repo@v1"],
  "extensions": ["/path/to/local/extension.ts"]
}

#Available Imports

PackagePurpose
@neosantara/codeExtension types (ExtensionAPI, ExtensionContext, events)
typeboxSchema definitions for tool parameters
@neosantara/aiAI utilities
@neosantara/tuiTUI components for custom rendering

Node.js built-ins (node:fs, node:path, etc.) are also available.

#Events

#Lifecycle Overview

neo starts
  ├─► session_start { reason: "startup" }
  └─► resources_discover { reason: "startup" }

user sends prompt
  ├─► input (can intercept, transform, or handle)
  ├─► before_agent_start (can inject message, modify system prompt)
  ├─► agent_start
  │   ┌─── turn (repeats while LLM calls tools) ───┐
  │   ├─► turn_start
  │   ├─► context (can modify messages)
  │   ├─► before_provider_request
  │   ├─► after_provider_response
  │   │   LLM responds, may call tools:
  │   │     ├─► tool_execution_start
  │   │     ├─► tool_call (can block)
  │   │     ├─► tool_result (can modify)
  │   │     └─► tool_execution_end
  │   └─► turn_end
  └─► agent_end

/compact or auto-compaction
  ├─► session_before_compact (can cancel or customize)
  └─► session_compact

/tree navigation
  ├─► session_before_tree (can cancel or customize)
  └─► session_tree

exit
  └─► session_shutdown

#Key Events

tool_call

Fired before tool executes. Can block. event.input is mutable.

neo.on("tool_call", async (event, ctx) => {
  if (event.toolName === "bash" && event.input.command?.includes("sudo")) {
    return { block: true, reason: "Blocked sudo" };
  }
});

tool_result

Fired after tool execution. Can modify result.

neo.on("tool_result", async (event, ctx) => {
  return { content: [...], details: {...}, isError: false };
});

before_agent_start

Fired before agent loop. Can inject messages and modify system prompt.

neo.on("before_agent_start", async (event, ctx) => {
  return {
    message: { customType: "my-ext", content: "Extra context", display: true },
    systemPrompt: event.systemPrompt + "\n\nExtra instructions...",
  };
});

context

Fired before each LLM call. Modify messages non-destructively.

neo.on("context", async (event, ctx) => {
  const filtered = event.messages.filter(m => !shouldPrune(m));
  return { messages: filtered };
});

input

Fired when user input is received. Can intercept, transform, or handle.

neo.on("input", async (event, ctx) => {
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }
  return { action: "continue" };
});

session_before_compact

See compaction.md for details.

session_shutdown

Fired before extension runtime is torn down.

neo.on("session_shutdown", async (event, ctx) => {
  // Cleanup, save state
});

#ExtensionContext (ctx)

All handlers receive ctx: ExtensionContext.

Property/MethodDescription
ctx.uiUI methods (select, confirm, input, notify, setStatus, setWidget)
ctx.hasUIfalse in print/JSON mode
ctx.cwdCurrent working directory
ctx.sessionManagerRead-only session state
ctx.modelRegistryAccess to models and API keys
ctx.signalCurrent agent abort signal
ctx.isIdle()Whether agent is idle
ctx.abort()Abort current agent turn
ctx.shutdown()Request graceful shutdown
ctx.compact()Trigger compaction
ctx.getSystemPrompt()Current system prompt string
ctx.getContextUsage()Current context token usage

#ExtensionAPI Methods (neo)

MethodDescription
neo.on(event, handler)Subscribe to events
neo.registerTool(def)Register LLM-callable tool
neo.registerCommand(name, opts)Register slash command
neo.registerShortcut(key, opts)Register keyboard shortcut
neo.registerFlag(name, opts)Register CLI flag
neo.registerProvider(name, config)Register model provider
neo.registerMessageRenderer(type, fn)Custom message rendering
neo.sendMessage(msg, opts)Inject custom message
neo.sendUserMessage(content, opts)Send user message
neo.appendEntry(type, data)Persist extension state
neo.setSessionName(name)Set session display name
neo.setLabel(entryId, label)Set entry label/bookmark
neo.exec(cmd, args, opts)Execute shell command
neo.getActiveTools()Get active tool list
neo.getAllTools()Get all registered tools
neo.setActiveTools(names)Enable/disable tools
neo.setModel(model)Set current model
neo.getThinkingLevel()Get thinking level
neo.setThinkingLevel(level)Set thinking level
neo.getCommands()Get available commands
neo.eventsShared event bus between extensions

#Custom Tools

import { Type } from "typebox";

neo.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does (shown to LLM)",
  parameters: Type.Object({
    action: Type.String(),
    text: Type.Optional(Type.String()),
  }),

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });

    return {
      content: [{ type: "text", text: "Done" }],
      details: { result: "..." },
    };
  },

  // Optional: Custom TUI rendering
  renderCall(args, theme, context) { /* return Component */ },
  renderResult(result, options, theme, context) { /* return Component */ },
});

Error signaling: Throw from execute to mark as error. Return values never set error flag.

Early termination: Return terminate: true to skip follow-up LLM call.

#Custom UI

#Dialogs

const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
const name = await ctx.ui.input("Name:", "placeholder");
const text = await ctx.ui.editor("Edit:", "prefilled text");
ctx.ui.notify("Done!", "info");

#Widgets & Status

ctx.ui.setStatus("my-ext", "Processing...");
ctx.ui.setStatus("my-ext", undefined);  // Clear
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
ctx.ui.setWidget("my-widget", undefined);  // Clear
ctx.ui.setTitle("neo - my-project");
ctx.ui.setEditorText("Prefill text");

#Custom Components

const result = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
  const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);
  text.onKey = (key) => {
    if (key === "return") done(true);
    if (key === "escape") done(false);
    return true;
  };
  return text;
});

#State Management

Store state in tool result details for proper branching support:

export default function (neo: ExtensionAPI) {
  let items: string[] = [];

  neo.on("session_start", async (_event, ctx) => {
    items = [];
    for (const entry of ctx.sessionManager.getBranch()) {
      if (entry.type === "message" && entry.message.role === "toolResult") {
        if (entry.message.toolName === "my_tool") {
          items = entry.message.details?.items ?? [];
        }
      }
    }
  });

  neo.registerTool({
    name: "my_tool",
    parameters: Type.Object({ text: Type.String() }),
    async execute(toolCallId, params) {
      items.push(params.text);
      return {
        content: [{ type: "text", text: "Added" }],
        details: { items: [...items] },
      };
    },
  });
}

#Provider Registration

neo.registerProvider("my-proxy", {
  name: "My Proxy",
  baseUrl: "https://proxy.example.com",
  apiKey: "PROXY_API_KEY",
  api: "openai-completions",
  models: [{
    id: "my-model",
    name: "My Model",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 4096,
  }],
});

#Error Handling

  • Extension errors are logged, agent continues
  • tool_call errors block the tool (fail-safe)
  • Tool execute errors must be signaled by throwing

#Mode Behavior

ModeUI MethodsNotes
InteractiveFull TUINormal operation
RPC (--mode rpc)JSON protocolHost handles UI
JSON (--mode json)No-opEvent stream to stdout
Print (-p)No-opExtensions run but can't prompt

Check ctx.hasUI before using UI methods in non-interactive modes.

ON THIS PAGE

  1. Quick Start
  2. Extension Locations
  3. Available Imports
  4. Events
  5. Lifecycle Overview
  6. Key Events
  7. ExtensionContext (ctx)
  8. ExtensionAPI Methods (neo)
  9. Custom Tools
  10. Custom UI
  11. Dialogs
  12. Widgets & Status
  13. Custom Components
  14. State Management
  15. Provider Registration
  16. Error Handling
  17. Mode Behavior
Previous← SubagentsNextThemes →

Neo Code

Neosantara-first AI coding agent for your terminal.

Product

  • Docs
  • Pricing
  • GitHub

Neosantara

  • Dashboard
  • API

Legal

  • Terms
  • Privacy

2026 Neosantara. All rights reserved.