# Quickstart

This page gets you from install to a useful first neko session. Neko is a fork of the pi coding agent; these docs use the neko names (`neko`, `~/.neko/`) throughout.

## Install

Neko is distributed as an npm package:

```bash
npm install -g --ignore-scripts @neko-mono/coding-agent
```

`--ignore-scripts` disables dependency lifecycle scripts during install. Neko does not require install scripts for normal npm installs.

This installs the `neko` command (and its `catgirl` alias).

On macOS and Linux you can alternatively install a standalone binary release:

```bash
curl -fsSL https://get-neko.mcqueen.horse/install.sh | bash
```

This installs to `~/.neko/app/<platform>` and symlinks `neko`/`catgirl` into `~/.local/bin`. On Windows, download the zip from `https://get-neko.mcqueen.horse/releases/latest/` instead.

### Uninstall

Use the package manager that installed neko:

```bash
# npm install -g
npm uninstall -g @neko-mono/coding-agent

# pnpm
pnpm remove -g @neko-mono/coding-agent

# Yarn
yarn global remove @neko-mono/coding-agent

# Bun
bun uninstall -g @neko-mono/coding-agent
```

For binary installs, remove `~/.neko/app` and the `~/.local/bin/neko` and `~/.local/bin/catgirl` symlinks.

Uninstalling neko leaves settings, credentials, sessions, and installed packages in `~/.neko/agent/`.

Then start neko in the project directory you want it to work on:

```bash
cd /path/to/project
neko
```

## First-time setup

On the first interactive start, neko runs a short setup wizard:

1. **Theme** - dark or light, with a live preview.
2. **Provider login** - log in to one or more providers via OAuth subscription or API key. The first login also picks a default model.
3. **Subagent tiers** - optionally pin heavy/medium/light models for delegated work (a detected flagship model prefills the heavy tier).
4. **Web search** - toggles, an optional summary model, and an optional Exa API key. Works out of the box without any of it.
5. **Defaults review** - neko's opinionated defaults, shown next to pi's, adjustable per row.
6. **Pick your neko** - the pixel cat that lives above the editor: skin, size, or no cat, with a live preview.
7. **Analytics opt-in** and a finish screen with tips.

Every step can be skipped; Esc goes back (and leaves setup from the first step). If setup is interrupted (Esc out or Ctrl+C), it re-offers on the next launch, prefilled with the choices already made. To re-run a completed setup, delete `~/.neko/agent/settings.json`.

## Authenticate

If you skipped the login step, neko can authenticate later through `/login` (subscription or API-key providers), or through environment variables.

### Option 1: subscription login

Start neko and run:

```text
/login
```

Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.

### Option 2: API key

Set an API key before launching neko:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
neko
```

You can also run `/login` and select an API-key provider to store the key in `~/.neko/agent/auth.json`.

See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.

## First session

Once neko starts, type a request and press Enter:

```text
Summarize this repository and tell me how to run its checks.
```

By default, neko gives the model four tools:

- `read` - read files
- `write` - create or overwrite files
- `edit` - patch files
- `bash` - run shell commands

Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Neko runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.

## Give neko project instructions

Neko loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:

```markdown
# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.
```

Neko loads:

- `~/.neko/agent/AGENTS.md` for global instructions
- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory

Restart neko, or run `/reload`, after changing context files.

## Common things to try

### Reference files

Type `@` in the editor to fuzzy-search files, or pass files on the command line:

```bash
neko @README.md "Summarize this"
neko @src/app.ts @src/app.test.ts "Review these together"
```

Images or text can be pasted with Ctrl+V (Alt+V on Windows); images can also be dragged into supported terminals.

### Run shell commands

In interactive mode:

```text
!npm run lint
```

The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.

### Switch models

Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.

### The cat

A pixel cat sits above the editor: it paces while the model works, sprints in `/fast` mode, and streams a rainbow wake in `/ultra` mode. `/neko` configures it (`/neko mini`, `/neko large`, `/neko dilute`, `/neko off`). To not load it at all, add `"extensions": ["-neko-cat.ts"]` to your settings.

### Continue later

Sessions are saved automatically:

```bash
neko -c                  # Continue most recent session
neko -r                  # Browse previous sessions
neko --name "my task"    # Set session display name at startup
neko --session <path|id> # Open a specific session
```

Inside neko, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.

### Non-interactive mode

For one-shot prompts:

```bash
neko -p "Summarize this codebase"
cat README.md | neko -p "Summarize this text"
neko -p @screenshot.png "What's in this image?"
```

Use `--mode json` for JSON event output or `--mode rpc` for process integration.

## Next steps

- [Using neko](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference.
- [Providers](providers.md) - authentication and model setup.
- [Settings](settings.md) - global and project configuration.
- [Keybindings](keybindings.md) - shortcuts and customization.
- [Packages](packages.md) - install shared extensions, skills, prompts, and themes.

Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md).
