Skip to content

commands.md

Latest commit

 

History

History
209 lines (163 loc) · 15.6 KB

commands.md

File metadata and controls

209 lines (163 loc) · 15.6 KB
Raw
title Commands
description Complete reference of built-in slash commands and special input syntax
sidebar_order 5

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 the project with intelligent analysis and create AGENTS.md. Use /init --preset <react|nextjs|rust> for bundled stack guidance, ignore patterns, and a /check command skill; /init --force regenerates AGENTS.md, and /init --lean skips merging CLAUDE.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). Enter copies the highlighted model's ID to the clipboard and, when the active provider is OpenRouter, also switches the session to that model
/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
/commands List custom commands. Subcommands: show <name>, create <name> (see Custom Commands)
/tools List available tools grouped by source (built-in, MCP, custom). Subcommand: create <name> (see Custom Tools)
/agents List subagents. /agents show <name> for details, /agents copy <name> to customize, /agents create <name> to scaffold a new one (see Subagents)
/checkpoint Save and restore file snapshots. Subcommands: create/save, list/ls, load/restore, delete/remove/rm, help (see Checkpointing)
/compact Compress message history to reduce context usage. Flags include --llm, --mechanical, --default, --conservative, --aggressive, --preview and --restore; --strategy, --threshold, --auto-on and --auto-off only change session settings (see Context Compression)
/context-max Set maximum context length for the current session (e.g. /context-max 128k), or inspect the resolved context source. /context-max --reset clears the session override. Also available as --context-max CLI flag
/exit Exit the application (alias: /quit)
/export Export the current session to a markdown file, or to JSON with /export --json or a .json filename (see Exporting a Session)
/copy Copy the last assistant response to the system clipboard. Use /copy code to copy just the last fenced code block from the last response
/expand [n] Print tool result n in full. Long tool output is cut to 20 lines with a /expand n hint; run /expand without a number to list recent results
/commit Generate a Conventional Commit message from staged Git changes. Add --copy (or -c) to also copy the message to the system clipboard. A spinner shows while the model is working
/review One-shot, diff-only review of the current branch or one target. Usage: /review [quick] [<branch-or-PR-number-or-GitHub-PR-URL>] (e.g. /review, /review main, /review quick 42, /review https://github.com/owner/repo/pull/42). Bare PR numbers are resolved across configured GitHub remotes and their fork parents; ambiguous numbers require a full PR URL
/doctor Show environment health report for bug reports
/update Update Nanocoder to the latest version
/usage Get current model context usage visually
/stats Lifetime usage (sessions, prompts, tokens). Ranges: 7d / 3m / all-time, either as an argument (/stats 7d) or with ←/→ in the view; Esc/Enter to close. Use /stats reset to clear the ledger
/tip [text] Show a random usage tip, shortcut, or slash command; pass text to pick from tips mentioning it
/lsp List connected LSP servers
/repomap Show a PageRank-ordered map of the codebase - the most-referenced files and the symbols they define. Use /repomap --tokens <n> to widen the map beyond its default 1024-token budget
/schedule Read-only view of cron subscriptions declared by skills (see Skills → Event subscriptions)
/skills List and inspect loaded skills. Subcommands: show <name>, create <name> (scaffold a bundle with AI assistance), check <name> (validate a bundle), promote <name> (copy a project skill to your personal config) and demote <name> (copy a personal skill into the project); promote/demote accept --force and --move (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)
/remember Save a durable project memory (see Semantic Memory)
/memory List, delete, propose, and accept project memories (see Semantic Memory)
/privacy Inspect what the prompt scrubber would remove from some text: /privacy inspect <text>. Scrubbing itself is switched on with the enablePromptScrubbing preference (/settings → Advanced → Privacy)
/credits Show project contributors and dependencies
/copilot-login [providerName] Log in to GitHub Copilot via device flow. Saves credentials for the named provider, "GitHub Copilot" by default
/codex-login Log in to ChatGPT/Codex via device flow. Saves credentials for the "ChatGPT" provider
/voice Configure Voice Mode (`/voice [hands-free

Voice Mode

Nanocoder includes a local-first Realtime Voice Mode supporting push-to-talk, hands-free voice activity detection (VAD), barge-in interruption, and optional cloud STT/TTS.

Command Description
/voice Toggle voice mode on/off
/voice ptt or /voice push-to-talk Switch to push-to-talk mode (use Ctrl+G to record/submit)
/voice hands-free Switch to hands-free mode (automatic VAD speech detection)
/voice stt [local|cloud] Configure speech-to-text backend (local Whisper or opt-in cloud)
/voice tts [local|cloud] Configure text-to-speech backend (local Piper or opt-in cloud; cloud sends generated text to OpenAI)
/voice status Display current voice configuration and backend status
/voice mode <push-to-talk|hands-free> Set specific activation mode

Push-to-talk (Ctrl+G) can interrupt a response at any point, including while it is being spoken. In hands-free mode, speech has to last about 300 ms before it counts, so a cough or a door does not cancel a run. Speech that starts while a response is being spoken is ignored, so the speakers cannot interrupt themselves; use Ctrl+G to cut playback short. Hands-free speech is also ignored while a typed prompt is running or a confirmation is on screen.

Hands-free mode is paused in yolo mode, so ambient speech cannot trigger unconfirmed tool calls. Cloud STT sends microphone audio to OpenAI, and cloud TTS sends the response text; both are opt-in and local is the default.

Exporting a Session

/export                     # markdown, filename generated from your first prompt and the date
/export notes/auth.md       # markdown, your filename
/export --json              # JSON, generated filename
/export --json run.json     # JSON, your filename
/export run.json            # a .json filename also selects JSON

JSON exports keep full message content and session metadata, for replay or evaluation. The file is written relative to the current directory and must stay inside the project: ~ is not expanded, .. segments are refused, and absolute paths outside the project root are rejected. A generated filename gets a numeric suffix rather than overwriting an earlier export; a filename you type overwrites an existing file.

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+n 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"

For long prompts, use --prompt-file <path> to read the prompt from a file instead of the command line. It takes precedence over a positional prompt, and avoids the Linux limit of 128 KiB per command-line argument, which makes large prompts (for example ones that embed file contents) fail to launch with E2BIG:

nanocoder run --prompt-file prompt.md

If a tool requires approval that the active mode won't grant, nanocoder prints Tool approval required for: ... and exits with status code 1 in the Ink runtime, or 2 under the --plain runtime (used automatically in CI and non-TTY environments, and always with --json).

Because there is nobody to answer a prompt in a run, the agent-loop retry limits hard-stop instead of pausing: a model that repeats the same tool call, returns empty responses, or keeps emitting malformed tool calls past its configured cap ends the run with an error. The run exits with status code 1 in this case, and also when it fails on a provider or connection error or times out, so CI can tell a failed run from a finished one. Under the --plain runtime (used automatically in CI and non-TTY environments) the error also names the limit that fired.

Warning - CI polling patterns: the repeated-call hard stop triggers on legitimate repetition too. If your workflow's model is expected to run the identical command repeatedly - polling a deploy, waiting on a slow job by re-running the same check - the run aborts once maxRepeatedToolCalls consecutive identical calls are emitted (default 3). Raise nanocoder.retries.maxRepeatedToolCalls in that project's agents.config.json before relying on such a pattern in CI.

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": "string_replace",
      "arguments": { "path": "src/api.ts" },
      "result": "...",
      "error": null
    }
  ],
  "steps": 2,
  "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)
  • steps — how many times the model was called during the run, including retried turns. One step can make zero or several tool calls, so this is not the same as the length of toolCalls. 0 when the run stopped before calling the model
  • filesChanged — deduplicated list of file paths touched by file-mutating tools (write_file, string_replace, diff_edit)
  • 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, a provider request that fails with an HTTP error or a dropped connection, the turn limit being hit without a final answer, or an agent-loop retry limit being hit), kind is "error" and the object still includes whatever toolCalls were captured before the failure, so partial progress isn't silently dropped.