karst-code 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +208 -2
  2. package/cli.js +18514 -0
  3. package/package.json +35 -4
package/README.md CHANGED
@@ -1,3 +1,209 @@
1
- # Temporary Holding Version
1
+ # Karst
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A coding agent for the terminal. Karst reads and edits your code, runs commands and works through tasks with you, and asks before doing anything you have not allowed. It works with Anthropic, OpenAI, Ollama, or any server that speaks the Chat Completions API.
4
+
5
+ ```sh
6
+ npm install -g karst-code
7
+ export ANTHROPIC_API_KEY=...
8
+ karst
9
+ ```
10
+
11
+ ## Features
12
+
13
+ - **Your choice of model:** Anthropic (the default), OpenAI, Ollama, and Chat Completions servers such as DeepSeek, Groq, OpenRouter, Mistral, LM Studio or vLLM. `/provider` and `/model` switch in the middle of a session.
14
+ - **Tools:** reading, writing and editing files, search, shell commands that can run in the background, web fetch and search, notebooks, images and PDFs, a task checklist, plan mode, git worktrees, scheduled prompts, and subagents that work in the background.
15
+ - **You stay in control:** permission rules and modes, approval prompts answered with the arrow keys (with an optional note for the model), an operating-system sandbox for shell commands, and a trust step before a repository's own settings take effect.
16
+ - **Extensible:** MCP servers, skills, custom commands and agents, hooks and plugins. Skills and plugins written for Claude Code work too.
17
+ - **Sessions:** saved transcripts to resume, fork and rename, `/rewind` to undo file changes, automatic compaction of long conversations, and memory across sessions.
18
+ - **Scripting:** `-p` prints one answer and exits, with text, JSON or stream-JSON output and answers that follow a JSON Schema.
19
+ - **Try it without a key:** a mock provider answers from a script, so you can try the whole interface first.
20
+
21
+ ## Install
22
+
23
+ Requires [Node.js](https://nodejs.org) 22 or later.
24
+
25
+ ```sh
26
+ npm install -g karst-code # installs the `karst` command
27
+ npx karst-code # or try it without installing
28
+ ```
29
+
30
+ **In a repository you do not trust, run the installed `karst`, not `npx karst-code`.** npx prefers a copy of the package from the project's own `node_modules`, so the repository could supply its own.
31
+
32
+ ## Moving from Cairn
33
+
34
+ Karst was called Cairn, published as `cairn-code`, until 0.2.0. It was renamed because Cairn Code (github.com/cairn/cairn), a different terminal coding agent, uses the same `cairn` command, `~/.cairn` folder and `CAIRN.md` file.
35
+
36
+ ```sh
37
+ npm uninstall -g cairn-code
38
+ npm install -g karst-code
39
+ karst migrate --dry-run # lists what would move from ~/.cairn to ~/.karst
40
+ karst migrate
41
+ ```
42
+
43
+ `karst migrate` moves settings, saved keys, trust, sessions, memory, plans, skills, agents, plugins and MCP sign-ins, and `~/.cairn/CAIRN.md` becomes `~/.karst/KARST.md`. It replaces nothing already in `~/.karst`, and leaves in `~/.cairn` anything Cairn did not write. Karst reads nothing from Cairn's places, so in your projects rename `CAIRN.md` to `KARST.md`, `CAIRN.local.md` to `KARST.local.md`, `.cairn/` to `.karst/` and a plugin's `.cairn-plugin/` to `.karst-plugin/`, and in hooks and settings use `KARST_PROJECT_DIR`, `KARST_PLUGIN_ROOT` and the other `KARST_*` variables. `karst doctor` points out what it finds.
44
+
45
+ ## Quick start
46
+
47
+ ```sh
48
+ cd your-project
49
+ karst # interactive session
50
+ karst -p "explain this repo" # answer once and exit
51
+ cat log.txt | karst -p "find bugs" # also reads standard input
52
+ karst -c # continue the latest session in this directory
53
+ karst -r <id or name> # resume an earlier session
54
+ karst usage # tokens and estimated cost per day; also: projects, sessions
55
+ karst doctor # check the installation
56
+ karst update # install the latest version
57
+ karst migrate # move what Cairn, the earlier name, saved in ~/.cairn
58
+ ```
59
+
60
+ Each session checks npm for a newer version as it starts and says when there is one. `"updateCheck": false` in `~/.karst/settings.json` turns that off, and `"autoUpdates": true` installs it in the background instead.
61
+
62
+ Karst uses an Anthropic API key from the [Console](https://platform.claude.com), or `ANTHROPIC_AUTH_TOKEN`. Instead of exporting it each time, you can save it once with `karst provider key anthropic`. Karst does not use a Claude Code login or subscription.
63
+
64
+ ## Choosing a provider and model
65
+
66
+ | Provider | Needs | Default model |
67
+ | --- | --- | --- |
68
+ | `anthropic` | `ANTHROPIC_API_KEY`, or a saved key | `claude-opus-5-5` |
69
+ | `openai` | `OPENAI_API_KEY`, or a saved key | `gpt-6-astra` |
70
+ | `ollama` | Ollama on this machine, or `OLLAMA_HOST` | `qwen3-coder:30b` |
71
+ | one you add | `karst provider add` | the one you choose |
72
+
73
+ ```sh
74
+ karst --provider openai --model gpt-6.1-sol
75
+ karst provider add deepseek --type openai-chat --base-url https://api.deepseek.com/v1 --model deepseek-chat
76
+ karst provider list # every provider, its model, and where its key comes from
77
+ karst provider use deepseek # the default for new sessions
78
+ karst provider remove deepseek
79
+ ```
80
+
81
+ `karst provider add` asks for the key without showing it. Without `--type`, it also asks for the type, the base URL and the model. The types are `anthropic`, `openai`, `openai-chat` (Chat Completions) and `ollama`.
82
+
83
+ In a session, `/provider` opens a list of providers: type to narrow it, use `↑` `↓` and `Enter` to choose, or pick "Add a provider…". `/model` lists the current provider's models; for Ollama and Chat Completions servers, the list comes from the server. The conversation carries on with the new provider, and new sessions start with your last choice.
84
+
85
+ **Keys** are saved in `~/.karst/credentials.json`, which only you can read, and never in a settings file. A key in an environment variable takes precedence over a saved one. Each saved key is only sent to the address it was saved for: if a provider's address changes, for example through a repository's settings, Karst warns and sends no key until you save one for the new address.
86
+
87
+ ## Working in a session
88
+
89
+ - **Keep typing while the agent works.** The line you type and a status line stay at the bottom, and output appears above them.
90
+ - **A message waits 3 seconds before it is sent.** Anything you send in that time joins it. `Enter` on an empty line sends at once, and `Esc` brings the message back to edit.
91
+ - **Sending a message while the agent works** stops that work and continues from your new message. **`/queue <message>`** waits its turn instead.
92
+ - **The status line** shows what is running and for how long, background agents and shell commands, queued messages, and the tokens used, such as `⠹ Working 12s · Esc to stop · 2 agents · 1 shell · 3 queued · 45k tokens`.
93
+ - **After each turn,** a line shows its cost, tokens and time next to the session's, such as `▸ Cost: turn $0.42 • session $3.17 | Tokens: turn 48k • session 1.2M | Time: 1m 20s`. Once the context passes 75% of the auto-compact point, a note after each turn suggests `/compact` before you continue.
94
+ - **The input sits between two rules,** and the right end of the status line shows the model and effort level. The terminal window is titled `Karst · <project folder>`.
95
+ - **A panel opens each session** with the model, directory and git branch, the session id, the permission mode, and the instruction files, MCP servers, skills and plugins loaded. `/clear` wipes the screen and shows it again for the new session.
96
+ - **Typing `/`** opens a menu of commands that narrows as you type. `↑` `↓` choose, `Enter` runs, `Tab` completes.
97
+ - **Permission prompts** list Yes, Yes and don't ask again, and No. `↑` `↓` and `Enter` choose, `y` `a` `n` answer at once, and `Tab` adds a note for the model to the highlighted answer. An approved prompt is taken off the screen; a refused one stays.
98
+ - **Thinking** shows in a few dimmed lines above the input while it streams, then folds to one line such as `✻ Thought for 12s`.
99
+ - **Long pastes** (more than 3 lines or 800 characters) show as `[Pasted text #1 +42 lines]` and go in full with the message.
100
+ - **Images:** `Cmd+V` on macOS, or `Ctrl+V` on Windows and Linux, pastes the image on the clipboard as `[Image #1]`, and image files dropped on the terminal are attached the same way. Delete the placeholder to leave the image out. In a terminal whose `Cmd+V` pastes only text, such as iTerm2 before 3.7, use `Ctrl+V`. On Linux this needs `wl-clipboard` (Wayland) or `xclip` (X11).
101
+ - **Keys:** `Esc` or `Ctrl+C` stops the running work. `Shift+Tab` changes the permission mode. `Alt+Enter`, or a line ending in `\`, starts a new line. Pasted text keeps its line breaks. `Ctrl+D` on an empty line quits.
102
+
103
+ | Command | What it does |
104
+ | --- | --- |
105
+ | `/help` | List the commands and keys |
106
+ | `/provider`, `/model`, `/effort` | Switch provider, model or reasoning effort |
107
+ | `/mode` | Show or change the permission mode |
108
+ | `/queue` | Run a message after the current work; `/queue` alone lists them, `/queue clear` empties it |
109
+ | `/plan` | Plan mode: the agent only reads, then asks you to approve a plan |
110
+ | `/rewind` | Undo file changes from the last turn, or the last N turns |
111
+ | `/compact` | Summarize the conversation to free up context |
112
+ | `/clear`, `/resume`, `/rename` | Start a new conversation on a clear screen, go back to an earlier one, or name this one. `/clear` and `/resume` stop the background work the old conversation left running |
113
+ | `/btw <question>` | Ask a side question without adding it to the conversation |
114
+ | `/loop [interval] [prompt]` | Run a prompt again and again: `/loop 5m check the deploy` on a schedule, `/loop check the deploy` at a pace the model picks, `/loop` alone for a default prompt that tends unfinished work and the branch's pull request. `Esc` stops a self-paced loop while it waits, and `/loop stop` stops them all |
115
+ | `/cost`, `/context`, `/status` | Tokens and estimated cost, how full the context is, session details |
116
+ | `/usage` | Tokens and estimated cost on a screen of their own, in tabs: this session, then per day, project and session, like `karst usage`. `←` `→` switch tabs and `Esc` goes back. `/usage daily`, `/usage projects` or `/usage sessions` opens on that tab |
117
+ | `/tasks`, `/todos` | Background commands, agents and scheduled jobs, any of which `/tasks stop <id>` stops; and the agent's checklist |
118
+ | `/mcp`, `/skills`, `/agents` | MCP servers, skills and agents in use |
119
+ | `/init` | Write a `KARST.md` with notes about this project |
120
+ | `/exit` | Quit |
121
+
122
+ ## Permissions and safety
123
+
124
+ | Mode | Behavior |
125
+ | --- | --- |
126
+ | `default` | Asks before changing files or running commands that are not read-only |
127
+ | `acceptEdits` | Approves file changes, and `mkdir`, `touch`, `mv`, `cp`, inside the working directories |
128
+ | `plan` | Read-only, until you approve a plan |
129
+ | `dontAsk` | Refuses everything that would have asked |
130
+ | `bypassPermissions` | Never asks, except for ask rules and commands that delete important paths. Use it only in an isolated environment |
131
+
132
+ Choose one with `--permission-mode`, `Shift+Tab` or `/mode`. Rules go in settings:
133
+
134
+ ```json
135
+ {
136
+ "permissions": {
137
+ "allow": ["Bash(npm test *)", "Edit(/src/**)"],
138
+ "ask": ["Bash(git push *)"],
139
+ "deny": ["Read(.env)", "Bash(curl *)"]
140
+ }
141
+ }
142
+ ```
143
+
144
+ - **Rules for shell commands are guardrails, not a security boundary.** For a boundary, turn on the sandbox with `"sandbox": { "enabled": true }` in settings, or `/sandbox on` from the next start. Commands the model runs then work under Seatbelt on macOS or bubblewrap on Linux: they can write only to the working directories and temporary directories, and have no network unless you list domains in `sandbox.network.allowedDomains`. Reads are still allowed almost everywhere, including `~/.ssh`, unless you add paths to `sandbox.filesystem.denyRead`.
145
+ - **A repository's own settings wait for trust.** Its hooks, allow rules, provider settings, MCP servers, skills, commands and agents take effect only after you trust the directory, at the prompt on startup, with `/trust`, or with `--trust` for one run.
146
+ - **Commands the model runs never see your API keys.** Every provider's key variable is removed from their environment, and saved keys are never put in an environment at all.
147
+
148
+ ## Configuration
149
+
150
+ Settings are read from `~/.karst/settings.json`, then the project's workspace folder, then `.karst/settings.json` in the project, then `.karst/settings.local.json`, then `--settings`. Each overrides the one before.
151
+
152
+ What Karst saves for a project (approvals saved with "don't ask again", `-s local` providers and MCP servers, memory) goes in its workspace folder, `~/.karst/workspaces/<hash>/`, outside the repository; `karst doctor` shows which one. Karst does not create `.karst/` in a repository for settings: that folder is yours, and its files override the workspace folder.
153
+
154
+ ```json
155
+ {
156
+ "provider": "anthropic",
157
+ "model": "claude-opus-5-5",
158
+ "effort": "medium",
159
+ "permissions": { "allow": ["Bash(npm test *)"], "defaultMode": "default" },
160
+ "hooks": {
161
+ "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": ".karst/hooks/check.sh" }] }]
162
+ },
163
+ "env": { "NODE_ENV": "development" }
164
+ }
165
+ ```
166
+
167
+ - **Project instructions:** `KARST.md` files, from `~/.karst/` and from the filesystem root down to the working directory. A directory without one uses `AGENTS.md` or `CLAUDE.md`. More instructions go in `.karst/rules/*.md`, optionally only for files matching some paths.
168
+ - **MCP servers:** `karst mcp add <name> <url>` for HTTP, or `karst mcp add <name> <command> -- <args>` for stdio, such as `karst mcp add github -e GITHUB_TOKEN=... npx -- -y some-mcp-server`. Then `karst mcp list`, and `karst mcp login <name>` for servers that use OAuth.
169
+ - **Skills:** Markdown instructions in `.karst/skills/<name>/SKILL.md` or `~/.karst/skills/<name>/SKILL.md`, run as `/<name>` or by the model when relevant. `.karst/commands/<name>.md` makes a simple command.
170
+ - **Agents:** subagents defined in `.karst/agents/<name>.md`, with their own prompt, tools and model.
171
+ - **Plugins:** bundles of skills, commands, agents, hooks and MCP servers. `karst plugin install ./toolkit`, or `--plugin-dir ./toolkit` for one run.
172
+ - **Hooks** run your commands at points such as `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart` and `Stop`, and can block or adjust what happens.
173
+
174
+ ## Scripting
175
+
176
+ ```sh
177
+ karst -p "summarize the changes" --output-format json
178
+ karst -p "fix the failing test" --allowedTools "Edit,Bash(npm test *)" --max-turns 20
179
+ karst -p "list the TODOs" --json-schema schema.json
180
+ git diff | karst -p "review this" --output-format stream-json
181
+ ```
182
+
183
+ With `-p`, nobody is there to answer a permission prompt, so anything that would ask is refused; pre-approve it with `--allowedTools` or a rule. `--max-budget-usd` stops when the estimated spend reaches a limit. `karst --help` lists every option.
184
+
185
+ ## Try it without an API key
186
+
187
+ ```sh
188
+ mkdir -p /tmp/play && cd /tmp/play
189
+ karst --provider scripted
190
+ ```
191
+
192
+ Replies come from a built-in script instead of a model. Type `help` to see what it does, such as `run <command>`, `demo edit`, `demo ask` or `demo agent`. The tool calls are real, which is why this runs in a scratch directory. To write your own replies, set `KARST_SCRIPT` to a JSON file of rules that match what you type.
193
+
194
+ ## Your data
195
+
196
+ Karst keeps its files in `~/.karst` (or `KARST_HOME`): settings, saved keys, session transcripts, file checkpoints and memory. Each transcript also records the tokens and estimated cost of every response, which `karst usage` totals per day, `karst usage projects` per project and `karst usage sessions` per session; add `--since`, `--until`, `--project <path>` or `--json`. Scheduled prompts are saved in the workspace folder too: a session's come back when you resume it, and those the model makes durable run in every later session of the project. `karst purge --dry-run` lists the workspace folder (settings, saved approvals, MCP servers, memory and scheduled jobs), transcripts, file history and logs stored for the current project, and `karst purge --yes` deletes them. The project's own files, `.karst/` included, are not touched.
197
+
198
+ ## Versions
199
+
200
+ - **0.2.0:** Cairn is now **Karst**, because Cairn Code (github.com/cairn/cairn) is another terminal coding agent with the same `cairn` command, `~/.cairn` folder and `CAIRN.md` file. The package is `karst-code` and the command is `karst`: run `npm uninstall -g cairn-code && npm install -g karst-code`, then `karst migrate` to move your settings, saved keys, sessions and memory from `~/.cairn` to `~/.karst`. Karst does not read `~/.cairn`, `CAIRN_HOME`, `CAIRN.md`, `.cairn/` or `.cairn-plugin/`, and hooks get `KARST_*` variables instead of `CAIRN_*`, so rename these in your projects to `KARST.md`, `.karst/` and `.karst-plugin/`; `karst doctor` points out the ones it finds. Also new: `karst update` installs the latest version, and each session says when a newer one is on npm (`updateCheck` and `autoUpdates` in settings). `/loop` runs a prompt again and again, on a schedule or at a pace the model picks, and `/tasks` lists background agents and scheduled jobs too, any of which `/tasks stop <id>` stops. What Karst saves for a project (approvals, `-s local` providers and MCP servers, memory) goes in `~/.karst/workspaces/<hash>/`. Each session opens with a panel showing the model, directory, branch and what was loaded. Thinking streams in dimmed lines and then folds to one, long pastes show as `[Pasted text #1 +42 lines]`, an approved permission prompt is taken off the screen, and `Cmd+V` pastes images on macOS.
201
+ - **0.1.4:** `Ctrl+V` pastes an image from the clipboard on macOS and Linux, and image files dropped on the terminal are attached too, as `[Image #1]` placeholders. `/usage` opens a screen of its own with tabs for this session, days, projects and sessions, switched with `←` `→` and closed with `Esc`. Each turn ends with a line showing its cost, tokens and time next to the session's, and with a note to `/compact` once the context is nearly full. The input sits between two rules, the status line shows the model and effort level on the right, and the terminal window is titled after the project.
202
+ - **0.1.3:** each session now saves its tokens and estimated cost. `cairn usage` reports them per day, `cairn usage projects` per project and `cairn usage sessions` per session, also as `/usage` in a session, and after a resume `/cost` shows what the session spent over every run. This is also the first version on npm with the retries from 0.1.2.
203
+ - **0.1.2:** a failed model request is retried up to 10 times, waiting longer each time (from half a second up to 5 minutes), and a reply that breaks off partway is started over. Each retry is shown as it happens. Releases are now published from GitHub Actions, with npm provenance.
204
+ - **0.1.1:** this README, written for people installing Cairn. The program is the same as in 0.1.0.
205
+ - **0.1.0:** the first release.
206
+
207
+ Development and testing happen on macOS. On Linux the sandbox has not been tried yet, and it has no network proxy, so `allowedDomains` does not work there.
208
+
209
+ Karst's behavior follows Claude Code's public documentation, and its system prompt and tool descriptions are adapted from Claude Code's published system prompts.