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 CHANGED
@@ -1,21 +1,40 @@
1
1
  # Changelog
2
2
 
3
- ## 0.1.0 — 2026-11-08
4
-
5
- First release.
6
-
7
- - `init`: names the orchestrator model and effort for a project.
8
- - `models`: lists agent CLIs, models and efforts. Codex comes from `~/.codex/models_cache.json`,
9
- the others from the catalog.
10
- - `credits`: reads CodexBar, with the declared budget and local-log estimate as fallbacks.
11
- - `rank`: Artificial Analysis Intelligence Index per model × effort; refreshes from the AA API
12
- with a key.
13
- - `route`: profiles for planning, development, review (another vendor), debugging, research and
14
- extraction (cheapest).
15
- - `dispatch` / `send` / `read`: work through herdr or herdr-core. The `confirm` policy is the
16
- default.
17
- - `status`, `costs`: live state, estimated cost per agent and delegation advice.
18
- - `cleanup`, `resume`: save session ids, close finished agents, reopen them with their context.
19
- `cleanup --workspace` closes harma's herdr workspace once no agent is open.
20
- - `dispatch` exits 4 when the agent starts but waits on a dialog; the task is not marked as sent.
21
- - `install` / `uninstall` / `doctor`: install the skill for Claude Code and Codex.
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
- One orchestrator model runs your project; the other models on your machine do the work.
4
-
5
- harma is a skill for **Claude Code** and **Codex** plus a small CLI. You name the model (and
6
- effort) responsible for a project. It then:
7
-
8
- 1. sees which agent CLIs, models and effort levels this machine has;
9
- 2. reads how much credit each provider has left (via [CodexBar](https://github.com/steipete/CodexBar),
10
- a declared budget, or local session logs);
11
- 3. ranks every model × effort by the [Artificial Analysis](https://artificialanalysis.ai/models)
12
- Intelligence Index and cost per task;
13
- 4. proposes which model takes planning, development, review, debugging, research or extraction;
14
- 5. starts agents in [herdr](https://herdr.dev) tabs or [herdr-core](https://github.com/herdrdev/herdr-core)
15
- terminals, **only after you say yes**;
16
- 6. shows what each agent is doing;
17
- 7. tracks cost per agent and tells you where to delegate more or less;
18
- 8. closes finished agents after saving their native session ids, so `harma resume <name>` brings
19
- one back with its full context.
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 # skill for Claude Code and Codex (~/.claude/skills, ~/.codex/skills)
25
- npx harma-kit install --target codex
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
- You need Node ≥ 20, at least one agent CLI (`claude`, `codex`, `agy`, `kimi`, `grok`, `muse`,
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
- ## Use it from your agent
43
+ ## Get started
34
44
 
35
- In a project, tell Claude or Codex something like:
45
+ In a project, ask Claude Code or Codex for what you want, in your own words:
36
46
 
37
- > Use harma. You are the orchestrator, Opus 5.5 at high effort. Check which models we have and
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 route pianificazione
47
- harma dispatch --name planner --task-type pianificazione --prompt-file brief.md # exit 3: asks you
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
- ## Commands
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
- ## Maintainers
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
- `node scripts/import-catalog.mjs <controller-models>` regenerates `data/catalog.json`. `npm test`
112
- runs the suite with fake `herdr`, `hc`, `codexbar` and agent CLIs.
72
+ ## Credits
113
73
 
114
- Intelligence Index and cost per task: [Artificial Analysis](https://artificialanalysis.ai/).
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)