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 +38 -19
- package/README.md +51 -92
- package/data/catalog.json +479 -176
- 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/harness.mjs +3 -2
- package/src/rank.mjs +34 -14
- package/src/roster.mjs +177 -0
- package/src/tui.mjs +345 -0
|
@@ -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.2-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.2-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.2-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.2-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 and cost per task from the free Artificial Analysis API (`/api/v2/language/models/free`, every page) 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.1
|
|
3
|
+
"version": "0.2.1",
|
|
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",
|
package/skill/SKILL.md
CHANGED
|
@@ -1,131 +1,122 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: harma
|
|
3
|
-
description: Run a project as the orchestrator model over other coding agents with the harma CLI
|
|
3
|
+
description: Run a project as the orchestrator model over other coding agents with the harma CLI. It inventories the agent CLIs, models and effort levels on this machine, reads each provider's remaining credits, ranks models by Artificial Analysis intelligence per effort, lets the user choose one or more models per job, starts agents in herdr or herdr-core terminals after consent, monitors them, tracks cost, and closes finished agents after saving their session ids so they can be resumed. Use it whenever the user names an orchestrator or a model "responsible" for a project, asks which models or effort levels are available, how much credit is left, which model is best for planning, development, review, debugging, research or extraction, wants work delegated or split across models or agents, wants to check on, clean up or resume agents, or mentions harma or herdr, in any language (for example "orchestratore", "quali modelli ho", "crediti", "delega", "riprendi la sessione"). Do not use it for a task the user wants done by the current model alone.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# harma
|
|
7
7
|
|
|
8
|
-
You are, or are about to become, the **orchestrator** of this project: the model that decides which
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
reviewers, extra workers or later turns. If the user's own instructions (CLAUDE.md, AGENTS.md)
|
|
22
|
-
are stricter, follow them.
|
|
23
|
-
The policy `auto-within-budget` exists for users who set it themselves in `.harma/config.json`;
|
|
24
|
-
never set it on your own.
|
|
25
|
-
2. **Never invent numbers.** Models, efforts, credits, prices and scores come from harma's output,
|
|
26
|
-
each with its source and date. When harma says `sconosciuto` (unknown), say unknown.
|
|
27
|
-
3. **Close only what harma opened.** `cleanup` touches only terminals/tabs recorded in
|
|
28
|
-
`.harma/agents.jsonl`. Do not close other panes, tabs, workspaces or servers.
|
|
29
|
-
4. **Do not hand off your own role.** You stay the orchestrator; agents report to you, you verify
|
|
30
|
-
their results before telling the user something is done.
|
|
8
|
+
You are, or are about to become, the **orchestrator** of this project: the model that decides which agent does which job, watches the agents, and keeps the workspace clean. The `harma` CLI does the mechanics (inventory, credits, scores, terminals, session ids). You do the judgement and talk to the user.
|
|
9
|
+
|
|
10
|
+
Run it as `harma <command>` when it's installed globally, otherwise as `npx -y harma-kit <command>`. Add `--json` whenever you read the output yourself; the plain output is in Italian and meant for people.
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
These rules protect the user's money, their machine and their trust. They hold even when a shortcut looks harmless.
|
|
15
|
+
|
|
16
|
+
1. **No agent starts without the user's consent.** Every agent you start spends the user's credits and touches their files. `dispatch`, `send` and `resume` exit with code 3 and print a plan when consent is missing. Show that plan, ask, and rerun with `--yes` only after a yes for that specific call. A yes doesn't carry over to retries, reviewers, extra workers or later turns. If the user's own instructions (CLAUDE.md, AGENTS.md) are stricter, follow them. Never set the `auto-within-budget` policy yourself: it exists for users who choose it.
|
|
17
|
+
2. **Never invent numbers.** Models, efforts, credits, prices and scores come from harma's output, with their source and date. When harma says `sconosciuto`, tell the user it's unknown. A made-up score or balance leads the user to spend money on a wrong premise.
|
|
18
|
+
3. **Close only what harma opened.** `cleanup` touches only the agents recorded in `.harma/agents.jsonl`. Other panes, tabs, workspaces and servers belong to the user.
|
|
19
|
+
4. **Stay the orchestrator.** Agents report to you. Read and check their work before telling the user something is done, because an agent that says "done" may not be.
|
|
20
|
+
5. **Never answer an agent's approval or trust dialog.** Those questions are addressed to the user. Read them and pass them on.
|
|
31
21
|
|
|
32
22
|
## Workflow
|
|
33
23
|
|
|
34
24
|
### 1. Set the orchestrator
|
|
35
|
-
|
|
36
|
-
|
|
25
|
+
|
|
26
|
+
When the user names the model and effort responsible for the project:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
37
29
|
harma init --orchestrator <harness>:<model> --effort <level>
|
|
38
30
|
```
|
|
39
|
-
|
|
40
|
-
If the user names you, use your own harness and model id. `harma models` lists valid pairs.
|
|
31
|
+
|
|
32
|
+
The harness is the CLI that runs the model (`claude`, `codex`, `agy`, `kimi`, `grok`, `muse`, `qwen`, …). If the user names you, use your own harness and model id. `harma models --json` lists the valid pairs.
|
|
41
33
|
|
|
42
34
|
### 2. Know what is available
|
|
43
|
-
```
|
|
44
|
-
harma models --json # CLIs on PATH, models, supported efforts, source of each row
|
|
45
|
-
harma credits --json # remaining % per provider, status (ampio/ok/scarso/esaurito/sconosciuto), source
|
|
46
|
-
harma rank --json # AA Intelligence Index per model × effort, cost per task, date
|
|
47
|
-
```
|
|
48
|
-
- Credits come from CodexBar when installed. Without it, or for providers it does not cover,
|
|
49
|
-
harma uses a budget the user declared in `.harma/config.json` → `budgets.<provider>`
|
|
50
|
-
(`{"limit": 100, "currency": "USD"}`) against an estimate from local session logs, otherwise
|
|
51
|
-
reports unknown. Suggest the user enable the provider in CodexBar or declare a budget.
|
|
52
|
-
- The "stima 7g" figure is local tokens × API list price. For a subscription it is **not** what the
|
|
53
|
-
user pays; say so when you quote it.
|
|
54
|
-
- `harma rank --refresh` updates the scores from the Artificial Analysis API when `AA_API_KEY` is
|
|
55
|
-
set. Mention the snapshot date when you rely on the bundled data.
|
|
56
|
-
|
|
57
|
-
### 3. Route work
|
|
58
|
-
```
|
|
59
|
-
harma route <pianificazione|sviluppo|review|debugging|ricerca|estrazione> --json
|
|
60
|
-
harma route review --author <harness>:<model> --json # reviewer from another vendor
|
|
61
|
-
```
|
|
62
|
-
Present the top candidates with their reasons (index, cost per task, credit state) and your
|
|
63
|
-
recommendation. Typical split: planning and hard debugging on the strongest model; development
|
|
64
|
-
on a strong model at reasonable cost; review on a different vendor from the author; extraction
|
|
65
|
-
and summaries on the cheapest model above the floor.
|
|
66
35
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
harma
|
|
70
|
-
|
|
36
|
+
```sh
|
|
37
|
+
harma models --json
|
|
38
|
+
harma credits --json
|
|
39
|
+
harma rank --json
|
|
71
40
|
```
|
|
72
|
-
Agent names: lowercase, `[a-z][a-z0-9_-]{0,31}`, unique among open agents (`planner`, `builder`,
|
|
73
|
-
`review-1`). Write a self-contained brief: goal, files, constraints, what "done" means, and how to
|
|
74
|
-
report back (e.g. "write your result to `.harma/out/<name>.md`").
|
|
75
41
|
|
|
76
|
-
|
|
42
|
+
When you report these, mention where the numbers come from:
|
|
43
|
+
|
|
44
|
+
- **Credits**: CodexBar when it's installed, otherwise a budget the user declared in `.harma/config.json` → `budgets.<provider>`, otherwise unknown. Suggest enabling the provider in CodexBar or declaring a budget.
|
|
45
|
+
- **Estimates**: the "stima 7g" figure is local tokens × API list price. For a subscription it's not what the user pays; say so when you quote it.
|
|
46
|
+
- **Scores**: they come from a bundled Artificial Analysis snapshot unless `harma rank --refresh` ran with `AA_API_KEY`. Mention the snapshot date when you rely on it.
|
|
47
|
+
|
|
48
|
+
### 3. Propose models and let the user choose
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
harma route <job> --json
|
|
52
|
+
harma route review --author <harness>:<model> --json
|
|
77
53
|
```
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
54
|
+
|
|
55
|
+
Jobs are `pianificazione`, `sviluppo`, `review`, `debugging`, `ricerca` and `estrazione`; English aliases such as `planning` or `development` also work. Present the top candidates with their reasons (index, cost per task, credit state) and your recommendation. Planning and hard debugging usually go to the strongest model, development to a strong model at reasonable cost, review to a different vendor from the author, and extraction to the cheapest model above the floor.
|
|
56
|
+
|
|
57
|
+
Before the first dispatch, let the user decide which models each job gets. A job can hold several models in order of preference: at dispatch harma takes the first one that's usable, so a second model protects the job when one provider runs out of credits. Pick one way to ask:
|
|
58
|
+
|
|
59
|
+
- **Selection screen**: `harma select --open --wait --json` opens it in a focused herdr tab and returns the saved choices. Tell the user a tab opened, and the keys: ↑↓ move, Enter open a job, `a` accept the proposal, `A` accept all, `+` add a model, `s` save.
|
|
60
|
+
- **In this chat**: ask with your structured-question tool (`AskUserQuestion` in Claude Code), offering the proposal and alternatives from `harma rank`. Then record exactly what they chose:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
harma select --set "sviluppo=codex:gpt-6.2-sol@high|claude:claude-sonnet-5-5@high,review=none" --json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Use `harma select --accept --json` only when the user said to accept all proposals.
|
|
67
|
+
|
|
68
|
+
Never record a choice the user didn't make. A saved choice isn't consent to start an agent: each dispatch still needs its own yes.
|
|
69
|
+
|
|
70
|
+
### 4. Dispatch
|
|
71
|
+
|
|
72
|
+
After the user agrees to a specific dispatch:
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
harma dispatch --name <agent-name> --task-type <job> --prompt-file <brief.md> --yes --json
|
|
81
76
|
```
|
|
82
|
-
Status values come from the terminal backend: `working`, `idle`, `done`, `blocked`, `unknown`,
|
|
83
|
-
`finished`. `blocked` means the agent waits on a question or approval: read it and ask the user;
|
|
84
|
-
never answer an approval dialog on the user's behalf. `idle`/`done` does not prove the task is
|
|
85
|
-
done: read the output and check the work.
|
|
86
77
|
|
|
87
|
-
|
|
78
|
+
With `--task-type` and no `--model`, harma uses the user's list for that job, otherwise the top route candidate. The plan's `why` says which model on the list it took and which it skipped (for example "n.1 … saltato: crediti scarso"). Tell the user when it isn't their first choice. Use `--model <harness>:<model> --effort <level>` only when the user asked for that model.
|
|
79
|
+
|
|
80
|
+
Name agents in lowercase, unique among open agents (`planner`, `builder`, `review-1`). Write a self-contained brief: the goal, the files, the constraints, what "done" means, and how to report back, for example "write your result to `.harma/out/<name>.md`". The agent starts with none of your context, so anything you leave out of the brief it will guess.
|
|
81
|
+
|
|
82
|
+
### 5. Monitor
|
|
83
|
+
|
|
84
|
+
```sh
|
|
85
|
+
harma status --json
|
|
86
|
+
harma read <agent-name> --lines 120
|
|
87
|
+
harma send <agent-name> "<follow-up>" --yes
|
|
88
88
|
```
|
|
89
|
+
|
|
90
|
+
`blocked` means the agent waits on a question or an approval: read it and ask the user. `idle` or `done` doesn't prove the task is finished, so read the output and check the work.
|
|
91
|
+
|
|
92
|
+
### 6. Watch cost
|
|
93
|
+
|
|
94
|
+
```sh
|
|
89
95
|
harma costs --json
|
|
90
96
|
```
|
|
91
|
-
Use `advice` to rebalance: delegate more to providers with `ampio` margin, less to `scarso`,
|
|
92
|
-
nothing to `esaurito` until its reset. Tell the user when you shift work and why.
|
|
93
97
|
|
|
94
|
-
|
|
98
|
+
Use `advice` to rebalance: delegate more to providers with `ampio` credits, less to `scarso`, nothing to `esaurito` until it resets. Tell the user when you shift work and why.
|
|
99
|
+
|
|
100
|
+
### 7. Keep the workspace clean
|
|
101
|
+
|
|
95
102
|
At each step boundary, and before ending your turn on a finished task:
|
|
96
|
-
```
|
|
97
|
-
harma cleanup --dry-run --json # what would close, with session ids
|
|
98
|
-
harma cleanup --json # saves session ids, closes finished agents' tabs/terminals
|
|
99
|
-
```
|
|
100
|
-
harma keeps agents that are `working` or `blocked`, and agents whose session id it cannot find
|
|
101
|
-
(closing them would lose their context). `--force` overrides both; use it only when the user asks.
|
|
102
|
-
When the project's work is over, `harma cleanup --workspace` also closes the herdr workspace
|
|
103
|
-
harma created for it (only once no harma agent is open).
|
|
104
103
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
harma
|
|
108
|
-
harma resume <name> --yes # after consent: reopens it in a new terminal
|
|
104
|
+
```sh
|
|
105
|
+
harma cleanup --dry-run --json
|
|
106
|
+
harma cleanup --json
|
|
109
107
|
```
|
|
110
108
|
|
|
111
|
-
|
|
109
|
+
harma saves each session id, then closes finished agents. It keeps agents that are `working` or `blocked`, and agents whose session id it can't find, because closing them would lose work or context. Use `--force` only when the user asks. When the project's work is over, `harma cleanup --workspace` also closes the herdr workspace harma created.
|
|
112
110
|
|
|
113
|
-
|
|
114
|
-
(`hc`, headless terminals labelled `harma.project=<id>`). `--backend herdr|hc` forces one;
|
|
115
|
-
otherwise harma uses whichever is running, herdr first. If neither is available, `harma doctor`
|
|
116
|
-
says what to install. Do not start, stop or restart a herdr/hc server yourself.
|
|
111
|
+
To continue a closed agent's work with its full context, after consent:
|
|
117
112
|
|
|
118
|
-
|
|
113
|
+
```sh
|
|
114
|
+
harma resume <agent-name> --yes
|
|
115
|
+
```
|
|
119
116
|
|
|
120
|
-
|
|
121
|
-
- `.harma/agents.jsonl` — append-only log: started, session, prompted, closed, resumed.
|
|
122
|
-
- `.harma/cache/` — last inventory, credits, rank (each with `fetched_at`).
|
|
117
|
+
## References
|
|
123
118
|
|
|
124
|
-
|
|
119
|
+
Read these only when you need them:
|
|
125
120
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
Exit code 4 from `dispatch` means the agent started but waits on a dialog (often "trust this
|
|
129
|
-
folder?" in a new directory) and the task was **not** delivered: `harma read <name>`, ask the
|
|
130
|
-
user to answer it in their terminal, then `harma send <name> "<task>" --yes`. Never answer a
|
|
131
|
-
trust or approval dialog yourself.
|
|
121
|
+
- [references/commands.md](references/commands.md): every command and option, exit codes, files and backends
|
|
122
|
+
- [references/troubleshooting.md](references/troubleshooting.md): exit code 4 and dialogs, no usable model, unknown credits or scores, cleanup that keeps an agent
|