harma-kit 0.0.0-stage → 0.1.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,21 @@
1
+ # Changelog
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.
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,119 @@
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
+ 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.
20
+
21
+ ## Install
22
+
23
+ ```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
28
+ ```
29
+
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`)**.
32
+
33
+ ## Use it from your agent
34
+
35
+ In a project, tell Claude or Codex something like:
36
+
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.
40
+
41
+ The skill turns that into:
42
+
43
+ ```sh
44
+ harma init --orchestrator claude:claude-opus-5-5 --effort high
45
+ 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
49
+ harma status
50
+ harma costs
51
+ harma cleanup
52
+ harma resume planner --yes
53
+ ```
54
+
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
102
+
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
+ ```
108
+
109
+ ## Maintainers
110
+
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.
113
+
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.
116
+
117
+ ## License
118
+
119
+ MIT
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));