# @neosh/titles

> Names a conversation after what it turned out to be about.

Latest version **0.5.0** (published 2026-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @neosh/titles
pnpm add @neosh/titles
yarn add @neosh/titles
bun add @neosh/titles
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2026-09-25 |
| First published | 2026-08-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 6.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 32 |
| Maintainers | meszmate |
| Keywords | neosh, neosh-plugin |

## Links

- npm: https://www.npmjs.com/package/@neosh/titles
- Repository: https://github.com/neoswarm/neosh
- Homepage: https://github.com/neoswarm/neosh#readme
- Issues: https://github.com/neoswarm/neosh/issues
- npm.io page: https://npm.io/package/@neosh/titles

## Recent versions

- 0.5.0 (latest) — 2026-09-25
- 0.4.11 — 2026-09-22
- 0.4.10 — 2026-09-17
- 0.4.9 — 2026-09-16
- 0.4.8 — 2026-09-16
- 0.4.7 — 2026-09-10
- 0.4.6 — 2026-09-09
- 0.4.5 — 2026-09-06
- 0.4.4 — 2026-09-05
- 0.4.3 — 2026-09-05
- 0.4.2 — 2026-09-04
- 0.4.1 — 2026-09-04
- 0.4.0 — 2026-09-03
- 0.3.0 — 2026-08-30
- 0.2.0 — 2026-08-25
- … 1 more at https://npm.io/package/@neosh/titles/versions

## README

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
    <img src="docs/assets/logo-dark.svg" alt="neoswarm" width="440">
  </picture>

  <p><b>Neovim for controlling AI agents.</b><br />A terminal workspace where every feature is a plugin.</p>

  <p>
    <a href="https://discord.gg/cWdMAqcAn5"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white&style=flat-square" alt="Discord" /></a>
    <a href="https://neoswarm.dev/docs"><img src="https://img.shields.io/badge/Docs-neoswarm.dev-1f6feb?style=flat-square" alt="Docs" /></a>
    <a href="https://github.com/neoswarm/neosh/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/neoswarm/neosh/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status" /></a>
    <a href="./LICENSE"><img src="https://img.shields.io/github/license/neoswarm/neosh?style=flat-square" alt="License" /></a>
  </p>

  <p>
    <a href="#quick-start">Quick start</a> ·
    <a href="#how-it-works">How it works</a> ·
    <a href="#plugins">Plugins</a> ·
    <a href="#configuration">Configuration</a> ·
    <a href="https://neoswarm.dev/docs">Docs</a> ·
    <a href="#community">Community</a> ·
    <a href="#contributing">Contributing</a>
  </p>

  <p><i>⭐ Help us reach more terminal lovers. Star this repo!</i></p>

  <img src="docs/demo.gif" width="100%" alt="neosh running two conversations at once: a turn fixing a flaky test, switching sessions mid-turn, the finished turn going unread, and the transcript read in normal mode" />
</div>

<br />

Run coding agents the way you run Neovim. One workspace, any model, and a public API that every
built-in feature is written on. If you can see it, a plugin can replace it.

## Quick start

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

Or with Homebrew, npm, or from crates.io:

```bash
brew install neoswarm/tap/neosh
npm install -g neosh
cargo install neosh          # builds deno_core from source, so give it a quarter of an hour
```

Or from source:

```bash
git clone https://github.com/neoswarm/neosh
cd neosh
cargo run
```

No API key needed. An existing `claude` login works as is, and 423 models are reachable before you
configure anything. `neosh init` writes a starter config you can edit. Every install option is in
the [installation guide](https://neoswarm.dev/docs/installation).

Start a conversation with the question already in it:

```bash
neosh prompt why is the composer eating my paste
```

A terminal is for one computer. With others paired, `neosh ls` lists them and `neosh connect
<name>` opens a terminal on one — its projects, its conversations, `^N` starting there. Plain
`neosh` asks which whenever another computer is paired, unless `swarm.device` already says, and
`^J` moves a terminal from one to another.

## From a script, or from another agent

`neosh agent` is the workspace without a screen — the same API a plugin uses, over the same socket
a terminal attaches to. A shell loop, a CI job or a coding agent can run ten conversations at once
while you carry on working in the terminal.

```bash
neosh agent start -C ../wt-login "fix the redirect loop"   # prints an id
neosh agent ls                                             # what is running
neosh agent watch                                          # follow, live
neosh agent wait 3f2a1b0c --timeout 900 && ./deploy.sh     # the exit status is the answer
```

Nothing there takes a screen, and what it starts is an ordinary conversation you can open with `^T`.
`neosh skill install` teaches Claude Code, Codex, Cursor and Gemini to drive it. Full reference:
[scripting](https://neoswarm.dev/docs/scripting).

## How it works

The workspace is a process. Terminals attach to it, and each one is somewhere in it: its own
conversation, its own scroll, its own panels, while the work is shared, so every window shows
every turn that is running and where. Close one, the turns keep running, and `neosh` puts you back.

```mermaid
flowchart LR
  T1["Your terminal"] --> WS
  T2["The laptop, later"] --> WS
  T3["A teammate's screen"] --> WS
  subgraph WS["One workspace process"]
    direction TB
    PL["Plugins (TypeScript)<br/>sidebar · git · palette · your init.ts"] --> CORE["One core (Rust)<br/>buffers · windows · keys · turns"]
  end
  CORE --> A["Agents"]
  A --> P["claude · codex · any OpenAI-shaped endpoint"]
  WS -.->|"paired over ASCP"| M["Another machine's workspace"]
```

Everything on screen came through the same API a third party plugin uses. The chat, the sidebar,
git, the palette. All defaults, and a default is something you turn off.

- **One workspace, many terminals** - attach from anywhere, detach without stopping anything
- **Any model** - your `claude` login, an API key, or any OpenAI-shaped endpoint
- **Worktrees built in** - every conversation gets its own branch, named by what you asked for
- **Machines** - pair computers and steer agents that live on them, each one keeps its own files
- **Vim keys everywhere** - read the transcript in normal mode, take pieces of it out
- **Plugins in TypeScript** - fully typed API, and the built-ins are written on it too

## Plugins

A plugin is a folder with a `plugin.toml` and a `main.ts`. Drop it in, it runs.

```ts
import type { PluginContext } from "@neosh/api";

export async function activate({ neosh }: PluginContext) {
  const buf = await neosh.buf.create({ name: "[hello]" });
  await neosh.float.open(buf, { border: "rounded", title: "hi" });
}
```

Guide: [neoswarm.dev/docs/plugins](https://neoswarm.dev/docs/plugins). Writing one with an agent?
Point it at [neoswarm.dev/skill.md](https://neoswarm.dev/skill.md). Built one? Put it in the
[showcase](website/src/data/plugins/README.md). One file, one pull request.

## Configuration

Same layout Neovim uses. `~/.config/neosh/init.ts` is a plugin with the whole API, and
`config.toml` sits beside it for plain settings. See
[neoswarm.dev/docs/configuration](https://neoswarm.dev/docs/configuration).

## Models

| driver | needs |
|---|---|
| `claude-cli` | your existing `claude` login |
| `anthropic` | `ANTHROPIC_API_KEY` |
| `openai-compat` | any endpoint speaking the OpenAI shape |
| `google` | `GEMINI_API_KEY` |

Adding an endpoint is a config entry, never code.

## Documentation

The full docs live at **[neoswarm.dev/docs](https://neoswarm.dev/docs)**.

| Read this | To learn |
|-----------|----------|
| [Start guide](https://neoswarm.dev/docs) | Install, first conversation, the keys that matter |
| [Configuration](https://neoswarm.dev/docs/configuration) | `config.toml`, `init.ts`, and where everything lives |
| [Keymaps](https://neoswarm.dev/docs/keymaps) | Rebinding anything, modes, and the command palette |
| [Models](https://neoswarm.dev/docs/models) | Drivers, endpoints, and per-model options |
| [Machines](https://neoswarm.dev/docs/machines) | Pairing computers and steering remote agents |
| [Writing a plugin](https://neoswarm.dev/docs/plugins) | From empty folder to something on screen |
| [Scripting](https://neoswarm.dev/docs/scripting) | `neosh agent`, running many at once, and the skill for coding agents |
| [Docs for agents](https://neoswarm.dev/docs/agents) | llms.txt, the plugin skill, and what to tell your agent |

## Community

neosh is non profit and held by the people who use it. No company behind it, and not affiliated
with the Neovim project, just built in its spirit.

- **[Discord](https://discord.gg/cWdMAqcAn5)** - talk to the people building and using it
- **[GitHub Issues](https://github.com/neoswarm/neosh/issues)** - report bugs and request features
- **[Pull requests](https://github.com/neoswarm/neosh/pulls)** - for everything else

<p>
  <a href="https://discord.gg/cWdMAqcAn5"><img src="https://img.shields.io/badge/Join%20the%20Discord-5865F2?logo=discord&logoColor=white&style=flat-square" alt="Join the Discord" /></a>
</p>

## Star the repository ⭐

A star helps more people find neosh, and it is the one metric a non profit project has.

<img width="1316" height="720" alt="star" src="https://github.com/user-attachments/assets/e26610c6-ff8a-4995-900c-509682b9a86e" />

## Contributing

Pull requests are welcome. Keep each one to a single logical change, and open an issue first for
anything large. `./scripts/check.sh` runs everything CI runs, and for anything visual, attach a
screenshot or a short recording: it is a terminal app, so what the screen looks like is the point.
The full guide is in [CONTRIBUTING.md](CONTRIBUTING.md), and the design rules live in
[AGENTS.md](AGENTS.md).

## Security

Found a vulnerability? Report it privately through
[GitHub security advisories](https://github.com/neoswarm/neosh/security/advisories/new) instead of
opening a public issue.

## License

neosh is free, and it stays free. Everything in this repository is
[MIT licensed](LICENSE): use it, change it, ship what you build on it. There is no paid tier and
no open core, because there is no company to need one.

---
_Source: https://npm.io/package/@neosh/titles · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
