harma-kit 0.1.0 → 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 +29 -19
- package/README.md +51 -92
- 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/roster.mjs +177 -0
- package/src/tui.mjs +345 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,21 +1,31 @@
|
|
|
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.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/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)
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Agents, sessions and backends
|
|
2
|
+
|
|
3
|
+
This page explains where harma runs agents, how it keeps each agent's session ID so you can resume it, and which files it writes in your project. harma only closes what it started, as recorded in `.harma/agents.jsonl`.
|
|
4
|
+
|
|
5
|
+
## Backends
|
|
6
|
+
|
|
7
|
+
harma runs each agent in a terminal managed by one of two backends. With `--backend auto` (the default) it uses herdr when herdr is running, otherwise herdr-core. harma never starts, stops or restarts the backend's server.
|
|
8
|
+
|
|
9
|
+
- **[herdr](https://herdr.dev)**: harma creates one workspace per project, labelled `harma:<project>`, and one tab per agent. Closing an agent closes its tab. herdr's agent detection reports each agent's state and session ID.
|
|
10
|
+
- **[herdr-core](https://github.com/herdrdev/herdr-core) (`hc`)**: harma starts headless terminals labelled `harma.project` and `harma.agent`, with `--outlive-parent` so they survive the orchestrator's session. State comes from the terminal's status reports. Open one with `hc attach agent_name`.
|
|
11
|
+
|
|
12
|
+
## Session IDs
|
|
13
|
+
|
|
14
|
+
A session ID lets the agent CLI reopen a conversation with its full context. harma records it as soon as it's known:
|
|
15
|
+
|
|
16
|
+
- **Claude Code**: harma generates the ID and passes it with `--session-id` when it starts the agent
|
|
17
|
+
- **Codex**: Codex creates the ID on its first turn; harma reads it from herdr's agent detection, or from `~/.codex/sessions` by matching the folder and start time
|
|
18
|
+
|
|
19
|
+
Other CLIs run normally, but harma can resume only Claude Code and Codex sessions.
|
|
20
|
+
|
|
21
|
+
## Clean up finished agents
|
|
22
|
+
|
|
23
|
+
At the end of each step, the orchestrator runs:
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
harma cleanup --dry-run
|
|
27
|
+
harma cleanup
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The first command lists what would close, with session IDs. The second saves each session ID to `.harma/agents.jsonl`, then closes the agent's tab or terminal.
|
|
31
|
+
|
|
32
|
+
`cleanup` keeps an agent open in two cases: it's still `working` or `blocked`, or harma can't find its session ID, since closing it would lose the context. `--force` closes it anyway, and `--agent agent_name` limits cleanup to one agent. Once no harma agent is open, `harma cleanup --workspace` also closes the herdr workspace harma created.
|
|
33
|
+
|
|
34
|
+
## Resume an agent
|
|
35
|
+
|
|
36
|
+
`resume` reopens a closed agent's session in a new tab or terminal, with the same model and effort:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
harma resume planner --print-only
|
|
40
|
+
harma resume planner --yes
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`--print-only` shows the native command, for example `claude --resume <session_id> --model claude-opus-5-5 --effort high` or `codex resume <session_id> -m gpt-6.1-sol -c model_reasoning_effort="high"`. Under the `confirm` policy, resuming needs `--yes`.
|
|
44
|
+
|
|
45
|
+
## Project files
|
|
46
|
+
|
|
47
|
+
harma keeps its state in `.harma/` at the project root:
|
|
48
|
+
|
|
49
|
+
| Path | Contents |
|
|
50
|
+
|---|---|
|
|
51
|
+
| `.harma/config.json` | Orchestrator, backend, dispatch policy, budgets, thresholds, routing overrides and your model choices (`roster`) |
|
|
52
|
+
| `.harma/agents.jsonl` | Append-only events: `orchestrator`, `started`, `session`, `prompted`, `blocked`, `closed`, `resumed`, `roster` |
|
|
53
|
+
| `.harma/cache/` | Last inventory, credits, ranking and selection status, each with its fetch time; git ignores this folder |
|
|
54
|
+
|
|
55
|
+
`config.json` and `agents.jsonl` are plain files you can read and commit. Edit `config.json` by hand only for `budgets`, `thresholds` and `routing`; use `harma init` and `harma select` for the rest.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Choose the models for each job
|
|
2
|
+
|
|
3
|
+
This guide shows how to accept the orchestrator's proposals or choose your own models and effort levels, for the orchestrator and for each kind of job. Your choices are stored per project, and `harma dispatch --task-type` uses them before any proposal.
|
|
4
|
+
|
|
5
|
+
## Kinds of job
|
|
6
|
+
|
|
7
|
+
harma sorts work into six jobs. The CLI uses the Italian names and accepts the English aliases:
|
|
8
|
+
|
|
9
|
+
| Job | Aliases | What the proposal favours |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `pianificazione` | `planning`, `plan` | Highest intelligence; cost matters little |
|
|
12
|
+
| `sviluppo` | `development`, `dev`, `build` | High intelligence at a reasonable cost |
|
|
13
|
+
| `review` | `code-review`, `revisione` | A vendor other than the one that wrote the code |
|
|
14
|
+
| `debugging` | `debug`, `problem-solving` | High intelligence; cost matters little |
|
|
15
|
+
| `ricerca` | `research` | Good intelligence at a contained cost |
|
|
16
|
+
| `estrazione` | `extraction`, `clerk` | The cheapest model above a minimum score |
|
|
17
|
+
|
|
18
|
+
[How harma decides](how-harma-decides.md) explains the scoring behind each proposal.
|
|
19
|
+
|
|
20
|
+
## Open the selection screen
|
|
21
|
+
|
|
22
|
+
Run `harma select` in your own terminal from the project folder. When an agent drives harma it has no terminal of its own, so it runs this instead:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
harma select --open --wait
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
That opens the screen in a focused herdr tab (or an `hc` terminal) and returns your choices to the agent once you save.
|
|
29
|
+
|
|
30
|
+
The screen lists the orchestrator first, then one row per job, each with the proposal and your current choice. Use these keys:
|
|
31
|
+
|
|
32
|
+
| Key | Action |
|
|
33
|
+
|---|---|
|
|
34
|
+
| `↑` `↓` (or `k` `j`) | Move between rows |
|
|
35
|
+
| `Enter` | Open the row: pick the orchestrator's model, or open a job's list of models |
|
|
36
|
+
| `a` | Accept the proposal for this row |
|
|
37
|
+
| `A` | Accept every proposal |
|
|
38
|
+
| `x` | Clear the row (it goes back to undecided) |
|
|
39
|
+
| `s` | Save to `.harma/config.json` |
|
|
40
|
+
| `q` or `Esc` | Quit; harma asks first if you have unsaved changes |
|
|
41
|
+
|
|
42
|
+
Each model is shown with its best AA Intelligence Index and its provider's credit state. Each effort level is shown with its index and cost per task. A job can also be set to "no model", and `dispatch` then refuses that job.
|
|
43
|
+
|
|
44
|
+
## Use several models for one job
|
|
45
|
+
|
|
46
|
+
A job can hold up to five models in order of preference. When you open a job, its list appears with these keys:
|
|
47
|
+
|
|
48
|
+
| Key | Action |
|
|
49
|
+
|---|---|
|
|
50
|
+
| `+` | Add a model, then choose its effort |
|
|
51
|
+
| `Enter` | Change the selected model or its effort; on the "add" line, add one |
|
|
52
|
+
| `d` (or `Backspace`) | Remove the selected model |
|
|
53
|
+
| `K` `J` (or `Shift` `↑` `↓`) | Move the selected model up or down |
|
|
54
|
+
| `a` | Replace the list with the proposal |
|
|
55
|
+
| `Esc` | Go back to the rows |
|
|
56
|
+
|
|
57
|
+
The proposal for each job is the best candidate plus a backup on a different CLI, so the job keeps a model when one provider runs low.
|
|
58
|
+
|
|
59
|
+
At dispatch, harma goes down your list in order:
|
|
60
|
+
|
|
61
|
+
1. It skips a model whose CLI isn't installed or whose credits are exhausted (`esaurito`)
|
|
62
|
+
2. It passes over a model whose credits are low (`scarso`) when a later one has more
|
|
63
|
+
3. It takes the first model left; if none is left, `dispatch` stops and lists why each one was skipped
|
|
64
|
+
|
|
65
|
+
The dispatch plan names the model it took and its position, for example `n.2 di 2 — n.1 codex:gpt-6.1-sol @ xhigh saltato: crediti scarso`. `harma route <job>` shows which model on your list `dispatch` would take right now.
|
|
66
|
+
|
|
67
|
+
## Choose without the screen
|
|
68
|
+
|
|
69
|
+
The same choices work as options, which helps when you answer the orchestrator in chat:
|
|
70
|
+
|
|
71
|
+
```sh
|
|
72
|
+
harma select --set "sviluppo=codex:gpt-6.1-sol@xhigh|claude:claude-sonnet-5-5@high,review=none"
|
|
73
|
+
harma select --accept
|
|
74
|
+
harma select --show
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`--set` takes `job=harness:model@effort`, separated by commas. Separate models for the same job with `|`, in order of preference, and use `none` for no model. The orchestrator takes exactly one model. `--accept` accepts every proposal and `--show` prints the current choices.
|
|
78
|
+
|
|
79
|
+
## What gets saved
|
|
80
|
+
|
|
81
|
+
Saving writes the `roster` section of `.harma/config.json` and adds a `roster` event to `.harma/agents.jsonl`. Each job records its models in order, whether you accepted the proposal (`proposta`) or chose them (`utente`), the proposal at that time, and the date. Every project has its own roster.
|
|
82
|
+
|
|
83
|
+
Saving choices never starts an agent: each `dispatch` still asks for your confirmation.
|
package/docs/commands.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# Command reference
|
|
2
|
+
|
|
3
|
+
This page lists every `harma` command with its options and exit codes. harma prints its own messages in Italian; every command also takes `--json` for output an agent can parse.
|
|
4
|
+
|
|
5
|
+
Model targets are written `harness:model`, where the harness is the CLI that runs the model, for example `claude:claude-opus-5-5` or `codex:gpt-6.1-sol`. `harma models` lists the valid pairs on your machine.
|
|
6
|
+
|
|
7
|
+
## Set up a project
|
|
8
|
+
|
|
9
|
+
| Command | Description |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `init --orchestrator harness:model --effort level` | Creates `.harma/` and records the orchestrator |
|
|
12
|
+
|
|
13
|
+
`init` options:
|
|
14
|
+
|
|
15
|
+
- `--backend auto|herdr|hc`: terminal backend; `auto` (default) uses herdr when it runs, otherwise `hc`
|
|
16
|
+
- `--policy confirm|auto-within-budget`: dispatch policy; `confirm` is the default, see [consent](how-harma-decides.md#consent)
|
|
17
|
+
|
|
18
|
+
## Know your resources
|
|
19
|
+
|
|
20
|
+
| Command | Description |
|
|
21
|
+
|---|---|
|
|
22
|
+
| `models` | Agent CLIs on `PATH`, their models and effort levels, with the source of each row |
|
|
23
|
+
| `credits` | Remaining share per provider and its state: `ampio`, `ok`, `scarso`, `esaurito` or `sconosciuto` |
|
|
24
|
+
| `rank [--refresh] [--top count]` | AA Intelligence Index and cost per task for each model and effort; `--refresh` updates the scores from the AA API |
|
|
25
|
+
| `route job [--author harness:model] [--top count]` | Best candidates for a job, your saved choice, and which of your models `dispatch` would use now |
|
|
26
|
+
|
|
27
|
+
`--author` on `route review` excludes the vendor of the model that wrote the code.
|
|
28
|
+
|
|
29
|
+
## Choose models
|
|
30
|
+
|
|
31
|
+
| Command | Description |
|
|
32
|
+
|---|---|
|
|
33
|
+
| `select` | Opens the selection screen in this terminal |
|
|
34
|
+
| `select --open [--wait] [--timeout seconds]` | Opens the screen in a focused herdr tab or an `hc` terminal; `--wait` returns your choices once you save (default timeout 900) |
|
|
35
|
+
| `select --set "job=harness:model@effort\|…,…"` | Records choices without the screen; `none` means no model for that job |
|
|
36
|
+
| `select --accept` | Accepts every proposal |
|
|
37
|
+
| `select --show` | Prints the current choices and proposals |
|
|
38
|
+
|
|
39
|
+
[Choose the models for each job](choosing-models.md) covers the screen and the `--set` syntax.
|
|
40
|
+
|
|
41
|
+
## Delegate work
|
|
42
|
+
|
|
43
|
+
These commands start or instruct an agent, so under the `confirm` policy they need `--yes`. Without it they print the plan and exit with code 3.
|
|
44
|
+
|
|
45
|
+
| Command | Description |
|
|
46
|
+
|---|---|
|
|
47
|
+
| `dispatch --name agent_name (--model harness:model [--effort level] \| --task-type job)` | Starts an agent in its own tab or terminal and sends it the task |
|
|
48
|
+
| `send agent_name "text" [--wait] [--timeout seconds]` | Gives an open agent more work |
|
|
49
|
+
| `read agent_name [--lines count]` | Prints the agent's recent screen output |
|
|
50
|
+
|
|
51
|
+
`dispatch` options:
|
|
52
|
+
|
|
53
|
+
- `--prompt "text"` or `--prompt-file path`: the task to send once the agent starts
|
|
54
|
+
- `--task-type job`: uses your saved models for that job, otherwise the best route candidate
|
|
55
|
+
- `--cwd path`: working folder for the agent (default: the project root)
|
|
56
|
+
- `--wait`: waits until the agent is idle again; `--timeout seconds` (default 600)
|
|
57
|
+
- `--author harness:model`: with `--task-type review` and no saved choice, excludes that vendor
|
|
58
|
+
|
|
59
|
+
Agent names are lowercase, start with a letter, use `a-z`, `0-9`, `_` or `-`, are at most 32 characters, and are unique among open agents.
|
|
60
|
+
|
|
61
|
+
## Watch agents
|
|
62
|
+
|
|
63
|
+
| Command | Description |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `status [--all]` | Each open agent: model, effort, live state, age and session ID; `--all` includes closed agents |
|
|
66
|
+
| `costs` | Estimated cost per agent, credits per provider, and advice on where to delegate more or less |
|
|
67
|
+
|
|
68
|
+
Live states come from the backend: `working`, `idle`, `done`, `blocked`, `unknown` or `finished`.
|
|
69
|
+
|
|
70
|
+
## Clean up and resume
|
|
71
|
+
|
|
72
|
+
| Command | Description |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `cleanup [--dry-run] [--agent agent_name] [--force] [--workspace]` | Saves session IDs, then closes finished agents |
|
|
75
|
+
| `resume agent_name [--print-only] [--yes]` | Reopens a closed agent's session with its model and effort |
|
|
76
|
+
|
|
77
|
+
`cleanup` keeps agents that are `working` or `blocked` and agents whose session ID it can't find; `--force` closes them anyway. `--workspace` also closes the herdr workspace harma created, once no harma agent is open. `resume --print-only` prints the native resume command without running it.
|
|
78
|
+
|
|
79
|
+
## Install the skill
|
|
80
|
+
|
|
81
|
+
| Command | Description |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `install [--target claude\|codex\|both] [--force]` | Copies the skill into `~/.claude/skills/harma` and `~/.codex/skills/harma` |
|
|
84
|
+
| `uninstall [--target claude\|codex\|both] [--force]` | Removes the skill harma installed |
|
|
85
|
+
| `doctor` | Checks Node.js, catalog, backends, agent CLIs, CodexBar, the AA key and the installed skill |
|
|
86
|
+
|
|
87
|
+
harma doesn't overwrite or remove a skill folder it didn't install unless you pass `--force`.
|
|
88
|
+
|
|
89
|
+
## Exit codes
|
|
90
|
+
|
|
91
|
+
| Code | Meaning |
|
|
92
|
+
|---|---|
|
|
93
|
+
| 0 | Done |
|
|
94
|
+
| 1 | Error; the message says what failed and how to fix it |
|
|
95
|
+
| 3 | Needs your confirmation; nothing was started (rerun with `--yes` after you agree) |
|
|
96
|
+
| 4 | `dispatch` started the agent, but it waits on a dialog and the task wasn't sent; see [troubleshooting](troubleshooting.md#an-agent-waits-on-a-dialog) |
|
|
97
|
+
|
|
98
|
+
## Environment variables
|
|
99
|
+
|
|
100
|
+
| Variable | Use |
|
|
101
|
+
|---|---|
|
|
102
|
+
| `AA_API_KEY` | Artificial Analysis API key for `rank --refresh` |
|
|
103
|
+
| `HERDR_TAB_ID` | Set by herdr; `select --open` uses it to close its own tab |
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Development
|
|
2
|
+
|
|
3
|
+
This page covers working on harma itself: running the tests, updating the model catalog and publishing a release. harma is plain JavaScript modules for Node.js 20 or later, with no dependencies.
|
|
4
|
+
|
|
5
|
+
## Repository layout
|
|
6
|
+
|
|
7
|
+
| Path | Contents |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `bin/harma.mjs` | Command entry point |
|
|
10
|
+
| `src/` | Commands, backends, credits, ranking, routing, roster and the selection screen |
|
|
11
|
+
| `skill/SKILL.md` | The skill that `harma install` copies for Claude Code and Codex |
|
|
12
|
+
| `data/catalog.json` | Bundled models, efforts, prices and Artificial Analysis scores |
|
|
13
|
+
| `scripts/import-catalog.mjs` | Rebuilds the catalog |
|
|
14
|
+
| `tests/` | Test suite |
|
|
15
|
+
| `docs/` | This documentation |
|
|
16
|
+
|
|
17
|
+
## Run the tests
|
|
18
|
+
|
|
19
|
+
```sh
|
|
20
|
+
npm test
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The suite runs with fake `herdr`, `hc`, `codexbar` and agent CLIs on a private `PATH`, so it never starts a real agent or reads your real credits. The selection screen is a pure state machine (`reduce` and `render` in `src/tui.mjs`), and the tests drive it with simulated keys.
|
|
24
|
+
|
|
25
|
+
## Update the catalog
|
|
26
|
+
|
|
27
|
+
The catalog comes from a local checkout of controller-models, the model registry that holds the Artificial Analysis snapshots:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
node scripts/import-catalog.mjs path_to_controller_models
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The script also reads the path from `HARMA_CONTROLLER_MODELS`. Users can refresh scores on their own machine with `harma rank --refresh`, without a new release.
|
|
34
|
+
|
|
35
|
+
## Release
|
|
36
|
+
|
|
37
|
+
1. Update `version` in `package.json` and add an entry to `CHANGELOG.md`
|
|
38
|
+
2. Run `npm test` and `node bin/harma.mjs doctor`
|
|
39
|
+
3. Check the package contents with `npm pack --dry-run`
|
|
40
|
+
4. Push to GitHub, then run `npm publish`; `prepublishOnly` runs the tests again
|
|
41
|
+
|
|
42
|
+
The package is published as `harma-kit`, and it installs the `harma` and `harma-kit` commands.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# How harma decides
|
|
2
|
+
|
|
3
|
+
This page explains where harma's numbers come from and how it turns them into proposals: the intelligence scores, the routing formula, the credit states, the cost estimates and the consent policy. Every value harma shows carries its source and date, and anything it can't measure is shown as unknown (`sconosciuto`) rather than guessed.
|
|
4
|
+
|
|
5
|
+
## Intelligence scores
|
|
6
|
+
|
|
7
|
+
Model intelligence comes from the [Artificial Analysis](https://artificialanalysis.ai/models) Intelligence Index, version 5.0, measured separately for each effort level, together with Artificial Analysis's cost per task. harma bundles a snapshot dated 2026-10-28 in `data/catalog.json`.
|
|
8
|
+
|
|
9
|
+
`harma rank --refresh` downloads current scores from the Artificial Analysis API and writes them to `~/.config/harma/catalog.json`, which harma uses instead of the bundled snapshot when it's newer. The API key is read from `AA_API_KEY`, or from the delegation-kit key file `~/.local/share/delegation-kit/config/artificial-analysis.env` when it exists. A model or effort level without a score stays unknown, and routing leaves it out.
|
|
10
|
+
|
|
11
|
+
## Routing
|
|
12
|
+
|
|
13
|
+
For each job, harma scores every installed model and effort pair:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
score = index − cost_weight × cost_per_task + credit_adjustment
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Each job has its own minimum index and cost weight, so planning favours intelligence while research and development weigh cost more:
|
|
20
|
+
|
|
21
|
+
| Job | Minimum index | Cost weight | Rule |
|
|
22
|
+
|---|---|---|---|
|
|
23
|
+
| `pianificazione` | 45 | 0.5 | |
|
|
24
|
+
| `sviluppo` | 40 | 1.5 | |
|
|
25
|
+
| `review` | 42 | 1 | Excludes the author's vendor when you pass `--author` |
|
|
26
|
+
| `debugging` | 45 | 0.75 | |
|
|
27
|
+
| `ricerca` | 35 | 1.5 | |
|
|
28
|
+
| `estrazione` | 30 | | Cheapest model above the minimum; credits only break ties |
|
|
29
|
+
|
|
30
|
+
The credit adjustment is +2 for `ampio`, 0 for `ok`, −1 for `sconosciuto` and −8 for `scarso`. Models whose credits are `esaurito` are left out. When a cost per task is unknown, harma assumes the highest known cost, so an unmeasured model never looks cheap.
|
|
31
|
+
|
|
32
|
+
To change a profile for one project, set `routing.<job>` in `.harma/config.json`, for example `{"routing": {"sviluppo": {"min_index": 45, "cost_weight": 1}}}`.
|
|
33
|
+
|
|
34
|
+
The proposal for each job is the top candidate plus the best candidate on a different CLI, as a backup. When you've saved your own models for a job, `dispatch --task-type` uses them instead; [Choose the models for each job](choosing-models.md#use-several-models-for-one-job) explains how it picks among them.
|
|
35
|
+
|
|
36
|
+
## Credits
|
|
37
|
+
|
|
38
|
+
harma reads remaining credit per provider from [CodexBar](https://github.com/steipete/CodexBar) (`codexbar usage --format json --provider all`), removes the account identity from the result, and caches it for 15 minutes.
|
|
39
|
+
|
|
40
|
+
When CodexBar doesn't report a provider, harma falls back to a budget you declare in `.harma/config.json`:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{ "budgets": { "codex": { "limit": 100, "currency": "USD" } } }
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
It compares that budget with the cost estimated from the last 7 days of local session logs. With neither CodexBar nor a budget, the credit state is `sconosciuto`.
|
|
47
|
+
|
|
48
|
+
The remaining share maps to a state through `thresholds` in `.harma/config.json`:
|
|
49
|
+
|
|
50
|
+
| State | Remaining share (defaults) |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `esaurito` | Below 5% |
|
|
53
|
+
| `scarso` | Below 20% |
|
|
54
|
+
| `ok` | From 20% to below 60% |
|
|
55
|
+
| `ampio` | 60% or more |
|
|
56
|
+
| `sconosciuto` | Not measured |
|
|
57
|
+
|
|
58
|
+
## Cost estimates
|
|
59
|
+
|
|
60
|
+
`harma costs` estimates what each agent has used from its local session log: `~/.claude/projects` for Claude Code and `~/.codex/sessions` for Codex. It multiplies the input, output and cached tokens by the API list prices in the catalog.
|
|
61
|
+
|
|
62
|
+
For a subscription, that figure is what the same usage would cost at API prices, not what you pay. OpenAI's cached input is counted at 10% of the input price, which is an assumption harma states in its output. `costs` also suggests delegating more to providers with `ampio` credits and less to those that are `scarso`.
|
|
63
|
+
|
|
64
|
+
## Consent
|
|
65
|
+
|
|
66
|
+
The dispatch policy decides when harma may start or instruct an agent:
|
|
67
|
+
|
|
68
|
+
- **`confirm`** (default): `dispatch`, `send` and `resume` refuse to run without `--yes` and exit with code 3, showing the plan. The orchestrator asks you, then reruns with `--yes`.
|
|
69
|
+
- **`auto-within-budget`**: harma starts an agent without asking only when that provider's credits are `ok` or `ampio`; otherwise it asks as under `confirm`.
|
|
70
|
+
|
|
71
|
+
Only you set `auto-within-budget`, with `harma init --policy auto-within-budget`. The skill tells the orchestrator never to change the policy, and a saved model choice is never consent to start an agent.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
This page covers the situations where harma stops and asks for something, and how to get past each one. Start with `harma doctor`, which checks Node.js, the catalog, the backends, the agent CLIs, CodexBar, the Artificial Analysis key and the installed skill, and says what to install for each missing piece.
|
|
4
|
+
|
|
5
|
+
## A command exits with code 3
|
|
6
|
+
|
|
7
|
+
Code 3 isn't an error: harma needs your confirmation before it starts or instructs an agent. It prints the plan (model, effort, command and why) and starts nothing. When you agree, the orchestrator reruns the same command with `--yes`. Your yes covers that one dispatch, not retries or extra agents.
|
|
8
|
+
|
|
9
|
+
## An agent waits on a dialog
|
|
10
|
+
|
|
11
|
+
`dispatch` exits with code 4 when the agent started but waits on a question, often "Do you trust this folder?" the first time a CLI opens a new directory. The task wasn't sent. To continue:
|
|
12
|
+
|
|
13
|
+
1. Run `harma read agent_name` to see the question
|
|
14
|
+
2. Answer it yourself in the agent's tab or terminal; the orchestrator must not answer approval dialogs for you
|
|
15
|
+
3. Send the task again with `harma send agent_name "task" --yes`
|
|
16
|
+
|
|
17
|
+
## The selection screen needs a terminal
|
|
18
|
+
|
|
19
|
+
`harma select` without options needs an interactive terminal. An agent has none, so it runs `harma select --open --wait`, which opens the screen in a herdr tab or an `hc` terminal. Without either, record choices with `harma select --set`, `--accept` or `--show`; see [Choose the models for each job](choosing-models.md#choose-without-the-screen).
|
|
20
|
+
|
|
21
|
+
## Dispatch finds no usable model for a job
|
|
22
|
+
|
|
23
|
+
`dispatch --task-type` stops when every model you saved for that job is unavailable: its CLI isn't installed or its credits are exhausted. The message lists the reason for each model. Add another model with `harma select`, wait for the provider's reset, or pass `--model harness:model` for this one dispatch.
|
|
24
|
+
|
|
25
|
+
When you chose "no model" for a job, `dispatch --task-type` refuses it by design; pass `--model` or change the choice.
|
|
26
|
+
|
|
27
|
+
## Credits show as unknown
|
|
28
|
+
|
|
29
|
+
`sconosciuto` means harma has no reliable figure for that provider:
|
|
30
|
+
|
|
31
|
+
- **CodexBar isn't installed or not running**: install [CodexBar](https://github.com/steipete/CodexBar), or declare a budget
|
|
32
|
+
- **CodexBar doesn't report this provider**: enable the provider in the CodexBar app
|
|
33
|
+
- **No CodexBar and no budget**: add `budgets.<provider>` to `.harma/config.json`, as shown in [How harma decides](how-harma-decides.md#credits)
|
|
34
|
+
|
|
35
|
+
## A model has no score
|
|
36
|
+
|
|
37
|
+
The bundled snapshot doesn't cover every model and effort level. Set `AA_API_KEY` and run `harma rank --refresh` to fetch current scores. A model that Artificial Analysis hasn't measured stays unknown and doesn't appear in proposals, but you can still choose it in `harma select` or pass it with `--model`.
|
|
38
|
+
|
|
39
|
+
## Cleanup keeps an agent open
|
|
40
|
+
|
|
41
|
+
`cleanup` keeps agents that are `working` or `blocked`, and agents whose session ID it can't find, because closing them would lose work or context. Check them with `harma status` and `harma read agent_name`. Use `harma cleanup --force` only when you're sure you don't need the session again.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "harma-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "A skill for Claude Code and Codex that lets one orchestrator model run a project: it inventories the models on your machine, reads their credits and intelligence per effort, routes work to them through herdr or herdr-core, watches cost, and saves every agent's session before closing it.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
"bin/",
|
|
31
31
|
"src/",
|
|
32
32
|
"skill/",
|
|
33
|
+
"docs/",
|
|
33
34
|
"data/",
|
|
34
35
|
"README.md",
|
|
35
36
|
"CHANGELOG.md",
|