Connectors, Server and Git

The System group in the Settings rail holds three pages: Connectors, Server and Git. They connect Neova to outside services, to your coding agents, and to git.

Connectors

Open it from Settings › Connectors.

Connectors bring outside sources into Neova. Click Add connection and pick one:

Option	What it does
Email account	Emails in a chosen folder become tasks.
Telegram bot	Chat with your agents from your phone.
GitHub repo	Pull issues into a stage.
Stream Deck	A key per running agent; press it to open the agent’s terminal.

The page lists your connections in sections: Email, Telegram and GitHub.

Email

Each email account shows its name, its status, its address and server, and which folder syncs to which stage (Syncing folder → stage). An account without a folder and stage shows Sync not configured.

The status is Idle, Live, Reconnecting…, Error or Live sync unavailable. On Error and Live sync unavailable, the reason shows below the name. Click the status to fix it: it opens the account details, or the sync settings when the mailbox folder is missing.

Button	What it does
Sync now	Imports new emails right away. Shown once sync is configured.
Configure sync	Choose the mailbox folder and the target stage.
Edit account	Change the account details.
Remove	Removes the account after you confirm. Tasks already imported stay in Neova as regular tasks.

How to add an email account

1. Click Add connection › Email account. The Add email account dialog opens.
2. Fill in Account name, Email address, IMAP host, Port and App password. Use an app password generated by your email provider. Under Advanced you can set a Username if it differs from the email address.
3. Click Test connection. Save becomes available when the test succeeds.
4. Click Save. The Configure sync dialog opens.
5. Under Mailbox folder, Neova looks for a folder named “Neova”. If there is none, click Create folder on server.
6. Under Target Stage, pick the stage. Each new email becomes a task in this stage.
7. Click Save configuration. Neova imports the emails in the folder, newest first. Tasks appear in the stage as they import.

Telegram

A Telegram bot lets you chat with the Neova Assistant from Telegram and get a message when an agent needs you. You connect one bot per project. The bot only works while Neova is running with this project open.

Each bot shows its name, its status and the Telegram user it is paired with. The status is Connected, Not paired, Idle or Error. If another app or Neova window uses the same bot token, the status says so.

Button	What it does
Send test	Sends a test message to the paired chat. Available while the bot is connected.
Notification settings	Choose what the bot forwards.
Disconnect	After you confirm, the bot stops and its token is removed from the Keychain. The bot itself stays on Telegram.

Notification settings has three parts:

Part	What it forwards
Agent notifications	Messages agents send with notify_user, by level: Info, Success, Warning.
Agent status	Agent needs attention: a message when an agent is waiting on you.
Stages	A message when a task enters a stage. Pick All stages or specific stages.

How to connect a Telegram bot

1. Click Add connection › Telegram bot.
2. In Telegram, open @BotFather and run /newbot. Pick a username that ends in bot.
3. In Neova, fill in Account name and paste the Bot token.
4. Click Validate token. When the token works, Neova shows the bot’s username. Click Continue.
5. In Telegram, send /start to your bot. Neova waits for it.
6. Neova shows the Telegram account that sent /start. Click Pair and save.

Neova renames the bot to match the project.

GitHub

A GitHub connection pulls issues from one repository into a stage when you ask. Each task links back to its issue. Issues already imported are skipped. Nothing is sent to GitHub.

Each repository shows which issues it pulls (All open issues or Issues labelled label) and its status.

Button	What it does
Pull issues	Pulls new issues now.
Edit repo	Change the settings.
Remove	Removes the connection after you confirm. The token is removed from the Keychain. Imported tasks stay as regular tasks.

How to add a GitHub repo

1. Click Add connection › GitHub repo.
2. Fill in Repository as owner/name, or paste the repository’s web address.
3. Paste an Access token: a fine-grained token with read-only access to Issues on this repository. Create one on GitHub opens the page to make one. The token is stored in your Keychain.
4. Under Which issues, choose All open issues or Only open issues with the label and type the label.
5. Under Add new issues to Stage, pick a stage.
6. Click Test connection to see how many issues match, or click Save. Save checks the connection first.

