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 CHANGED
@@ -1,21 +1,31 @@
1
1
  # Changelog
2
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.
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
- 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.
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 # 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
37
+ npx harma-kit install
38
+ npx harma-kit doctor
28
39
  ```
29
40
 
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`)**.
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
- ## Use it from your agent
43
+ ## Get started
34
44
 
35
- In a project, tell Claude or Codex something like:
45
+ In a project, ask Claude Code or Codex for what you want, in your own words:
36
46
 
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.
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 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
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
- ## 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
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
- ## Maintainers
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
- `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.
72
+ ## Credits
113
73
 
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.
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.
@@ -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.1.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",