# Terminal UI Install `nc`, sign in to Codex or Claude, and run coding sessions in the terminal. ## Overview `nanocode` is a terminal coding agent built on the nanocode SDK, and `nc` is the same program under a shorter name. Without a subcommand, it opens the interactive interface in the current directory, with the workspace tools, Code Mode, subagents, and durable sessions on. ```bash # Open the interface and send the first prompt nc "fix the failing test" ``` The default model is `claude-opus-5-5` at `xhigh` thinking. Sessions, logins, and history live in `~/.nanocode`. ## Walkthrough The steps below install the CLI, sign in, and run a first session. ### Install the CLI The package is `nanocode-cli` in `bin/nanocode`, and it builds the `nanocode` binary with Rust 1.97 or newer. `--locked` builds with the repository's `Cargo.lock`. ```bash # 1. Install the binary from the repository cargo install --locked --git https://github.com/gakonst/nanocode nanocode-cli # 2. Add nc as a link to the same binary ln -s "$(command -v nanocode)" "$(dirname "$(command -v nanocode)")/nc" # 3. Print the installed version nc --version ``` ### Sign In Start `nc`, then run `/login codex` for a ChatGPT login or `/login claude` for a Claude subscription. Each command opens the sign-in page in the browser and prints its URL. The login is saved in `~/.nanocode`. ```bash # Inside nc: sign in to one or both providers /login codex /login claude ``` If no `nanocode` Claude login exists, the Claude harness uses an existing Claude Code login. ### Start a Session Run `nc` in the project directory, or pass `-C` to open another workspace. A prompt argument is sent as soon as the session is ready. ```bash # Open a session in another checkout nc -C ~/src/app "explain the build" ``` ### Steer the Turn The prompt accepts input while a turn runs. `/help` lists every key binding. | Key | Action | | ----------------------- | ------------------------------------------------ | | `enter` | Send, or steer the message into the running turn | | `tab` | Queue a follow-up for after the running turn | | `shift+enter`, `ctrl+j` | Insert a newline | | `esc esc` | Interrupt the running turn | | `@path` | Find a file and insert its path | | `!command` | Run a shell command locally | | `ctrl+v` | Attach an image from the clipboard | | `ctrl+g` | Edit the prompt in `$EDITOR` | | `ctrl+d`, `ctrl+s` | Open the model picker or the thinking dial | | `ctrl+o` | Cycle how tool calls and reasoning show | | `ctrl+t` | Toggle the tree of active subagents | | `ctrl+c` | Clear the draft, or quit when pressed twice | ## Recipes ### Pick a Model `-m` takes a model ID or alias, and `-t` a thinking level the model supports. `--harness` selects a harness's default model when `-m` is absent. Inside a session, `/model`, `/thinking`, and `/fast` change them. ```bash # 1. List models with their thinking levels and service tiers nc models # 2. Start on Luna at high thinking, on the fast tier nc -m luna -t high --tier fast ``` ### Resume a Session Sessions save to `~/.nanocode/sessions.jsonl` unless `--ephemeral` is set. Resuming needs a saved session, so `--ephemeral` and `--resume` reject each other. ```bash # 1. Continue the latest session in this workspace nc -c # 2. Pick a saved session, or name one by ID nc resume nc resume 01970000-0000-7000-8000-000000000000 # 3. List saved sessions, or print one session's messages nc sessions --all nc sessions 01970000-0000-7000-8000-000000000000 ``` ### Add Project Instructions Both harnesses read `AGENTS.md` files into the agent's context. `~/.nanocode/AGENTS.md` applies to every workspace. In the project, each directory from the Git root down to the workspace contributes its `AGENTS.md`, and an `AGENTS.override.md` replaces the `AGENTS.md` in the same directory. ```bash # Add an instruction for every session in this repository echo "- Run cargo test before you finish." >> AGENTS.md ``` ### Insert a Skill A skill is a directory with a `SKILL.md` file. `/skills` lists the skills in `~/.nanocode/skills`, `~/.agents/skills`, and the `.agents/skills` directory of each directory from the workspace up to the Git root, then inserts the selected one. ```bash # Create a project skill that /skills lists mkdir -p .agents/skills/release && echo "# Release" > .agents/skills/release/SKILL.md ``` ### Run a Command Type `/` to complete a command. The common commands are below. | Command | Result | | ------------------------------------ | ----------------------------------------------------------- | | `/model`, `/thinking`, `/fast` | Change the model, thinking level, or service tier | | `/new`, `/resume` | Start a new session, or resume a saved one | | `/btw` | Open a forked side thread that never interrupts the turn | | `/agents`, `/agent #id`, `/stop #id` | Show, focus, or close subagents | | `/compact`, `/context` | Compact the conversation, or show its token usage | | `/skills`, `/image` | Insert a skill, or attach a clipboard image | | `/runner` | List, connect, listen for, select, or disconnect hands | | `/session`, `/id` | Show session details, or copy the session ID | | `/copy`, `/theme`, `/mouse` | Copy the last reply, set the theme, or toggle mouse capture | | `/reload` | Restart every `nc` window with the newest binary | | `/quit` | Exit | ### Move the Home `--home` or `NANOCODE_HOME` replaces `~/.nanocode`. The directory holds `sessions.jsonl` and its index, `history.jsonl`, the `auth.json` and `claude.json` logins, global `AGENTS.md`, `skills/`, and telemetry under `log/`. ```bash # Keep a separate set of sessions and logins NANOCODE_HOME=~/.nanocode-work nc ``` ### Attach a Hand A hand runs this session's Code Mode cells on another machine. `--runner-host` listens for a hand, and `nc hand` dials it with the same token. ```bash # 1. On the brain: listen for hands export NANOCODE_RUNNER_TOKEN=$(openssl rand -hex 32) nc --runner-host 127.0.0.1:9000 # 2. On the hand: dial the brain from a checkout nc hand ws://127.0.0.1:9000 --name build-box -C ~/src/app ``` ### Turn Off Telemetry `nc` writes OpenTelemetry traces and metrics to `~/.nanocode/log/otel/-/` by default. `--telemetry off` records nothing, and `--otel-endpoint` also exports to an OTLP/HTTP collector. ```bash # Run one session without traces or metrics nc --telemetry off ``` ## More - [Headless Runs](/docs/guides/exec): Run one prompt from scripts and CI with nc exec. - [Remote Hands](/docs/guides/remote-hands): Run Code Mode cells on other machines. - [Model Gateways](/docs/guides/gateways): Route Codex models through OpenRouter, Vercel, or Cloudflare. - [CLI](/docs/api/cli): Every subcommand, flag, and environment variable.