Start your first conversation

Open a project, connect an AI provider, pick a model and a run mode, then work with an agent.

An agent conversation is where you ask an AI agent to read, change or explain the code in a project. This page walks through the first one, from opening a folder to reviewing the result.

1. Open a project

A project is a folder on your computer. On the home screen, choose one of:

  • Open a project to pick a local folder.
  • Recent projects to reopen a folder you used before.

To work on a folder that lives on another computer, see Remote machines.

On Windows, Open folder… in the menu does the same thing.

2. Connect an AI provider

Neoo does not sell AI usage: each agent runs on your own account with the provider. Open Settings → Providers to see which ones are ready. Each row shows Connected or Not connected.

ProviderHow to connect it
ClaudeAdd your Claude account in Settings → Providers → Add account, or sign in with claude auth login in a terminal.
CodexAdd your ChatGPT account with Add account, or sign in with codex login.
GeminiAdd account, sign in with Google, then paste the code into Authorization code and click Submit code.
CursorPaste your key into Cursor API key, or sign in with cursor-agent login.
OpenRouterPaste your key into OpenRouter API key and click Save.
AntigravityPaste a Gemini key into Gemini API key (Antigravity).
OpenCodeInstall OpenCode. Free models work without an account.
Neoo AINothing to do: it is available as soon as you are signed in to Neoo.

Grok is also listed. For every provider in detail, see Connect your AI accounts.

When Claude Code, Codex or Gemini isn't installed on this computer, click Install automatically on its row. Neoo downloads the provider's official command-line tool, checks its fingerprint and installs it for Neoo only — no terminal needed. A progress bar shows the download (about 95 MB for Claude Code, 130 MB for Codex and 55 MB for Gemini on a Mac). If you send a message before installing, Neoo installs the tool first, then runs the turn.

If you prefer to install the command-line tool yourself, or for the other providers, click Open terminal on the row: Neoo opens a terminal with the right install or sign-in command. A tool you install yourself always takes priority over the one Neoo installed.

3. Start the conversation

  1. Click New Agent at the top of the sidebar.
  2. In Choose a project, select your project.
  3. Type your request in the message field and press Enter, or click the round send button with the arrow. It fills with blue as soon as there is something to send.

In the message field, Page Up moves the cursor to the start of your text and Page Down to the end. Hold Shift to select up to there.

Be specific: say what you want, where, and how you'll know it's done. For example: "Add a dark mode toggle to the settings page and keep the user's choice after a restart."

4. Choose a model

The model name under the message field opens the model picker. Search for a model, keep Automatic to let Neoo choose, or star models to find them under Favorites.

If a model belongs to a provider that isn't connected, the picker says so and offers Sign in.

5. Choose a run mode

The + menu of the message field has a Run mode section. It decides what the agent may do without asking you.

ModeWhat the agent can do
PlanSuggests a plan without changing any file.
Default permissionsAsks before editing files, running commands or going outside the project.
Approve for meA reviewer allows safe actions automatically and asks you only for risky ones.
Full accessNever asks. Use it only on projects you are ready to let the agent change freely.

A mode change during a running turn applies to your next message.

6. Add context

  • Type @ to mention a file, a folder or another conversation.
  • Use Add image or file in the + menu, or paste or drag files onto the conversation.
  • To reuse a file in another conversation, drag it from the message box onto that conversation in the sidebar, or onto its message box in split view. The conversation opens with a copy of the file attached, and the file stays attached where it was.
  • Type / to open Commands and skills.
  • What you type and the images you attach stay in the message box if Neoo restarts (update, crash, closing the app), in agent conversations and in bot conversations. An image whose temporary file was deleted in the meantime is removed from the box.
  • Use the microphone button to Record a voice note instead of typing.

7. Follow and steer the agent

