Start Guide

neosh is a terminal workspace for running coding agents, built the way Neovim is built. This guide takes you from install to your first conversation.

Install

One command builds neosh from source and puts it on your path:

curl -fsSL https://neoswarm.dev/install.sh | sh

Homebrew, Cargo and a plain source build are covered in Installation.

Start the workspace

neosh

That starts a workspace and attaches your terminal to it. No API key is needed: an existing claude login works as is, and hundreds of models are reachable before you configure anything.

Three things worth knowing on day one:

1. The workspace is a process, and your terminal is a view of it. Closing the terminal detaches, turns keep running, and running neosh again puts you back.
2. neosh stop is what actually ends a workspace. ^Q never can.
3. neosh init writes a starter config you can edit later. You do not need it to begin.

Your first conversation

1. Type a message and press ⏎. That starts a turn.
2. While the turn runs, ⏎ steers it: your message is held and taken in at the agent’s next gap.
3. Esc interrupts. The agent is asked to stop, so the conversation survives it.
4. ^P picks a different model, even mid turn.
5. ^N starts a new conversation. In a repository it asks where: right here, a fresh worktree, an existing one, another machine, or somewhere else.

A worktree you did not name gets its branch named from your first message, so fix/composer-paste-truncation appears instead of a random placeholder.

Find your way around

Next steps

• Concepts explains the workspace model in five minutes.
• Keys is the short version of every binding that ships.
• Configuration covers init.ts and config.toml.
• Plugins shows how to write and install one.