heartcode 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fayaz Bin Salam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# HeartCode
 
-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.
+A coding agent for your terminal that works with any OpenAI-compatible model.
+
+**Zero dependencies.** Nothing in `node_modules`, no install scripts, no packages pulled in
+behind your back: only Node.js (20 or newer) and HeartCode's own code. What you install is
+what you can read.
+
+<!-- image: HeartCode in the terminal, answering a message -->
+![HeartCode in the terminal](docs/images/heartcode.png)
+
+## Why I made it
+
+Not to compete with other coding CLIs. I made it for my own use, because none of the ones I
+tried did what I needed. In short, HeartCode:
+
+- **Works with any OpenAI-compatible provider**, several at once: OpenRouter, Groq, NVIDIA,
+  Gemini, Ollama, LM Studio, your own proxy…
+- **Keeps a list of models and falls back on its own.** When one hits a rate limit or goes down,
+  the next one in your list answers. Free models run out often; this way the work goes on.
+- **Works with models that can't call tools.** It guides them step by step instead.
+- **Knows each model from [models.dev](https://models.dev)**: its context window, whether it calls
+  tools, thinks or reads images. Nothing is sent to the model to find out.
+- **Is set up in a web page** on your own machine (`/settings`), not by editing config files.
+- **Never sends `max_tokens`**, so no provider cuts the reply short by a limit you didn't choose.
+- **Can be used by other tools and AI agents**: `heart -p` runs one task headless, like
+  `claude -p` (see [SKILL.md](SKILL.md)).
+- **Logs each request and its reply** in a file of its own, when you switch logging on, so you
+  can see what went wrong.
+- **Takes skills, MCP servers and hooks** in Claude Code's formats; `/import` brings yours over.
+- **Has tabs** (`Ctrl+T`), each with its own conversation, and git worktrees for work kept apart.
+
+## How I set it up and use it
+
+### 1. Install
+
+From npm:
+
+```sh
+npm install -g heartcode
+```
+
+Or from source:
+
+```sh
+git clone https://github.com/p32929/HeartCode.git
+cd HeartCode
+npm start
+```
+
+`npm start` links the `heart` command to that folder, so a `git pull` updates it.
+
+### 2. Run `heart`
+
+In the project you want to work on:
+
+```sh
+cd ~/code/my-app
+heart
+```
+
+<!-- image: HeartCode's first screen -->
+![HeartCode's first screen](docs/images/start.png)
+
+### 3. Open the settings page
+
+Type `/settings`. The settings page opens in your browser. It runs on your machine only
+(127.0.0.1, with a secret key in its link).
+
+<!-- image: the settings page -->
+![The settings page](docs/images/settings.png)
+
+### 4. Providers & models
+
+1. **Add a provider**: its name, base URL and API key. Pick one of the presets to fill in the URL.
+2. **Choose the models to use**: click a model to add it to your list. I use the free models.
+
+<!-- image: Providers & models, with a provider added and models chosen -->
+![Providers and models](docs/images/providers.png)
+
+### 5. Your models
+
+1. **Sort them by context and abilities.** Click the *Abilities* column, then *Context*: the
+   models that can do the most, with the biggest context window, come first. Click
+   **Use this order** to save it.
+2. **Rearrange a bit more.** Drag a row to move it. #1 is the one HeartCode uses; the others are
+   its fallbacks, tried in order.
+
+If a model says *not found* in models.dev, **Retry** looks it up again, or **Set up** tells
+HeartCode what it can do.
+
+<!-- image: Your models, sorted -->
+![Your models](docs/images/your-models.png)
+
+### 6. Turn on logging (optional)
+
+On the **Logging** page: a log of each run, and each request with its reply, in files of their
+own. Logs older than 30 days are deleted (you can change that).
+
+<!-- image: the Logging page -->
+![Logging](docs/images/logging.png)
+
+### 7. Back to HeartCode
+
+Go back to the terminal. While the settings page is on, HeartCode shows a dialog and waits.
+Your changes are already in.
+
+### 8. Press Enter to stop the settings page
+
+**Turn off** is selected: press Enter. The page stops and HeartCode is yours again.
+
+<!-- image: the "settings page is on" dialog -->
+![The settings dialog](docs/images/settings-dialog.png)
+
+### 9. Send "Hi" as a test
+
+Type `Hi` and press Enter. Wait for the reply: your model works.
+
+<!-- image: the first reply -->
+![The first reply](docs/images/hi.png)
+
+### 10. Start using it
+
+Use HeartCode like any other coding agent: ask it to read, change, run and fix things in your
+project. `/` shows every command, `Shift+Tab` changes what it may do without asking, `Esc` stops
+it, and `heart --help` lists everything else.
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: heartcode
+description: Run a coding task with HeartCode, a coding agent for any OpenAI-compatible model (OpenRouter, Groq, Ollama, LM Studio, your own server…), from a script or another AI agent. Use it to hand a task to a different or cheaper model, get a second opinion on code, or run work in an isolated git worktree. Headless: `heart -p`, JSON out, exit code 0 or 1.
+---
+
+# HeartCode, for AI agents
+
+HeartCode is a coding agent in the terminal. Interactively it takes the whole screen, which an
+agent can't drive. Use it **headless**: `heart -p` runs one task without the screen, prints the
+answer (or JSON) and exits. Its flags and output match Claude Code's `claude -p`.
+
+## Check it's there
+
+```sh
+heart --version          # installed? (else: node /path/to/heart_cli/bin/heart.js --version)
+heart providers          # the providers set up, and their URLs (keys are masked)
+heart models --json      # the models to pass to -m: "default" first (the user's list, with fallbacks), then each model
+heart models --all --json   # every provider's models too (slower: asks each provider)
+```
+
+Read `--json`, not the text: the text layout is for people and may change.
+
+```json
+{ "models": [
+    { "place": null, "provider": null, "model": "default", "role": "default", "rotates": true, "about": "your models in order: #1, then the next when one fails (-m default, or no -m)" },
+    { "place": 1, "provider": "groq", "model": "openai/gpt-oss-120b", "role": "in use", "rotates": false },
+    { "place": 2, "provider": "openrouter", "model": "qwen/qwen3-coder", "role": "fallback", "rotates": false } ],
+  "providers": [
+    { "name": "groq", "baseUrl": "https://api.groq.com/openai/v1", "list": true, "models": ["…"] },
+    { "name": "local", "baseUrl": "http://127.0.0.1:9/v1", "list": true, "models": [], "error": "cannot reach …" } ] }
+```
+
+Each entry in `models` is something to pass to `-m`, in order:
+
+- **`default`** (always first; `place` and `provider` are `null`): the user's list. `rotates: true`
+  when they have more than one model: #1 is used, and the next one in order when it fails.
+- **the user's models** (`place` 1, 2, …): `role` is `in use` for #1 and `fallback` for the rest;
+  `rotates: false`, since a model named on its own is used alone.
+
+No model set up yet: `models` is empty (and `heart -p` fails with "no model set up").
+`heart models [--all] <filter>` keeps only the entries whose `model` contains `<filter>`.
+
+`providers` (only with `--all`): every provider's models. `list: false`: the user switched that
+provider's list off, and `models` are the ones they added by name. A provider that can't be
+reached has an `error` and is skipped; the command still exits `0`.
+
+**Which model to pass:**
+
+| `-m` | What runs |
+|---|---|
+| `default`, or no `-m` | the user's list: #1, and the next one in order when it fails (rate limits, outages…). Use this unless you need one particular model. |
+| a model from the list: `-m "<provider> <model>"` (`-m "groq openai/gpt-oss-120b"`), or `-m <model>` alone | that model alone: never another one, also when it fails (a rate limit or an outage is tried again, up to `--max-retries`) |
+
+**Failures:** a rate limit, a server error, a timeout or a lost connection is waited out and tried
+again (or handed to the next model in the list), up to `--max-retries` (10). An error waiting can't
+fix (a model name the server doesn't know, a wrong key, a request it refuses) is never sent again:
+the run stops with that error and exit code `1`. With the default list it moves on to the next
+model only if the user set its fallback rule to "at any error".
+
+`--provider <name>` and `-u <url>` (a server for this run) also mean one model, alone.
+
+`heart` is installed by `npm start` in the HeartCode folder. `heartcode` is the same command.
+Needs Node.js 20 or newer. No providers? See "Setting up a model" below.
+
+## Run a task
+
+```sh
+heart -p --output-format json -C /path/to/project "fix the failing test in math.test.js"
+```
+
+- `-C <folder>`: the project to work in (default: the current folder). A folder, not a file.
+- The prompt is the last argument, or stdin: `echo "explain src/agent.js" | heart -p`.
+- Exit code: `0` it finished, `1` it failed (no model, the model kept failing, the server refused
+  the request (wrong model name, bad key), `--max-turns` hit). The error is in `result` (JSON) or on stderr.
+
+`--output-format json` prints one object on stdout:
+
+```json
+{ "type": "result", "subtype": "success", "is_error": false, "result": "Fixed it: …",
+  "num_turns": 6, "duration_ms": 41200, "total_cost_usd": 0.0031,
+  "usage": { "input_tokens": 18000, "output_tokens": 900 }, "session_id": "20261027-…" }
+```
+
+Read `is_error` and `result`. `subtype` is `success`, `error_during_execution` or
+`error_max_turns`. Without `--output-format`, stdout is just the answer text, and an error
+goes to stderr. Logs never go to stdout.
+
+## Continue the same conversation
+
+Pass the `session_id` from the last result:
+
+```sh
+heart -p --output-format json --resume 20261027-… "now add a test for the empty case"
+heart -p --continue "…"          # or: the last session in this folder
+```
+
+## Keep it safe
+
+Headless never asks anyone. What the permission mode would ask about is declined, and the
+model is told why.
+
+| You want | Flags |
+|---|---|
+| Answers only, no changes (review, explain, find) | `--allowedTools Read,Grep,Glob` |
+| Edits, but no shell commands | `--permission-mode commands` |
+| Everything (edits and commands) | `--permission-mode all` (the default unless the user set another) |
+| Changes kept apart from the user's files | `--worktree=<name>` (in a git repo): it works in `.heartcode/worktrees/<name>` on the branch `heartcode/<name>`; kept if anything changed (merge it from there), removed if nothing did |
+| A cap on how long it works | `--max-turns 30` (model steps), `--max-retries 3` (a failing provider) |
+| Nothing written to the user's `~/.heart` (sessions, logs, settings) | `--temp` |
+
+Tool names: HeartCode's own (`read_file`, `edit_file`, `write_file`, `run_command`, `search`,
+`list_files`, `web_fetch`, `web_search`…) or Claude Code's (`Read`, `Edit`, `Write`, `Bash`,
+`Grep`, `Glob`, `WebFetch`, `WebSearch`). `--disallowedTools Bash` takes one away.
+
+## Choose the model
+
+```sh
+heart -p -m default "…"                         # the user's list, with its fallbacks (the same as no -m)
+heart -p -m "groq openai/gpt-oss-120b" "…"     # that provider and model alone, for this run
+heart -p --provider ollama -m qwen3-coder "…"   # the same, written apart
+heart -p --effort high "…"                      # how hard a thinking model thinks
+```
+
+What a model can do (tool calls, context size, thinking, images) comes from models.dev, at once;
+nothing is sent to the model to find out. A model models.dev doesn't know works with plain
+assumptions, and the user can set it up on the settings page. Models that can't call tools still
+work, in a slower guided mode.
+
+## Setting up a model
+
+Ask the user which provider and model to use, and for the key. Never invent one. Then:
+
+```sh
+# for one run only (nothing saved); the key from the environment, not the command line
+HEART_BASE_URL=https://api.groq.com/openai/v1 HEART_API_KEY=… HEART_MODEL=openai/gpt-oss-120b heart -p "…"
+
+# saved for every run (writes ~/.heart/config.json)
+HEART_API_KEY=… heart -u https://api.groq.com/openai/v1 -m openai/gpt-oss-120b --save -p "hello"
+```
+
+A model server on this machine (Ollama on :11434, LM Studio on :1234, llama.cpp on :8080) is
+found on its own. The user can also set everything up in a browser: `heart settings`.
+
+## More context for the task
+
+| Flag | |
+|---|---|
+| `--append-system-prompt "<text>"` | added to HeartCode's system prompt for this run |
+| `--mcp-config <file or JSON>` | more MCP servers (repeatable); `--strict-mcp-config`: only those |
+| `--skills-dir <folder>` | more skills (repeatable) |
+| `--no-memory` | don't read or write HeartCode's memory notes |
+
+A project's own `HEARTCODE.md` (or `AGENTS.md`, `CLAUDE.md`) is read like instructions.
+
+## Long tasks: a stream of events
+
+```sh
+heart -p --input-format stream-json --output-format stream-json
+```
+
+Stdin: one message per line, `{"type":"user","message":{"role":"user","content":"…"}}`.
+Stop the running one with `{"type":"control_request","request_id":"1","request":{"subtype":"interrupt"}}`.
+Stdout: one JSON event per line, `system`/`init`, then `assistant` (text, thinking, `tool_use`),
+`user` (`tool_result`), and a `result` after each message. It runs until stdin closes.
+
+## Don't
+
+- Don't run `heart` without `-p` from an agent: it's a full-screen app and waits for a person.
+- Don't put API keys on the command line where other processes can see them; use `HEART_API_KEY`.
+- Don't run `heart settings` unless the user asked: it starts a web page and runs until stopped.

package/bin/heart.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// `heart` (and `heartcode`): what `npm start` installs. Then HeartCode itself (heartcode.js).
+//   heart                     this folder
+//   heart .                   this folder
+//   heart ~/code/my-app       that folder (a folder: a file is an error)
+//   heart ~/code/my-app "fix the failing test" -m …   then anything heartcode takes (heart --help)
+//   heart --temp …            a throwaway ~/.heart: only your config.json (providers, keys), the
+//                             models' test results and prices copied in; deleted when HeartCode
+//                             quits; your own is never written to
+// Logs, when they're switched on (the settings page: Logging): each run's log in
+// ~/.heart/logs/runs/<day-month-year-hour-min-sec>/, a file per tab ("log": true in config.json);
+// each request to a model in ~/.heart/logs/requests/<same>/, a file per request ("logRequests").
+// Kept for logDays days (30 unless changed). HEART_LOG=/path/file.log logs this run in that one file
+// anyway; HEART_LOG=off: no run log.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const fail = (msg) => {
+  console.error(msg)
+  process.exit(1)
+}
+if (Number(process.versions.node.split('.')[0]) < 20) fail(`HeartCode needs Node.js 20 or newer (you have ${process.version}): https://nodejs.org`)
+
+const args = process.argv.slice(2)
+const realHome = process.env.HEART_HOME || path.join(os.homedir(), '.heart')
+const stamp = (() => {
+  const d = new Date()
+  return `${d.getDate()}-${d.getMonth() + 1}-${d.getFullYear()}-${d.getHours()}-${d.getMinutes()}-${d.getSeconds()}`.replace(/\b(\d)\b/g, '0$1')
+})()
+
+// --temp: HeartCode's folder is a new one in the system's temp folder
+const temp = args.includes('--temp')
+if (temp) {
+  args.splice(args.indexOf('--temp'), 1)
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'heart-temp-'))
+  // your providers and keys; what HeartCode learned about each model and prices (or it tests them again)
+  for (const f of ['config.json', 'models', 'prices.json']) if (fs.existsSync(path.join(realHome, f))) fs.cpSync(path.join(realHome, f), path.join(dir, f), { recursive: true })
+  process.env.HEART_HOME = dir
+  process.on('exit', () => fs.rmSync(dir, { recursive: true, force: true }))
+}
+
+// a folder first: HeartCode opens it (subcommands and options go straight through)
+const SUBCOMMANDS = ['probe', 'models', 'providers', 'config', 'settings']
+const first = args[0]
+if (first && !first.startsWith('-') && !SUBCOMMANDS.includes(first)) {
+  const where = path.resolve(first.replace(/^~(?=\/|$)/, os.homedir()))
+  const stat = fs.statSync(where, { throwIfNoEntry: false })
+  if (stat?.isDirectory()) args.splice(0, 1, '-C', where)
+  else if (stat) fail(`${first} is a file: heart opens a folder (heart path/to/folder)`)
+  else if (/^(\.|~|\/)|[\\/]/.test(first)) fail(`no such folder: ${first}`)
+  // else: words, a task to run (heart "fix the failing test")
+}
+
+// the run's log, if switched on (not for -p/--print: its callers set HEART_LOG themselves if they
+// want one; nor for --help and --version); requests are logged by HeartCode itself (src/log.js)
+const logOn = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(process.env.HEART_HOME || realHome, 'config.json'), 'utf8')).log === true
+  } catch {
+    return false
+  }
+})()
+const logs = temp ? path.join(os.tmpdir(), 'heart-temp-logs') : path.join(realHome, 'logs')
+process.env.HEART_LOGS ??= logs
+let runStamp = stamp
+for (let n = 2; ['runs', 'requests'].some((d) => fs.existsSync(path.join(logs, d, runStamp))); n++) runStamp = `${stamp}-${n}` // two runs in the same second
+process.env.HEART_LOG_STAMP ??= runStamp
+// The run's folder is set aside either way (made with its first line): the Logging page's switch
+// turns the log on or off while HeartCode runs (src/log.js, HEART_LOG_RUN).
+if (!process.env.HEART_LOG && !process.env.HEART_LOG_DIR && !args.some((a) => ['-p', '--print', '-h', '--help', '-v', '--version'].includes(a))) {
+  process.env.HEART_LOG_DIR = path.join(logs, 'runs', runStamp) // old ones: deleted after logDays (src/log.js)
+  process.env.HEART_LOG_RUN = logOn ? 'on' : 'off' // how it starts
+}
+
+process.argv = [process.argv[0], new URL('./heartcode.js', import.meta.url).pathname, ...args]
+await import('./heartcode.js')