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 +31 -0
- package/LICENSE +21 -0
- package/README.md +77 -2
- package/bin/harma.mjs +4 -0
- package/data/catalog.json +1085 -0
- 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 +49 -4
- package/skill/SKILL.md +122 -0
- package/skill/references/commands.md +49 -0
- package/skill/references/troubleshooting.md +37 -0
- package/src/backends.mjs +233 -0
- package/src/catalog.mjs +54 -0
- package/src/cli.mjs +98 -0
- package/src/commands.mjs +680 -0
- package/src/credits.mjs +101 -0
- package/src/harness.mjs +94 -0
- package/src/install.mjs +106 -0
- package/src/inventory.mjs +72 -0
- package/src/rank.mjs +102 -0
- package/src/roster.mjs +177 -0
- package/src/route.mjs +69 -0
- package/src/state.mjs +134 -0
- package/src/tui.mjs +345 -0
- package/src/usage.mjs +127 -0
- package/src/util.mjs +90 -0
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
|
-
#
|
|
1
|
+
# harma
|
|
2
2
|
|
|
3
|
-
|
|
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