Features

This guide walks you through Nanocoder's features in the order you'll naturally discover them — starting with the basics you'll use every session, then building up to power-user workflows.

Your First Session

When you launch Nanocoder for the first time in a project directory, you'll see a security disclaimer asking you to trust the directory. Once confirmed, you're in an interactive chat session with your AI assistant.

Here's what you need to know right away:

Talking to the AI

Type your message and press Enter to send. The AI streams its response token-by-token. If you need multi-line input, press Ctrl+J to add a new line — it's the official supported newline shortcut.

Giving the AI Context

Use @ followed by a filename to include file contents in your message. Nanocoder fuzzy-matches as you type and shows autocomplete suggestions — press Tab to select.

Can you review @src/app.tsx for any issues?

You can also include specific line ranges:

What does this function do? @src/utils.ts:45-80

Running Shell Commands

Prefix any command with ! to run it directly in your shell without leaving Nanocoder. The output becomes context for the AI.

!git status
!npm test

Keyboard Shortcuts

These are the shortcuts you'll use constantly:

Action	Shortcut
Submit prompt	Enter
New line	Ctrl+J
Toggle development mode	Shift+Tab
Cancel AI response	Esc
Clear input	Esc (twice)
Toggle compact tool output	Ctrl+O
Navigate prompt history	Up/Down

See the full Keyboard Shortcuts reference for the complete shortcut list. Shift+Enter is documented there only as a terminal-dependent fallback.

Slash Commands

Type / to see available commands. A few essentials:

• /help — list all commands
• /status — see your current provider, model, and context usage
• /model — switch models
• /clear — start fresh

See the full Commands Reference for every available command.

Controlling Tool Execution

When the AI wants to edit a file, run a command, or perform any action, it uses tools. How those tools execute depends on your current development mode:

Mode	Behaviour	Best For
Normal (default)	Confirm each tool before it runs	Unfamiliar codebases, sensitive operations
Auto-Accept	Most tools execute immediately; bash and destructive git still prompt	Trusted tasks, faster iteration
Yolo	Every tool executes immediately — no exceptions	Zero interruptions, full trust
Plan	Tools are shown but never executed	Exploring what the AI would do

Toggle between modes with Shift+Tab. The current mode is shown in the status bar.

Non-Interactive Mode

For scripting and automation, run Nanocoder without an interactive session:

nanocoder run "Add error handling to src/api.ts"

This submits the prompt, auto-accepts tool calls, and exits when complete. Run mode uses a minimal shell (plain-markdown assistant output, chronological tool one-liners, a single status line) so output pipes cleanly into other tools.

Override the default mode with --mode — works both interactively and with run:

nanocoder --mode yolo                      # interactive, no approvals
nanocoder --mode plan run "audit auth"     # run mode, plan only

See Commands → Non-Interactive Mode and Development Modes for details.

Managing Long Conversations

As your conversation grows, you'll want tools to keep it manageable.

Context Compression

Every message adds to your context window. When it fills up, the AI loses access to earlier messages. Context compression solves this:

• /compact — manually compress older messages. Uses an LLM to write a structured summary by default; pass --mechanical for a fast regex-based fallback
• Auto-compact — automatically compresses when context reaches a threshold (configurable in agents.config.json, including the strategy)
• /usage — see a visual breakdown of your current context utilization

Checkpointing

Before trying a risky approach, save a checkpoint:

/checkpoint create before-refactor
# ... try something experimental ...
/checkpoint load before-refactor    # roll back if it didn't work

Checkpoints save your conversation history, modified files, and model configuration.

Session Management

Nanocoder automatically saves your sessions so you can pick up where you left off:

/resume         # browse recent sessions
/resume last    # jump back into the most recent one

Sessions are saved every 30 seconds by default and kept for 30 days.

Tracking Complex Work

For multi-step tasks, the task management system keeps you and the AI aligned:

/tasks add Implement authentication
/tasks add Write tests for auth module
/tasks add Update API documentation

The AI also has access to task tools and will proactively create and update tasks when working on involved problems.

Customizing Nanocoder

Project Setup with /init

Run /init to analyze your project and generate an AGENTS.md file — a project-specific prompt that gives the AI context about your codebase, conventions, and tooling. Use /init --force to regenerate it.

The AGENTS.md file is automatically loaded every session, so the AI always knows how your project works.

Skills: the unified extension model

Skills are the umbrella for everything you can plug into Nanocoder — custom commands, subagents, custom tools, and event-driven triggers all live under one model. A skill is either a single .md file (a one-member skill) or a directory under .nanocoder/skills/<name>/ (a bundle that ships a command + subagent + tools together).

/skills              # list every loaded skill
/skills show k8s     # inspect a skill (members, subscriptions, source)
/skills create k8s   # scaffold a new bundle

For most cases, you'll work at the skill level. The per-primitive pages below cover the member-specific details.

Skill primitives

These are the kinds of members a skill can contain. Each page covers its primitive's specifics — combining them into a cohesive skill is documented in Skills.

• Custom Commands — reusable prompts invoked as /command. Support parameters, aliases, auto-injection, namespacing.
• Subagents — specialized AI agents the main agent can delegate to. Isolated context, filtered tools, optionally a different model.
• Custom Tools — model-callable shell scripts with declared input schemas and approval policy.
• Event subscriptions — cron and file.changed triggers that fire skill members through the per-project daemon. See Skills → Event subscriptions.

File Explorer

The file explorer gives you an interactive tree view of your project for browsing and selecting files as context:

/explorer

Navigate with arrow keys, select files with Space, search with /, and press Esc to add your selection as @file mentions. It shows token estimates so you know how much context you're adding.

Integrations

VS Code Extension

The VS Code extension bridges your editor and the CLI:

nanocoder --vscode

Features include live diff previews of proposed changes, right-click "Ask Nanocoder about this" for selected code, and LSP diagnostics sharing.

ACP (Zed and other editors)

Run Nanocoder as an Agent Client Protocol server so ACP-compatible editors like Zed can drive it as a native agent — with diffs, tool cards, permission prompts, and model switching rendered in the editor:

nanocoder --acp

MCP Servers

Extend Nanocoder's capabilities by connecting MCP (Model Context Protocol) servers. MCP servers add new tools the AI can use — from database queries to API calls to custom integrations.

/setup-mcp      # interactive setup wizard
/mcp            # see connected servers and tools

Feature Reference

Feature	Description
Skills	Umbrella — unified extension model for commands, subagents, tools, and event triggers
Custom Commands	Reusable AI prompts as markdown files (a kind of skill member)
Subagents	Specialized AI agents with isolated context (a kind of skill member)
Custom Tools	Model-callable shell scripts (a kind of skill member)
Scheduler	Migration pointer — cron triggers are now skill subscriptions
Commands Reference	All slash commands and special input syntax
Development Modes	Normal, auto-accept, yolo, and plan modes
Context Compression	Managing token usage in long conversations
Checkpointing	Saving and restoring conversation snapshots
Session Management	Automatic session saving and resumption
Task Management	Tracking multi-step work
File Explorer	Interactive file browser for context selection
VS Code Extension	Editor integration with live diff previews
ACP	Run as an Agent Client Protocol server for editors like Zed
Tune	Runtime model tuning for tool profiles, parameters, and compaction
Desktop Notifications	Get notified when Nanocoder needs your attention
Keyboard Shortcuts	Complete keyboard shortcut reference