# warm

Warm is a hosted coding agent for your terminal. It can inspect a project,
edit files, run commands, search the web, use MCP servers, and verify its work.

## Install

The quickest way downloads the native binary directly — no package manager, no
Node, no Bun:

```bash
# macOS / Linux
curl -fsSL https://warm.run/install.sh | sh
```

```powershell
# Windows (PowerShell)
irm https://warm.run/install.ps1 | iex
```

The installer verifies the download's checksum, installs under `~/.warm`, and
adds Warm to your `PATH` (pass `--no-modify-path` on macOS/Linux or
`-NoModifyPath` in PowerShell to skip that and get instructions instead).

Upgrading from Keelcode? The first run moves `~/.keelcode` to `~/.warm` and
leaves `~/.keelcode` behind as a link, so existing PATH entries, sessions and
logins carry over. `KEELCODE_*` environment variables are still read for one
release; the documented names are now `WARM_*`.

Or install with any package manager below. The package-manager launcher requires
**Node 18+** on your `PATH`, including when you install with Bun. Bun does not
provide Node:

```bash
npm  install --global @warm-ai/warm
pnpm add     --global @warm-ai/warm
yarn global  add      @warm-ai/warm
bun  add     --global @warm-ai/warm
```

> On a machine that has Bun but no Node, use the `curl | sh` / `install.ps1`
> script above instead — it installs a self-contained binary that needs no
> runtime at all.

If a package-manager install reports `command not found`, that manager's global
bin directory isn't on your `PATH`. Print it with `npm bin -g` (or `bun pm bin -g`)
and add it to your shell profile — or just use the curl installer, which handles
`PATH` for you.

The package installs one command:

```text
warm
```

For package-manager installs, `warm alias add kc` creates an extra command name
beside the package manager's own shims. Alias management is an npm-package
launcher feature; the native curl/PowerShell executable does not provide it.

## Staying current

Warm keeps itself up to date. At most once every six hours it checks the
registry in the background; installs made with the curl/PowerShell script download the new
version silently and switch to it on the next launch, while package-manager
installs show a one-line notice on the startup screen instead — their
`node_modules` tree belongs to the package manager, so Warm never writes
into it behind the manager's back.

```bash
warm update           # update now, in the foreground
warm update --check   # just report whether a newer version exists
```

To opt out, set `"autoUpdate": false` in `~/.warm/settings.json`, or export
`WARM_AUTO_UPDATE=0`. CI environments are skipped automatically.

After a package-manager installation, run the guided setup or add one or more
aliases directly:

```bash
warm alias setup
warm alias add mycode kk
warm alias list
warm alias remove kk
```

Custom aliases are created beside the package-manager shims. Warm refuses
to overwrite an existing command and never edits shell startup files. Package
installation stays non-interactive so it remains reliable in terminals, CI,
containers, and package managers that disable lifecycle scripts.

Fonts are never downloaded and terminal settings are never edited during
installation or normal startup. Warm defaults to font-independent Unicode,
and falls back to ASCII for clearly limited terminals. Rich Nerd Font icons are
an optional upgrade through `warm setup`; a failed or skipped setup keeps
the safe icon set enabled.

The `@warm-ai/warm` npm package is a small launcher that installs the matching
platform-suffixed version of that same package name for the current operating
system, CPU, and Linux libc. Warm's
application JavaScript, TypeScript, source maps, tests, and build configuration
are not included in the public package.

## Sign in and start

```bash
warm login
warm
```

If the machine cannot open a browser:

```bash
warm login --no-browser
```

Warm will also start sign-in automatically when an interactive session has
no usable account. Authentication uses a short-lived device approval; provider
credentials are never stored in the CLI.

Useful account commands:

```bash
warm whoami
warm usage
warm logout
```

## Everyday use

Start in the current project:

```bash
warm
```

Or select another project explicitly (a positional path is not a directory
selector):

```bash
warm --cwd /path/to/project
```

Run one prompt without opening the TUI:

```bash
warm -p "find and fix the failing test"
```