While the agent works, you can:

  • Click Stop turn to stop it. This works even while commands the agent started in the background are still running: the agent stops right away instead of waiting for them.
  • When the reply is already written but background tasks are still running, the message box reads "Reply ready — … background task(s) still running". Click the red stop button, End the wait, to stop those tasks and close the turn on the reply you already have. If the wait has not closed after about 15 seconds, Neoo stops the turn for you. A command the agent is still waiting on, even a long one, never counts as a background task: only commands started or moved to the background do.
  • A Claude command that runs past its time limit keeps running in the background. Once the reply is written and that command has printed nothing for 2 minutes, Neoo reminds the agent to stop it if it isn't needed, then again every 10 minutes. After 30 minutes without output, Neoo stops the command itself: the agent reports it and the turn closes, and the command's entry under Activity shows that Neoo stopped it. Commands the agent starts in the background on purpose are never stopped this way; they end when they finish or reach their own time limit.
  • Send another message. Choose Add to queue to send it after the current turn, or Steer to send it right away without interrupting.
  • Answer its questions and approval requests as they appear in the conversation.

Read the reply

A turn ends with the agent's answer, placed under a collapsible Worked for … block that holds the reasoning, the commands and the tool results (for example Worked for 14 s · 5 steps). Open it to retrace the work; everything you need to read stays outside of it.

The conversation reads in order, like a chat:

  • When the agent explains something and then asks you a question or shows a canvas, that explanation stays visible in the conversation, right above the question or the canvas. You never need to open the work block to understand what you are asked.
  • When an answer comes with a mock-up or a code sample, it is shown in a Preview block under the list of answers, in a fixed-width font so that diagrams stay aligned. Point at another answer, or reach it with the keyboard, to see its preview; the block keeps the last one you looked at.
  • Once you answer a question, your choice appears on the right as Your answer, followed by the work the agent does next. A skipped question shows Question skipped.
  • A canvas stays where the agent created it, between the work before and after it.
  • When the agent answers, suggests a next step, and you accept it, you read the first answer, the suggestion, your choice, the new work, then the second answer, in that order.

A note added at the end by a search or a check left running in the background completes the answer instead of replacing it, separated by a horizontal rule. Plain progress lines — "still waiting", "the check is still running" — stay in the work block.

With Claude, a stop hook (from your Claude Code settings or a plugin, for example a design review) can make the agent pick up again right after it answered, in the same turn. You still read that first answer, followed by what the agent wrote afterwards, separated by a horizontal rule. The work block shows a Stop hook step ("A stop hook resumed the agent after its answer.") at the point where the agent resumed. This also holds when you reopen the conversation later, including for turns that ran before Neoo detected this, as long as the Claude session transcript is still on your computer. Without it, such an older turn only shows the last answer; the first one is still in the work block.

Follow subagents

When the agent hands part of the work to a subagent, a Subagent card appears in the conversation, with a spinner while it runs. Click it to open that subagent's own conversation and follow it live. Click Main conversation to go back. The cards stay visible after the turn ends, and they also appear in Bot chats.

If the agent sends a finished subagent new instructions, or a subagent picks up again by itself once a background command it started ends, the conversation keeps waiting for it. A new running entry with the same name appears under Activity in the conversation's side panel; the earlier entry stays finished.

Save an image or a video

When an agent produces an image, a video or audio, it appears in the Media block at the top of the turn's work, with the number of items and an Open all button that opens the full gallery. Only what a generation tool (image, video, audio) or an MCP integration actually produced goes there: files the agent reads, lists, writes or finds through the shell or the browser — including network requests — never appear as media. Files a Bot explicitly sends you stay as attachments under its reply.

To keep a media file outside the project folder:

  • Click the download button next to the file name, or
  • Click the image to open the preview, then use Download at the top right. Copy image puts it in the clipboard instead.

Neoo asks where to save the file and proposes the name the agent used.

Images of 96 px or less — icons, logos — are grouped into a row of square thumbnails placed after the larger previews, so a logo never takes as much room as a screenshot. Beyond six of them, a +N button opens the full Media gallery, where every file is shown at full size. A larger local image carries its file name and its pixel size along the bottom edge.

Open an image or a video the agent mentions

A file path in an agent's reply, written as code or as a link, is clickable. In a conversation, the file opens in a tab of the conversation's side panel, next to the browser and Design tabs. Code and text open read-only, with line numbers. An image opens in an image viewer where you can Annotate image and copy it. A video or an audio file plays with the native controls, and a video can be as large as 500 MB.