Stream Deck

The Stream Deck connection shows a key for each running agent, with its status. Press a key to open that agent’s terminal.

How to set up Stream Deck

1. Click Add connection › Stream Deck.
2. Stream Deck app: Neova checks that the Stream Deck app is installed. It needs version 7.1 or later. If it is missing, click Download Stream Deck.
3. Install the Neova plugin: click Install plugin and confirm the install in the Stream Deck app. Use the same button to update the plugin later.
4. Place the keys: in the Stream Deck app, open the Neova Studio category and drag Neova Agent onto as many keys as you like. The keys fill with the running agents of the project in front, in sidebar order.
5. When the plugin connects, the dialog shows Connected. Click Done.

Server

Open it from Settings › Server.

The MCP Server is how coding agents connect to Neova. Each open project runs its own server.

Server status

The top card shows Server running with the port and the number of connected agents, or Server stopped.

Part	What it does
Port (leave empty for auto)	Shown while the server is stopped. Type a port from 21700 to 21899, or leave it empty and Neova picks one. If another project uses the port, its name shows under the field.
Projects	Lists all known projects with their port and when they were opened.
Start Server / Stop Server	Starts or stops the server.

To change the port, click Stop Server, type the new port and click Start Server.

Access

Access sets who can connect to this server and which tools they get. Every connection presents a key.

Part	What it does
Require access keys	When on, a connection with no key or a revoked key is refused. When off, any client that reaches the server gets every tool. Start the server before you turn it on.
Grants tab	The keys you have issued.
Presets tab	Named sets of tools that you apply to grants.
Recent refusals	Connections that were refused, with the agent’s name, the reason and when. Shown when there are any.

When you turn on Require access keys, Neova asks you to confirm. It then gives this project’s own agents a key and adds it to .mcp.json. Agents that are running stay connected and use the key after their next restart. Config files of other tools, such as Cursor’s or Gemini’s, are not changed.

If this project’s agents use a key from one of your grants, a banner says so. Click Use this project’s key to give them the project’s own key.

Grants

The table shows each grant’s name (Grant), its Scope preset, how many connections are live (Connected) and when it was last used (Last used). The ⋯ menu on a grant has:

• Change scope: apply another preset. This replaces the grant’s tool list with a copy of the preset’s.
• Rotate key: issue a new key for the grant.
• Revoke: the key stops working at once and cannot be restored.

Changing or revoking a grant closes its live connections. They reconnect under the new scope.

How to issue a key

1. On the Grants tab, click New grant.
2. Type a Name, for example “Team B”.
3. Pick a Scope preset, or choose New preset — pick the tools yourself….
4. Click Create grant.
5. Copy the Key. It is shown only once. Neova keeps a hash of it, so if the key is lost, rotate the grant.
6. Copy the snippet under Add this to the other project’s .mcp.json, or click Or write it into a project for me… and pick a project folder. Neova merges the entry into that folder’s .mcp.json.
7. Click Done, and restart the other project’s agents.

Presets

A preset is a named set of tools. Neova ships the presets Read-only board, Tasks, Collaborate and Full, marked Built-in. Each preset shows its number of tools. Presets that include tools which control the machine (terminal_send, schedule_action, restart_agent, start_agent) are flagged.

Applying a preset copies its tools into the grant. Editing the preset later does not change grants that already use it.

Click New preset, or Edit, Duplicate or Delete on a preset. In the preset dialog, type a Name, filter with Filter tools, tick the tools to allow, and click Save preset. Tools you do not tick are denied.

Agent Configuration

Add Neova as an MCP server in your coding agent’s configuration. Pick your agent from the tabs: Claude Code, Cursor, Gemini, Mistral Vibe or OpenCode.

Each tab shows the configuration to add, with a Copy button, a line that says where it goes, and a View docs link to the agent’s own documentation.