To review piped input, send the instruction and diff through stdin together:

```bash
{
  printf '%s\n\n' 'Review this diff for bugs'
  git diff
} | warm -p
```

Stdin supplies the prompt only when argv and `--prompt-file` do not provide
one. A nonempty `-p "prompt"` does not append piped input.

Resume work:

```bash
warm -c
warm sessions
warm --resume 2
```

Choose a model at launch:

```bash
warm --model <model-alias>
```

Inside the TUI, use `/models` to open the current model picker and `/usage` to
see the remaining hosted allowance. Run `/help` for the complete command list.
The footer reports client-observed `ttft` and `tps` for the latest model turn.
TTFT includes network and gateway latency; TPS uses provider-reported output
tokens and excludes tool execution. A dash is shown when the stream does not
contain enough timing or usage information for an honest measurement.

Measure local launcher startup:

```bash
warm bench
warm bench --json
```

The benchmark runs the installed launcher repeatedly, reports median/p90/min/max
latency, and is useful for comparing terminals, package managers, and releases.

## Common options

```text
-m, --model <alias>        choose a Warm model
    --permission-mode <m>  default | plan | acceptEdits | bypassPermissions
    --yolo                 bypass permission prompts in trusted environments
    --cwd <dir>            set the working directory
    --icons <set>          unicode | nerd | ascii | auto
    --no-alt-screen        keep output in the main terminal buffer
-c, --continue             resume the newest session in this directory
    --resume [id]          resume by id/index; no argument lists sessions
-p, --print [prompt]       run one headless prompt
    --output-format <f>    text | json | jsonl
-h, --help                 show help
-v, --version              show the installed version
```

`bypassPermissions` and `--yolo` remove confirmation prompts for operations
inside the workspace. Crossing the workspace boundary still requires explicit
approval and fails closed in headless mode.

## Configuration

Settings merge in this order, with later files winning:

1. `~/.warm/settings.json`
2. `<project>/.warm/settings.json` and `settings.local.json` (sanitized,
   capability-reducing fields only)
3. trusted per-project overrides under `~/.warm/projects/<workspace-hash>/`
4. command-line flags

Example project configuration:

```json
{
  "model": "<model-alias>",
  "permissionMode": "default",
  "maxTurns": 100,
  "timeoutMs": 600000,
  "permissions": {
    "ask": ["Bash", "Write", "Edit"],
    "deny": ["Write(/etc/**)"]
  }
}
```

Committed or in-tree settings cannot enable MCP processes, inject environment
variables, add allow rules, select `acceptEdits`/`bypassPermissions`, or define
unknown future capabilities. Explicit per-project choices made through the CLI
are stored outside the repository. Warm does not support bring-your-own-provider keys.

## MCP and skills

Inspect extension health:

```bash
warm doctor
warm mcp list
warm skills list
warm import list
```

Use `warm mcp --help` and `warm skills --help` for management commands.
MCP tools pass through the same permission checks as built-in tools.

## Automation

For scripts and CI, prefer structured headless output:

```bash
warm -p "run the tests and summarize failures" --output-format json
warm -p "review this repository" --output-format jsonl
```

Human progress is written to stderr. Machine-readable results are written to
stdout, so redirecting stdout does not mix logs into the protocol.
Model performance is written to stderr in text mode and included as structured
`performance` data in JSON/JSONL output.

## Local data and privacy

Warm stores account sessions, settings, conversations, caches, and local
receipts under `~/.warm`. Sensitive state uses owner-only permissions on
supported POSIX systems.

Anonymous product analytics are opt-in and can be controlled at any time:

```bash
warm telemetry status
warm telemetry enable
warm telemetry disable
```

Do not paste production secrets into prompts or commit `.warm` personal
state to a repository.

## Security

Report suspected vulnerabilities privately to `security@keelcode.ai`. Do not
include real credentials or unrelated private data in a report.

## License

Warm is proprietary software. Installation and use are governed by the
license included with this package and the applicable Warm service terms.