harma-kit 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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,31 @@
1
+ # Changelog
2
+
3
+ All notable changes to harma, newest first. Versions follow [semantic versioning](https://semver.org/).
4
+
5
+ ## 0.2.0 (unreleased)
6
+
7
+ You can now choose the models for each job yourself, or accept the orchestrator's proposals:
8
+
9
+ - **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
10
+ - **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
11
+ - **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
12
+ - **For agents**: `select --open --wait` opens the screen in a focused herdr tab (or an `hc` terminal) and returns your choices when you save
13
+ - **Without the screen**: `select --set "job=harness:model@effort|…"`, `--accept` and `--show`
14
+ - **Routing**: `route` shows your list and which model on it `dispatch` would use now; `dispatch --task-type` uses your list before the routing proposal
15
+ - **Docs**: the README is now a short overview, with guides and reference pages in `docs/`
16
+
17
+ 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.
18
+
19
+ ## 0.1.0 (2026-11-08)
20
+
21
+ First release:
22
+
23
+ - **`init`**: records the orchestrator model and effort for a project
24
+ - **`models`**: lists agent CLIs, models and effort levels; Codex models come from `~/.codex/models_cache.json`, the others from the catalog
25
+ - **`credits`**: reads CodexBar, falling back to a declared budget against an estimate from local logs
26
+ - **`rank`**: Artificial Analysis Intelligence Index for each model and effort; `--refresh` updates it from the AA API with a key
27
+ - **`route`**: profiles for planning, development, review (another vendor), debugging, research and extraction (cheapest)
28
+ - **`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
29
+ - **`status`, `costs`**: live state, estimated cost per agent and delegation advice
30
+ - **`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
31
+ - **`install`, `uninstall`, `doctor`**: install the skill for Claude Code and Codex and check the setup
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Matteo Scurati
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,78 @@
1
- # Temporary Holding Version
1
+ # harma
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
+ 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.
31
+
32
+ ## Install
33
+
34
+ Install the skill for Claude Code and Codex, then check the setup:
35
+
36
+ ```sh
37
+ npx harma-kit install
38
+ npx harma-kit doctor
39
+ ```
40
+
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`.
42
+
43
+ ## Get started
44
+
45
+ In a project, ask Claude Code or Codex for what you want, in your own words:
46
+
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.
48
+
49
+ The skill turns that request into harma commands. These are the main ones:
50
+
51
+ ```sh
52
+ harma init --orchestrator claude:claude-opus-5-5 --effort high
53
+ harma models && harma credits && harma rank --top 15
54
+ harma select --open --wait
55
+ harma dispatch --name planner --task-type pianificazione --prompt-file brief.md
56
+ harma status
57
+ harma cleanup
58
+ ```
59
+
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`.
61
+
62
+ ## Documentation
63
+
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)
71
+
72
+ ## Credits
73
+
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.
75
+
76
+ ## License
77
+
78
+ [MIT](LICENSE)
package/bin/harma.mjs ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../src/cli.mjs';
3
+
4
+ process.exitCode = await main(process.argv.slice(2));