Commands Reference

Type / in the chat input to see available commands. All commands start with / and can be invoked at any point during a session.

Built-in Commands

Command	Description
/help	Show available commands
/init	Initialize project with intelligent analysis, create AGENTS.md and configuration files. Use /init --force to regenerate AGENTS.md if it already exists, or /init --lean to skip merging CLAUDE.md content into the generated AGENTS.md
/setup-config	Open a configuration file in your $EDITOR (lists project and global config files)
/clear	Clear chat history
/model	Switch between available models from any configured provider
/status	Display current status (CWD, provider, model, theme, available updates, AGENTS setup)
/tasks	Manage task list for tracking complex work (see Task Management)
/model-database	Browse coding models from OpenRouter (searchable, filterable by open/proprietary)
/settings	Interactive settings menu. Accepts a tab name to jump straight there: /settings providers, /settings mcp, /settings appearance, /settings input, /settings behavior, /settings advanced
/mcp	Show connected MCP servers and their tools
/custom-commands	List all custom commands
/checkpoint	Save and restore conversation snapshots (see Checkpointing)
/compact	Compress message history to reduce context usage (see Context Compression)
/context-max	Set maximum context length for the current session, or inspect the resolved context source. Also available as --context-max CLI flag
/exit	Exit the application
/export	Export current session to markdown file
/copy	Copy the last assistant response to the system clipboard
/commit	Generate a Conventional Commit message from staged Git changes
/doctor	Show environment health report for bug reports
/update	Update Nanocoder to the latest version
/usage	Get current model context usage visually
/lsp	List connected LSP servers
/schedule	Read-only view of cron subscriptions declared by skills (see Skills → Event subscriptions)
/skills	List and inspect loaded skills; scaffold new bundle skills with AI assistance (see Skills)
/resume	Resume a previous chat session (aliases: /sessions, /history). Also available at launch via the --resume/--continue CLI flags. See Session Management
/retry	Re-run the last user turn. Use /retry --model <id> or /retry --provider <name> --model <id> to switch models first
/rename	Rename the current session. Name must be non-empty and 100 characters or less. See Session Management
/explorer	Interactive file browser to navigate, preview, and select files for context
/tune	Configure runtime model behaviour — tool profiles, compaction, native tools, model parameters (see Tune)
/ide	Connect to an IDE for live integration (e.g., VS Code diff previews)

Special Input Syntax

These shortcuts work directly in the chat input — no / prefix needed.

Syntax	Description
!command	Execute bash commands directly without leaving Nanocoder (output becomes context for the LLM)
@file	Include file contents in messages via fuzzy search — press Tab to select from suggestions
@file:10-20	Include specific line range from a file (line 10 to 20)
@file:10	Include a single line from a file

File Mentions

The @ syntax triggers real-time fuzzy matching as you type. Nanocoder searches your project files (respecting .gitignore) and shows autocomplete suggestions. Press Tab to accept a suggestion.

You can narrow the context by specifying line ranges:

What does this function do? @src/utils.ts:45-80
Explain the error on @src/app.tsx:23

Shell Commands

The ! prefix runs a command in your shell and includes the output as context for the AI:

!git log --oneline -10
!npm test -- --filter auth

Non-Interactive Mode

Run Nanocoder without an interactive session for scripting and automation:

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

This submits the prompt and exits when complete. Useful for CI pipelines, git hooks, or chaining with other tools.

Run mode renders through a dedicated minimal shell: no welcome banner, no boxed "You:" echo, no trailing token counts, no ctrl+r to expand hints. Assistant text streams as plain markdown, tools render chronologically as one-liners (e.g. ⚒ Read 1 file), and a single status line below the transcript shows progress.

By default, run uses auto-accept. Override with --mode to boot into a different development mode:

# Plan only — no changes executed
nanocoder --mode plan run "analyze the auth module"

# No safety rails — auto-accepts every tool including bash
nanocoder --mode yolo run "update README and push"

If a tool requires approval that the active mode won't grant, nanocoder prints Tool approval required for: ... and exits with status code 1.

JSON Output

For CI pipelines, scripting, and tool chaining, pass --json (alias --output-format json) alongside run to get a single structured JSON object on stdout instead of streamed markdown:

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

With --json set, all human-readable output — boot banners, streamed tokens, tool one-liners, status lines — is suppressed from stdout. Anything nanocoder would otherwise print is instead routed to stderr, so stdout stays clean for piping:

nanocoder --plain --json run "refactor the auth module" | jq .finalText

--json requires run and is incompatible with --acp and --vscode — combining them exits with an error before the session starts.

Output Shape

The emitted object looks like:

{
  "kind": "success",
  "exitCode": 0,
  "finalText": "...",
  "reasoning": "...",
  "toolCalls": [
    {
      "name": "edit_file",
      "arguments": { "path": "src/api.ts" },
      "result": "...",
      "error": null
    }
  ],
  "filesChanged": ["src/api.ts"],
  "usage": {
    "inputTokens": 4520,
    "outputTokens": 850,
    "totalTokens": 5370
  }
}

• kind — "success", "tool-approval-required", or "error", matching the underlying conversation result
• exitCode — 0 for success, 1 for error, 2 for tool-approval-required; mirrors the process exit code
• finalText — the model's final response text
• reasoning — accumulated reasoning/thinking content, or null if the model didn't emit any
• toolCalls — every tool call made during the run, each with its arguments and either a result or an error (never both)
• filesChanged — deduplicated list of file paths touched by file-mutating tools (write_to_file, create_file, string_replace, edit_file)
• usage — provider-reported token counts summed across every turn of the run. Omitted entirely when the provider reports no token telemetry (common with local models), so an absent block means "unknown", never "zero". When a provider reports input and output counts but no total, totalTokens is derived as their sum.

Two more fields appear conditionally: message (the error text, when kind is "error") and toolNames (the tools awaiting approval, when kind is "tool-approval-required").

On error (e.g. an untrusted workspace directory, or the turn limit being hit without a final answer), kind is "error" and the object still includes whatever toolCalls were captured before the failure, so partial progress isn't silently dropped.