harma-kit 0.1.0 → 0.2.1
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.
- package/CHANGELOG.md +38 -19
- package/README.md +51 -92
- package/data/catalog.json +479 -176
- package/docs/agents-and-sessions.md +55 -0
- package/docs/choosing-models.md +83 -0
- package/docs/commands.md +103 -0
- package/docs/development.md +42 -0
- package/docs/how-harma-decides.md +71 -0
- package/docs/troubleshooting.md +41 -0
- package/package.json +2 -1
- package/skill/SKILL.md +89 -98
- package/skill/references/commands.md +49 -0
- package/skill/references/troubleshooting.md +37 -0
- package/src/backends.mjs +11 -0
- package/src/cli.mjs +9 -3
- package/src/commands.mjs +160 -2
- package/src/harness.mjs +3 -2
- package/src/rank.mjs +34 -14
- package/src/roster.mjs +177 -0
- package/src/tui.mjs +345 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,21 +1,40 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
- `
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- `
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
3
|
+
All notable changes to harma, newest first. Versions follow [semantic versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## 0.2.1 (2026-11-18)
|
|
6
|
+
|
|
7
|
+
New models and a fix for score refresh:
|
|
8
|
+
|
|
9
|
+
- **New models**: GPT-6.2 Astra and GPT-6.2 Sol (Codex), Qwen4 Max (Qwen Code, and Claude Code on QwenCloud as `claude-qwencloud`), Claude Fable 5.2 and Gemini 4 Hydrogen, with prices from the official pages and Artificial Analysis Intelligence Index v5.0.1 per effort
|
|
10
|
+
- **Score refresh**: Artificial Analysis retired the endpoint `harma rank --refresh` used on 2026-11-04, so the command stopped working; it now reads the free `/api/v2/language/models/free` endpoint, follows every page and updates cost per task as well as the index
|
|
11
|
+
- **Catalog**: rebuilt from the controller-models registry on 2026-11-18
|
|
12
|
+
- **Examples**: the docs use `gpt-6.2-sol` in place of `gpt-6.1-sol`
|
|
13
|
+
|
|
14
|
+
## 0.2.0 (2026-11-09)
|
|
15
|
+
|
|
16
|
+
You can now choose the models for each job yourself, or accept the orchestrator's proposals:
|
|
17
|
+
|
|
18
|
+
- **Selection screen**: `harma select` opens a terminal screen with the orchestrator and each job, showing the proposal next to your choice; every model and effort level shows its AA index, cost per task and credit state
|
|
19
|
+
- **Several models per job**: add, remove and reorder up to five models per job, in order of preference; the proposal pairs the best candidate with a backup on another CLI
|
|
20
|
+
- **Choice by credits**: at dispatch, harma takes the first model on your list whose CLI is installed and whose credits aren't exhausted, prefers a later model over one whose credits are low, and records which models it skipped and why
|
|
21
|
+
- **For agents**: `select --open --wait` opens the screen in a focused herdr tab (or an `hc` terminal) and returns your choices when you save
|
|
22
|
+
- **Without the screen**: `select --set "job=harness:model@effort|…"`, `--accept` and `--show`
|
|
23
|
+
- **Routing**: `route` shows your list and which model on it `dispatch` would use now; `dispatch --task-type` uses your list before the routing proposal
|
|
24
|
+
- **Docs**: the README is now a short overview, with guides and reference pages in `docs/`
|
|
25
|
+
|
|
26
|
+
A saved choice isn't consent to start an agent: each dispatch still asks. Choices saved by earlier builds, with one model per job, still work.
|
|
27
|
+
|
|
28
|
+
## 0.1.0 (2026-11-08)
|
|
29
|
+
|
|
30
|
+
First release:
|
|
31
|
+
|
|
32
|
+
- **`init`**: records the orchestrator model and effort for a project
|
|
33
|
+
- **`models`**: lists agent CLIs, models and effort levels; Codex models come from `~/.codex/models_cache.json`, the others from the catalog
|
|
34
|
+
- **`credits`**: reads CodexBar, falling back to a declared budget against an estimate from local logs
|
|
35
|
+
- **`rank`**: Artificial Analysis Intelligence Index for each model and effort; `--refresh` updates it from the AA API with a key
|
|
36
|
+
- **`route`**: profiles for planning, development, review (another vendor), debugging, research and extraction (cheapest)
|
|
37
|
+
- **`dispatch`, `send`, `read`**: run agents through herdr or herdr-core, with the `confirm` policy as the default; `dispatch` exits with code 4 when the agent waits on a dialog and the task wasn't sent
|
|
38
|
+
- **`status`, `costs`**: live state, estimated cost per agent and delegation advice
|
|
39
|
+
- **`cleanup`, `resume`**: save session IDs, close finished agents and reopen them with their context; `cleanup --workspace` closes harma's herdr workspace once no agent is open
|
|
40
|
+
- **`install`, `uninstall`, `doctor`**: install the skill for Claude Code and Codex and check the setup
|
package/README.md
CHANGED
|
@@ -1,119 +1,78 @@
|
|
|
1
1
|
# harma
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
harma is a skill for
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
6. shows what each agent is doing
|
|
17
|
-
7.
|
|
18
|
-
8. closes
|
|
19
|
-
|
|
3
|
+
harma lets one model run a project while the other models on your machine do the work. You name the orchestrator (for example Opus 5.5 at high effort) and it uses harma to see which models you have, how much credit each provider has left and how capable each model is per effort level. It then proposes who takes planning, development, review, debugging, research or extraction, starts those agents in terminal tabs once you agree, and closes them when they finish without losing their sessions.
|
|
4
|
+
|
|
5
|
+
harma is a skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Codex](https://github.com/openai/codex), plus the `harma` command line tool the skill drives.
|
|
6
|
+
|
|
7
|
+
## What harma does
|
|
8
|
+
|
|
9
|
+
From one conversation with your orchestrator, harma covers eight steps:
|
|
10
|
+
|
|
11
|
+
1. **Orchestrator**: records which model and effort level runs the project
|
|
12
|
+
2. **Inventory**: lists the agent command line interfaces (CLIs) on your machine, their models and their effort levels
|
|
13
|
+
3. **Credits**: reads how much each provider has left from [CodexBar](https://github.com/steipete/CodexBar), or from a budget you declare
|
|
14
|
+
4. **Intelligence**: ranks every model and effort pair by the [Artificial Analysis](https://artificialanalysis.ai/models) (AA) Intelligence Index and cost per task
|
|
15
|
+
5. **Routing**: proposes models for each kind of job; you accept them or pick your own, with several models per job in order of preference
|
|
16
|
+
6. **Monitoring**: shows what each agent is doing
|
|
17
|
+
7. **Cost**: estimates cost per agent and says where to delegate more or less
|
|
18
|
+
8. **Cleanup**: saves each agent's session ID, closes its tab, and reopens the same session later with its full context
|
|
19
|
+
|
|
20
|
+
No agent starts without your yes: under the default policy, every start asks for confirmation.
|
|
21
|
+
|
|
22
|
+
## Requirements
|
|
23
|
+
|
|
24
|
+
You need:
|
|
25
|
+
|
|
26
|
+
- Node.js 20 or later
|
|
27
|
+
- At least one agent CLI: `claude`, `codex`, `agy`, `kimi`, `grok`, `muse`, `qwen` or another one in the catalog
|
|
28
|
+
- A terminal backend: [herdr](https://herdr.dev) or [herdr-core](https://github.com/herdrdev/herdr-core) (`hc`)
|
|
29
|
+
|
|
30
|
+
CodexBar and an Artificial Analysis API key are optional. Without them, harma uses a declared budget and the bundled scores.
|
|
20
31
|
|
|
21
32
|
## Install
|
|
22
33
|
|
|
34
|
+
Install the skill for Claude Code and Codex, then check the setup:
|
|
35
|
+
|
|
23
36
|
```sh
|
|
24
|
-
npx harma-kit install
|
|
25
|
-
npx harma-kit
|
|
26
|
-
npm i -g harma-kit # optional: the CLI without npx
|
|
27
|
-
npx harma-kit doctor # checks Node, backends, agent CLIs, CodexBar, AA key
|
|
37
|
+
npx harma-kit install
|
|
38
|
+
npx harma-kit doctor
|
|
28
39
|
```
|
|
29
40
|
|
|
30
|
-
|
|
31
|
-
`qwen`, …) and a terminal backend: **herdr** or **herdr-core (`hc`)**.
|
|
41
|
+
`install` copies the skill to `~/.claude/skills/harma` and `~/.codex/skills/harma`; add `--target claude` or `--target codex` for one of them. `doctor` checks Node.js, the backends, the agent CLIs, CodexBar, the AA key and the installed skill. For the `harma` command without `npx`, run `npm i -g harma-kit`.
|
|
32
42
|
|
|
33
|
-
##
|
|
43
|
+
## Get started
|
|
34
44
|
|
|
35
|
-
In a project,
|
|
45
|
+
In a project, ask Claude Code or Codex for what you want, in your own words:
|
|
36
46
|
|
|
37
|
-
> Use harma. You
|
|
38
|
-
> how much credit is left, then plan the auth refactor with the best planner and have the
|
|
39
|
-
> builder implement it. Ask me before starting each agent.
|
|
47
|
+
> Use harma. You're the orchestrator, Opus 5.5 at high effort. Check which models we have and how much credit is left, then plan the auth refactor with the best planner and have a builder implement it. Ask me before starting each agent.
|
|
40
48
|
|
|
41
|
-
The skill turns that into:
|
|
49
|
+
The skill turns that request into harma commands. These are the main ones:
|
|
42
50
|
|
|
43
51
|
```sh
|
|
44
52
|
harma init --orchestrator claude:claude-opus-5-5 --effort high
|
|
45
53
|
harma models && harma credits && harma rank --top 15
|
|
46
|
-
harma
|
|
47
|
-
harma dispatch --name planner --task-type pianificazione --prompt-file brief.md
|
|
48
|
-
harma dispatch --name planner --task-type pianificazione --prompt-file brief.md --yes
|
|
54
|
+
harma select --open --wait
|
|
55
|
+
harma dispatch --name planner --task-type pianificazione --prompt-file brief.md
|
|
49
56
|
harma status
|
|
50
|
-
harma costs
|
|
51
57
|
harma cleanup
|
|
52
|
-
harma resume planner --yes
|
|
53
58
|
```
|
|
54
59
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
| Command | What it does |
|
|
58
|
-
|---|---|
|
|
59
|
-
| `init --orchestrator h:m --effort e` | Sets the orchestrator; options `--backend auto\|herdr\|hc`, `--policy confirm\|auto-within-budget` |
|
|
60
|
-
| `models` | Agent CLIs on PATH, their models and efforts, with the source of each row |
|
|
61
|
-
| `credits` | Remaining share per provider: `ampio`, `ok`, `scarso`, `esaurito` or `sconosciuto` |
|
|
62
|
-
| `rank [--refresh]` | AA index and cost per task per model × effort; `--refresh` uses `AA_API_KEY` |
|
|
63
|
-
| `route <type> [--author h:m]` | Top candidates for `pianificazione`, `sviluppo`, `review`, `debugging`, `ricerca` or `estrazione` |
|
|
64
|
-
| `dispatch --name n (--model h:m \| --task-type t)` | Starts an agent; needs `--yes` under the `confirm` policy |
|
|
65
|
-
| `send n "text"` / `read n` | Gives an open agent more work / reads its screen |
|
|
66
|
-
| `status` | Every open agent: model, effort, live state, age, session id |
|
|
67
|
-
| `costs` | Estimated cost per agent, credits per provider, delegation advice |
|
|
68
|
-
| `cleanup [--dry-run] [--workspace]` | Saves session ids, then closes finished agents' tabs or terminals; `--workspace` also closes harma's herdr workspace when no agent is open |
|
|
69
|
-
| `resume n [--print-only]` | Reopens a saved session with its model and effort |
|
|
70
|
-
|
|
71
|
-
Every command takes `--json`. Exit code 3 means "needs the user's confirmation". Exit code 4
|
|
72
|
-
from `dispatch` means the agent started but is waiting on a dialog (for example "trust this
|
|
73
|
-
folder?"), so the task was not sent.
|
|
74
|
-
|
|
75
|
-
## How it decides
|
|
76
|
-
|
|
77
|
-
- **Intelligence.** The bundled catalog holds the Artificial Analysis Intelligence Index v5.0
|
|
78
|
-
per model × effort and cost per task (snapshot of 2026-10-28). `harma rank --refresh` updates
|
|
79
|
-
the index from the AA API into `~/.config/harma/catalog.json`. Missing scores stay unknown.
|
|
80
|
-
- **Routing.** `score = index − weight × cost per task ± credit adjustment`, above a minimum
|
|
81
|
-
index per task type. Review excludes the author's vendor. Extraction takes the cheapest model
|
|
82
|
-
above the floor. An unknown cost counts as the highest known one. Override the profiles in
|
|
83
|
-
`.harma/config.json` → `routing`.
|
|
84
|
-
- **Credits.** CodexBar first, with account identity removed. If CodexBar doesn't cover a
|
|
85
|
-
provider, harma uses a budget you declare (`budgets.<provider>`) against an estimate from local
|
|
86
|
-
logs. Otherwise the credit state is unknown. For a subscription, the "estimate" is tokens × API
|
|
87
|
-
list price, not what you pay.
|
|
88
|
-
- **Consent.** The default policy `confirm` refuses to start or instruct any agent without
|
|
89
|
-
`--yes`. Under `auto-within-budget`, which you must set yourself, harma dispatches without
|
|
90
|
-
asking only when the provider's credits are `ok` or `ampio`.
|
|
91
|
-
|
|
92
|
-
## Backends
|
|
93
|
-
|
|
94
|
-
- **herdr.** One workspace per project and one tab per agent, so closing an agent closes its
|
|
95
|
-
window. The session id comes from herdr's agent detection, or from `--session-id` for Claude.
|
|
96
|
-
- **herdr-core (`hc`).** Headless terminals labelled `harma.project` and `harma.agent`, started
|
|
97
|
-
with `--outlive-parent`. Codex session ids are read from `~/.codex/sessions`.
|
|
98
|
-
|
|
99
|
-
harma only closes what it started, as recorded in `.harma/agents.jsonl`.
|
|
100
|
-
|
|
101
|
-
## Project files
|
|
60
|
+
`select --open --wait` opens a screen in a herdr tab where you accept or change the models for each job. `dispatch` exits with code 3 and shows the plan until you agree; the orchestrator then runs it again with `--yes`.
|
|
102
61
|
|
|
103
|
-
|
|
104
|
-
.harma/config.json orchestrator, policy, budgets, thresholds, routing overrides
|
|
105
|
-
.harma/agents.jsonl append-only: started, session, prompted, closed, resumed
|
|
106
|
-
.harma/cache/ last inventory, credits, rank (cache/ is git-ignored)
|
|
107
|
-
```
|
|
62
|
+
## Documentation
|
|
108
63
|
|
|
109
|
-
|
|
64
|
+
- [Choose the models for each job](docs/choosing-models.md): the selection screen, several models per job, and doing it without a screen
|
|
65
|
+
- [Command reference](docs/commands.md): every command, option and exit code
|
|
66
|
+
- [How harma decides](docs/how-harma-decides.md): intelligence scores, routing, credits, cost estimates and consent
|
|
67
|
+
- [Agents, sessions and backends](docs/agents-and-sessions.md): herdr and herdr-core, session IDs, cleanup and resume, project files
|
|
68
|
+
- [Troubleshooting](docs/troubleshooting.md): exit codes, dialogs an agent waits on, missing credits or scores
|
|
69
|
+
- [Development](docs/development.md): tests, catalog updates and releases
|
|
70
|
+
- [Changelog](CHANGELOG.md)
|
|
110
71
|
|
|
111
|
-
|
|
112
|
-
runs the suite with fake `herdr`, `hc`, `codexbar` and agent CLIs.
|
|
72
|
+
## Credits
|
|
113
73
|
|
|
114
|
-
Intelligence Index and cost per task
|
|
115
|
-
herdr and herdr-core are projects of their authors; harma is not affiliated with them.
|
|
74
|
+
The Intelligence Index and cost per task come from [Artificial Analysis](https://artificialanalysis.ai/). herdr and herdr-core belong to their authors, and harma isn't affiliated with them.
|
|
116
75
|
|
|
117
76
|
## License
|
|
118
77
|
|
|
119
|
-
MIT
|
|
78
|
+
[MIT](LICENSE)
|