Elsewhere in the app, such as the Git review, text files open in the file viewer, and images (PNG, JPEG, GIF, WebP, BMP, AVIF, ICO) and videos (MP4, M4V, MOV, WebM, MKV, AVI) open in the same full-screen preview as the media of the conversation: Download saves a copy and Copy image puts an image in the clipboard. Press Esc or click outside the media to close it. An SVG shows as an image in a conversation tab; elsewhere it stays in the file viewer, so you can read its source.

A relative path is resolved from the conversation's project folder, including a path that goes up a level, such as ../other-project/out/demo.mp4. When you click a file outside the folders you opened, Neoo lets the preview read that one file, not the folder around it. If a file cannot be read — too large, missing, or a format the app cannot play — the viewer shows the reason, and Open in default app hands the file to your system.

Right-click a reference in a reply

Right-click a file path, a link, a command or any other code in an agent's reply to see what you can do with it. The menu depends on what the reference is:

  • File (including a line range such as src/App.tsx:41-46, which opens at the first line): Open here, Open in integrated browser for HTML, SVG, PDF, images and videos, Open in VS Code or Open in Cursor when its command-line launcher (code, cursor) is on your PATH, Open with default app, Reveal in File Explorer (Windows) or Reveal in Finder (macOS), Show changes, Mention in prompt (adds @path to your message), and copy the relative path, the absolute path or the path:line reference.
  • Folder: reveal it, Open terminal here, mention it, or copy its path.
  • GitHub pull request: a left click or Open pull request in Neoo opens its details (summary, timeline, code, review and merge actions) in a panel next to the conversation, the same way as an issue. The pin button (Pin pull request details across conversations) keeps that panel open when you switch conversations, until you close it. If the conversation's folder is not a Git repository on this computer, and in a Bot's conversation or work, a left click or Open pull request in Neoo opens the pull request in the GitHub view instead, not in your browser. The GitHub view looks among open, merged, then closed pull requests; a pull request of a repository with no open pull request in your projects (another repository, for example) opens its details directly, read with the GitHub CLI from one of your project folders. Your external browser is only used when none of your project folders is a Git repository, or from a separate window. Pull requests, issues and commits can also open in the integrated or external browser, and you can copy the link or repo#number. A pasted pull request or issue URL shows as repo#number with a GitHub icon.
  • Web link: open it in the integrated or external browser, or copy it. A left click opens localhost and local network addresses in the integrated browser, and other sites in your external browser.
  • Command (such as npm run dev): Prepare in terminal opens a terminal with the command typed but not run, so you can read it and press Enter yourself.
  • Commit hash: Show commit opens it in the side panel.
  • Branch (such as main or origin/feature-x): Check out asks you to confirm before switching, and Show branch opens the branch panel.
  • Name in code (a function, a variable, a constant): Add to prompt, or copy.

Anything else can be copied. If you select text first, right-click keeps the usual Copy menu. In a read-only conversation, only the actions that do not need the conversation remain.

8. Go back in time

Hover one of your earlier messages and choose Edit and restore from this message. Neoo asks Rewind to this message? and warns you if files created after that message will be deleted. See Checkpoints and rewind for details.

With Claude and Codex, the rewind also restores your files to how they were at that message. With other providers, only the conversation goes back; your files stay as they are.

9. Rename, pin or archive a conversation

Right-click a conversation in the sidebar (on a Mac, you can also Control-click it) to open its menu:

  • Rename: the title becomes a text field. Press Enter or click elsewhere to save, or Esc to cancel. You can also select the conversation with the keyboard and press F2.
  • Pin / Unpin: keeps the conversation at the top of the sidebar.
  • Settle / Un-settle (Activity view only): moves the conversation to the Settled shelf.
  • Archive / Unarchive.

Titles are kept on one line and limited to 200 characters. The same menu works in Remote (for conversations on another of your computers) and in the Neoo web app. The new title appears everywhere the conversation is shown, including your phone. Conversations that come from Forge, and Team conversations started by someone else, can't be renamed.

Next steps