Tab	Where the configuration goes
Claude Code	.mcp.json in your project
Cursor	.cursor/mcp.json in your project
Gemini	Your Gemini CLI configuration
Mistral Vibe	Your Mistral Vibe configuration
OpenCode	Your OpenCode MCP configuration

On Claude Code and Cursor, a card writes the file for you:

Card says	Button	What it does
Configure the MCP connection in this project directory	Add to Project	Creates the file with the Neova entry.
Add Neova to your existing MCP configuration	Add Neova	Adds the Neova entry to your existing file.
Update Neova in your MCP configuration	Update	Replaces an old Neova entry.
Neova is configured in this project	Configured	Nothing to do.

On Claude Code, a second card, Report agent status for Claude sessions you start yourself, adds Neova’s status hooks to .claude/settings.local.json. Agents that Neova starts already report their status. Click Add to settings, or Update when the hooks are out of date.

For a step-by-step guide per agent, see Connect a coding agent.

Available Tools

A list of all MCP tools that coding agents can use, grouped by category. Search with Search tools…. Click a category to see its tools and their descriptions. See MCP tools.

Git

Open it from Settings › Git.

Goal worktrees

Setting	What it does
Work on goals in separate folders	When on, each goal you open work on gets its own folder and branch, so agents on different goals never touch each other’s files. Tasks that are not on a goal stay on the branch you have checked out. Off by default.
Where the folders live	Shown when on. The folders are next to the project, outside it, in ../<project>.worktrees/. Hover to see the full path.
How it works	Shown when on. Opens five steps, from opening work on a goal to closing it.

The switch is unavailable when no project is open, when the project is not a git repository, when it sits inside a larger repository, or when git is not installed. The page then says which.

The five steps:

1. Open work on a goal in Project › Goals. It gets its own folder and a fresh branch from what your main folder has checked out.
2. Put an agent there: on an offline agent’s page, use Start Terminal ▾ and pick the goal. A running Claude agent can also switch itself when it picks up a task on that goal.
3. Update from main when main has moved on. If files clash, nothing changes and the goal’s agent resolves them.
4. Merge into main, one goal at a time. Your own unsaved edits in the main folder are never touched. Push to GitHub to back up or share the branch.
5. Close work to remove the folder. This is refused while there is uncommitted work or an agent inside. The branch is kept if it has commits that main does not.

Every goal folder is listed under Tools › Git › Worktrees. See Goals and Git.

Neova Git repository

Neova Git keeps a version history of your project data. It commits your tasks, wiki pages, agent notes, goals and skills to a git repository inside .neova/, on a branch named neova. Everything stays on this computer. Your code repository is not touched.

State	What you see
Not set up	Set up Neova Git.
Project files still tracked by your code repository	How many files, and the commands to run in the project folder to untrack them. Neova notices when you have run them.
Git not installed	Git is not installed on this computer.
Set up	A Set up badge, the Repository row (.neova/.git, branch neova) and Open in Tools › Git.

How to set up Neova Git

1. Click Set up Neova Git. A dialog lists what Neova will do.
2. Click Set up. This usually takes a few seconds.
3. When it says Neova Git is set up, click Done. From now on, every change is recorded automatically.

If set-up does not finish, Neova undoes what it had created and shows what went wrong. Click Try again.

Back up to GitHub

Shown once Neova Git is set up.

Row	What it shows
Backup status	Backing up to remote, or Not backed up. Backing up pushes the history to the neova branch. Anyone who can read that repository can read your tasks, wiki pages and agent notebooks.
This computer’s name	The name shown next to each change, so you can tell your machines apart. Click Change, type a name and click Save.

What gets backed up

Tick the folders to include. All are ticked by default.

• tasks/
• wiki/
• agents/ (incl. notebooks)
• goals/ · skills/
• snippets/

These are never included: logs/ · workspace/ (runtime state), connectors/ (personal and infrastructure details), editor-state.json (specific to this computer) and images/.

Related

• Connect a coding agent
• MCP tools
• MCP Servers
• Git
• Goals
• Assistant, which uses the Telegram bot and the MCP server