# neosh

> A terminal-first, Neovim-inspired agent workspace for running and orchestrating AI coding agents across multiple models and machines.

neosh is an open-source terminal workspace for running AI coding agents, built in the spirit of Neovim — every feature is a plugin, and every plugin uses the same public API. It is developed by the neoswarm organization, released under the MIT license, and described on its homepage as "an agent swarm for power users." The project is written primarily in Rust with a TypeScript plugin layer, and reached v0.2.0 in August 2026.

## What It Is

neosh is a TUI (terminal user interface) agent orchestrator that lets developers run, steer, and switch between AI coding agents without leaving the terminal. It manages conversations, git worktrees, and remote machines from a single persistent workspace process. The tool is explicitly non-profit and community-held, with no company behind it and no paid tier.

## How the Workspace Model Works

The workspace runs as its own background process; terminals attach to it like windows into a shared state. Closing a terminal detaches without stopping any running agent turns. Key behaviors include:

- **Persistent turns** — agents keep running after the terminal closes; `neosh` reconnects to the live state
- **Worktrees built in** — each conversation gets its own git branch, named automatically from the first message
- **Multi-terminal** — multiple terminals (or teammates) can attach to the same workspace simultaneously
- **Machine pairing** — computers can be paired over ASCP so agents running on a remote machine can be steered locally

## Plugin Architecture

The plugin system is the architectural centerpiece. Every built-in feature — the sidebar, git integration, the command palette, the chat panel — is itself a plugin written on the same public TypeScript API available to third-party authors. A plugin is a folder containing a `plugin.toml` and a `main.ts`; dropping it in is enough to activate it. The API is fully typed via `@neosh/api`. Any built-in can be disabled or replaced in the user config, and the configuration layout mirrors Neovim: `~/.config/neosh/init.ts` is a plugin with full API access, and `config.toml` sits beside it for plain settings.

## Model Support

neosh supports a wide range of AI models through four driver types:

- `claude-cli` — uses an existing `claude` CLI login with no API key required
- `anthropic` — direct Anthropic API via `ANTHROPIC_API_KEY`
- `openai-compat` — any endpoint speaking the OpenAI-compatible shape
- `google` — Google Gemini via `GEMINI_API_KEY`

The homepage states that 423 models are reachable before any configuration is needed. Models can be switched mid-turn with `^P`, and per-model options are set via config entries rather than code.

## Setup Path

Installation is a single curl command that builds neosh from source. Homebrew (`brew install neoswarm/tap/neosh`), npm (`npm install -g neosh`), and Cargo (`cargo install neosh`) are also supported. A source build via `cargo run` is available for contributors. The docs note that a Cargo install builds `deno_core` from source and takes roughly fifteen minutes.

## Update: v0.2.0

The latest release is v0.2.0, published on 2026-08-25. The repository was created in August 2026 and last pushed on 2026-08-26, indicating the project is in active early development. The GitHub repository carries 12 stars and zero forks at the time of indexing. CI runs via GitHub Actions on the main branch.

## Features
- Terminal-first agent workspace
- Persistent workspace process (agents keep running after terminal closes)
- Multi-terminal attach/detach
- Git worktree integration per conversation
- Plugin system in TypeScript with fully typed public API
- Every built-in feature is a plugin and can be replaced
- Support for 400+ AI models via multiple drivers
- Model switching mid-turn
- Machine pairing for remote agent control (ASCP)
- Vim-style keybindings and normal mode transcript navigation
- Command palette
- Configurable via init.ts and config.toml
- Homebrew, npm, Cargo, and source install options
- MIT licensed, no paid tier

## Integrations
Anthropic Claude, OpenAI-compatible endpoints, Google Gemini, OpenRouter, Ollama, Git / git worktrees, Neovim-style keymaps

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.2.0

## Links
- Website: https://neoswarm.dev
- Documentation: https://neoswarm.dev/docs
- Repository: https://github.com/neoswarm/neosh
- EveryDev.ai: https://www.everydev.ai/tools/neosh