samagotchi 0.142.0 → 0.143.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.
Files changed (118) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +66 -7
  3. data/README.md +1 -0
  4. data/docs/architecture.md +13 -6
  5. data/docs/bundle-authoring.md +6 -6
  6. data/docs/bundles.md +1232 -0
  7. data/docs/cli.md +36 -6
  8. data/docs/configuration.md +11 -12
  9. data/docs/context.md +10 -10
  10. data/docs/guardrails.md +7 -9
  11. data/docs/hooks.md +19 -2
  12. data/docs/internals/attached-context.md +2 -3
  13. data/docs/internals/bundles.md +5 -3
  14. data/docs/internals/engine.md +9 -3
  15. data/docs/internals/prompt-caching.md +12 -12
  16. data/docs/internals/web-push.md +1 -1
  17. data/docs/memory.md +2 -2
  18. data/docs/plugins.md +26 -1251
  19. data/docs/sessions.md +2 -2
  20. data/docs/sub-agent.md +6 -6
  21. data/docs/system-one.md +2 -2
  22. data/lib/samagotchi/bundle_command/api_calls.rb +132 -0
  23. data/lib/samagotchi/bundle_command/check.rb +50 -34
  24. data/lib/samagotchi/bundle_command/installed_check.rb +86 -0
  25. data/lib/samagotchi/bundle_command/scaffold.rb +1 -0
  26. data/lib/samagotchi/bundle_settings_check.rb +58 -0
  27. data/lib/samagotchi/bundles/agents-md/manifest.yml +4 -2
  28. data/lib/samagotchi/bundles/agents-md/plugin.rb +1 -1
  29. data/lib/samagotchi/bundles/btw/manifest.yml +4 -2
  30. data/lib/samagotchi/bundles/btw/plugin.rb +1 -1
  31. data/lib/samagotchi/bundles/check-in/manifest.yml +7 -6
  32. data/lib/samagotchi/bundles/check-in/plugin.rb +7 -14
  33. data/lib/samagotchi/bundles/claude-peer/manifest.yml +3 -3
  34. data/lib/samagotchi/bundles/claude-peer/plugin.rb +1 -1
  35. data/lib/samagotchi/bundles/claude-peer/scripts/pair +1 -1
  36. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  37. data/lib/samagotchi/bundles/codex-peer/plugin.rb +1 -1
  38. data/lib/samagotchi/bundles/coordinator/manifest.yml +2 -2
  39. data/lib/samagotchi/bundles/coordinator/plugin.rb +1 -1
  40. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  41. data/lib/samagotchi/bundles/cost-cap/manifest.yml +6 -3
  42. data/lib/samagotchi/bundles/cost-cap/plugin.rb +5 -7
  43. data/lib/samagotchi/bundles/github-pr/manifest.yml +3 -1
  44. data/lib/samagotchi/bundles/known-names/manifest.yml +3 -1
  45. data/lib/samagotchi/bundles/loop-guard/manifest.yml +4 -2
  46. data/lib/samagotchi/bundles/loop-guard/plugin.rb +1 -1
  47. data/lib/samagotchi/bundles/mcp/manifest.yml +4 -2
  48. data/lib/samagotchi/bundles/mcp/plugin.rb +2 -2
  49. data/lib/samagotchi/bundles/ruby/manifest.yml +2 -2
  50. data/lib/samagotchi/bundles/ruby/plugin.rb +1 -1
  51. data/lib/samagotchi/bundles/skills/manifest.yml +4 -2
  52. data/lib/samagotchi/bundles/skills/plugin.rb +1 -1
  53. data/lib/samagotchi/bundles/slow-commands/manifest.yml +4 -2
  54. data/lib/samagotchi/bundles/slow-commands/plugin.rb +1 -1
  55. data/lib/samagotchi/bundles/source-links/manifest.yml +3 -1
  56. data/lib/samagotchi/bundles/system/config_modification_protocol.md +1 -1
  57. data/lib/samagotchi/bundles/system/manifest.yml +3 -3
  58. data/lib/samagotchi/bundles/system/self_map.md +2 -2
  59. data/lib/samagotchi/bundles/work-cap/manifest.yml +6 -3
  60. data/lib/samagotchi/bundles/work-cap/plugin.rb +11 -13
  61. data/lib/samagotchi/context_candidate_choice.rb +12 -3
  62. data/lib/samagotchi/context_candidates.rb +4 -1
  63. data/lib/samagotchi/context_candidates_log.rb +11 -0
  64. data/lib/samagotchi/context_status.rb +1 -2
  65. data/lib/samagotchi/engine.rb +33 -68
  66. data/lib/samagotchi/extension_load.rb +8 -2
  67. data/lib/samagotchi/hook_routes.rb +37 -2
  68. data/lib/samagotchi/hooks/bundle_loader.rb +20 -4
  69. data/lib/samagotchi/hooks/registry.rb +23 -5
  70. data/lib/samagotchi/host_model.rb +3 -3
  71. data/lib/samagotchi/host_registry.rb +14 -7
  72. data/lib/samagotchi/kernel_loop.rb +7 -2
  73. data/lib/samagotchi/llm/chat_loop.rb +5 -0
  74. data/lib/samagotchi/llm/stray_tool_call.rb +23 -16
  75. data/lib/samagotchi/memory_bundle/builder.rb +4 -2
  76. data/lib/samagotchi/memory_bundle/installed_bundle.rb +9 -2
  77. data/lib/samagotchi/memory_bundle/installed_copy.rb +92 -0
  78. data/lib/samagotchi/memory_bundle/installer.rb +2 -0
  79. data/lib/samagotchi/memory_bundle/manifest.rb +23 -13
  80. data/lib/samagotchi/memory_bundle/provenance.rb +4 -1
  81. data/lib/samagotchi/memory_bundle/shipped_update.rb +13 -1
  82. data/lib/samagotchi/model_catalog.rb +3 -2
  83. data/lib/samagotchi/models_command.rb +1 -1
  84. data/lib/samagotchi/plugin/api.rb +14 -11
  85. data/lib/samagotchi/plugin/context.rb +10 -0
  86. data/lib/samagotchi/plugin/loader.rb +4 -2
  87. data/lib/samagotchi/plugin/peer.rb +17 -22
  88. data/lib/samagotchi/plugin_session_state.rb +32 -5
  89. data/lib/samagotchi/prompt_warmup.rb +1 -9
  90. data/lib/samagotchi/session_access/local.rb +1 -1
  91. data/lib/samagotchi/session_access/remote.rb +3 -3
  92. data/lib/samagotchi/session_archive_command.rb +3 -3
  93. data/lib/samagotchi/session_commands.rb +4 -4
  94. data/lib/samagotchi/session_config.rb +9 -3
  95. data/lib/samagotchi/session_continue.rb +1 -1
  96. data/lib/samagotchi/session_manager.rb +15 -6
  97. data/lib/samagotchi/system_one/judgments.rb +8 -25
  98. data/lib/samagotchi/system_one/log.rb +21 -0
  99. data/lib/samagotchi/system_one/recording.rb +1 -1
  100. data/lib/samagotchi/terminal_ui/attach_link.rb +2 -2
  101. data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb +1 -1
  102. data/lib/samagotchi/terminal_ui/attached_loop.rb +1 -1
  103. data/lib/samagotchi/terminal_ui/local_link.rb +1 -1
  104. data/lib/samagotchi/terminal_ui/remote_link.rb +1 -2
  105. data/lib/samagotchi/testing/judgments.rb +0 -9
  106. data/lib/samagotchi/update_command.rb +49 -16
  107. data/lib/samagotchi/version.rb +1 -1
  108. data/lib/samagotchi/web/app.rb +1 -0
  109. data/lib/samagotchi/web/auto_update.rb +79 -49
  110. data/lib/samagotchi/web/auto_update_record.rb +59 -0
  111. data/lib/samagotchi/web/public/app.js +8 -4
  112. data/lib/samagotchi/web/public/hash_intent.js +24 -0
  113. data/lib/samagotchi/web/public/index.html +3 -1
  114. data/lib/samagotchi/web/public/revise_stack.js +14 -5
  115. data/lib/samagotchi/web/session_control.rb +3 -3
  116. data/lib/samagotchi/web/update_check.rb +7 -6
  117. data/lib/samagotchi/web/update_ops.rb +80 -25
  118. metadata +8 -1
data/docs/plugins.md CHANGED
@@ -5,8 +5,8 @@ tools, hooks and background setup to every session. Its hooks are ordinary
5
5
  bundle hooks ([hooks.md](hooks.md)). Its commands and tools work like chi's
6
6
  own.
7
7
 
8
- This is the first version of the plugin API. More of it comes later: see
9
- [Not yet](#not-yet).
8
+ This page is the plugin API and its reference. What each shipped bundle does for a user (btw, mcp, cost-cap,
9
+ claude-peer…) is in [bundles.md](bundles.md).
10
10
 
11
11
  Writing a bundle? Start with [bundle-authoring.md](bundle-authoring.md): the `chi bundle new` / `test` / `check`
12
12
  loop, the event shapes, the kit, the pitfalls.
@@ -33,6 +33,9 @@ requires_chi: ">= 0.1.28" # optional: a gem-style requirement (">= 0.1.28, <
33
33
  # to the chi being released (docs/releasing.md)
34
34
  session_settings: [cap] # optional: the settings a session may set (chi --set my-bundle.cap=3);
35
35
  # {cap: number} types them: number (or off), boolean, string or any
36
+ settings: [greeting] # optional: the keys config.yml bundles: my-bundle: may have, written the same way
37
+ # (any also takes a mapping or a list). With it, another key warns; a session
38
+ # setting needn't be listed twice
36
39
  needs: [gh] # optional: outside commands it relies on (see memory.md#bundles-that-need-outside-commands)
37
40
  ```
38
41
 
@@ -79,6 +82,10 @@ Settings work as they do for hooks ([hooks.md](hooks.md#settings)). An
79
82
  sees a session's own `--set` values. A value a session may set is read from `ctx.settings` in the handler or
80
83
  command that uses it (see [Per-session settings](#per-session-settings)).
81
84
 
85
+ A config.yml `bundles:` name that no installed bundle has shows a warning when a session starts, in every UI (`config>`…);
86
+ so does a key or a value's type the manifest's `settings:` rules out. It warns only: the session goes on, and a
87
+ bundle with no `settings:` has its keys left alone. `chi bundle check --set` warns the same way (`settings`).
88
+
82
89
  ## The API: `register(chi)`
83
90
 
84
91
  ### `chi.command(name, description, anytime: false) { |args, ctx| … }`
@@ -465,7 +472,8 @@ attaches refs to it ([Refs on the answer](hooks.md#refs-on-the-answer-display-on
465
472
  `:question_asked`, `event[:refs]` attaches refs to the reply that asks a question
466
473
  ([Refs on a question](hooks.md#refs-on-a-question-display-only)). Its label is
467
474
  `plugin.rb (bundle my-bundle)`. The block may take only the event. If it
468
- raises, the error is logged and the hook is skipped.
475
+ raises, the error is logged and the hook is skipped; the first failure per
476
+ event in a worker also shows once in every UI (`plugins> plugin.rb (bundle x) before_turn hook failed (…)`).
469
477
 
470
478
  To act from the block, use `ctx`: `ctx.notify`, `ctx.ask_user`,
471
479
  `ctx.steer`, `ctx.stop_turn`, `ctx.stop_generation`. Inside the block they
@@ -509,7 +517,7 @@ end
509
517
  ```
510
518
 
511
519
  loop-guard's thinking watch is built on this ([The loop-guard
512
- bundle](#the-loop-guard-bundle)).
520
+ bundle](bundles.md#the-loop-guard-bundle)).
513
521
 
514
522
  ### `chi.service(name, eager: false) { |svc| … }`
515
523
 
@@ -547,7 +555,7 @@ end
547
555
  - `kill -9` runs nothing: a child process is orphaned then. Most stdio
548
556
  servers leave when their stdin closes, which it does as chi's process
549
557
  ends. The mcp bundle also stops a server that doesn't (see
550
- [The mcp bundle](#the-mcp-bundle), Stop).
558
+ [The mcp bundle](bundles.md#the-mcp-bundle), Stop).
551
559
 
552
560
  ### `chi.init(label, provides_tools: false, quiet: false, timeout: nil, failed: nil) { |ctx| … }`
553
561
 
@@ -787,7 +795,7 @@ file can't make itself a peer's, and uninstalling the bundle ends it.
787
795
  Subclasses of `Samagotchi::Plugin::Peer` (below) declare their `OUTBOX`
788
796
  source. Needs chi 0.67.0 (guard it with `chi.respond_to?(:peer_source)`).
789
797
 
790
- ### `chi.judgment(name, questions:, positive: nil, negative: nil, shared_host: :skip)`
798
+ ### `chi.judgment(name, questions:, positive: nil, negative: nil)`
791
799
 
792
800
  A cheap System 1 question this bundle asks with `ctx.judge` or `ctx.judge_later`: see
793
801
  [Judgments](#judgments-chijudgment-and-ctxjudge).
@@ -836,7 +844,8 @@ full label, `plugin.rb (bundle my-bundle)`.
836
844
  | `ctx.usage` | the session's work so far, read now, as a frozen value: `turns` (finished ones and the running one), `tool_calls` and `tool_calls_by_tool` (every call, running ones included; canonical names: an alias counts under its tool, a `call_tool` call under the inner tool), `steps` (the loop rounds that dispatched tools, `/stats`' iterations) and `active_ms` (`active_minutes` too): work time, the generations' time plus the finished tool calls' time, never the waits between them (a question, an approval, the user's answer to `ask_user_question`), with `tool_ms_by_tool` its tool part by tool, so a waiting tool's time (`task_wait`) can be left out. Its counts are the ones `/stats` and `chi sessions stats` show, earlier workers' included. Use its methods, not its class. Needs chi 0.100.0 (guard it with `ctx.respond_to?(:usage)`) |
837
845
  | `ctx.turn_author` | who wrote the running turn when it isn't the session's owner: a participant's `"p:<id>"` (`chi share`); nil for the owner's turns and between turns. Every hook event of such a turn carries the same as `author:`. The handler runs with the owner's power whatever the author ([hooks](hooks.md#participants-turns)). Needs chi 0.105.0 (guard it with `ctx.respond_to?(:turn_author)`) |
838
846
  | `ctx.settings` | the bundle's settings, frozen: config.yml's `bundles: <bundle>:` with the session's own `--set` values laid over it ([Per-session settings](#per-session-settings)); the config alone until the session is bound (in `register` and `chi.ctx`) |
839
- | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use. A session's own state goes in `sessions/<id>.json` or `sessions/<id>/` there: chi removes it when the session is deleted, discarded or pruned |
847
+ | `ctx.data_dir` | `$XDG_STATE_HOME/samagotchi/plugins/<bundle>/`, created on first use: what the bundle keeps across sessions |
848
+ | `ctx.session_dir` | this session's own folder there, created on use, read now; nil with no session yet. chi removes it when the session is deleted, discarded or pruned, so don't build the path yourself. A `sessions/<id>.json` an older version of your bundle kept moves in as `state.json` (chi still removes one left there). Needs chi newer than 0.142.0 |
840
849
  | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
841
850
  | `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn. An entry may carry `at`, when it happened (docs/sessions.md, Message times) |
842
851
  | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
@@ -1000,7 +1009,7 @@ gives a bundle no new power. Needs chi 0.142.0 (guard it with `chi.respond_to?(:
1000
1009
  ```ruby
1001
1010
  def register(chi)
1002
1011
  chi.judgment "progress", questions: { "progress" => { type: "noul", instructions: "Is this turn still making progress?" } },
1003
- positive: "keep_going", negative: "stop", shared_host: :skip
1012
+ positive: "keep_going", negative: "stop"
1004
1013
 
1005
1014
  chi.on(:after_tool_call) do |_event, ctx|
1006
1015
  @run = ctx.judge_later("progress", state: { prompt: @prompt, calls: @calls }) do |result|
@@ -1031,10 +1040,6 @@ name has a capital or a dot fails to load on this call. `approvals`, `context`,
1031
1040
  session. A plain map is checked when declared, a bad one failing the plugin's load; a callable's result at each ask, raising there.
1032
1041
  - `positive:` and `negative:` name the label values that say the answer was right and wrong (a word or a list). They
1033
1042
  are saved in each run for a later comparison, and don't limit `label`.
1034
- - `shared_host:` says what to do while a turn runs on the same local server (the same `hosts:` entry or the same URL
1035
- root, and not a remote one), where an ask evicts the turn's cached prompt: `:skip`, the default, saves the run with `asked: false`, so a
1036
- later replay can answer it; `:ask` asks anyway. Between turns and on a remote host, it asks either way. A turn's hooks count as in the
1037
- turn, `:after_turn` and `:session_end` too: an ask there would still evict the prefix the next turn wants.
1038
1043
 
1039
1044
  `ctx.judge(name, state:)` asks and waits, at most `system_one.timeout_ms`. `name` is as declared, without the bundle.
1040
1045
  `state:` is a String, Hash or Array: what the question is about, sent to the System 1 host and saved as sent (bytes that
@@ -1057,7 +1062,6 @@ anything that goes wrong on the way:**
1057
1062
  | `:no_session` | no session bound yet | no |
1058
1063
  | `:failed` | the host couldn't be reached, timed out, refused, or sent something unusable | yes, with `failure` |
1059
1064
  | `:cancelled` | the turn was stopped during the ask | yes, with `failure: "cancelled"` |
1060
- | `:shared_host` | `shared_host: :skip`, and a turn is running on it | yes, `asked: false` |
1061
1065
  | `:busy` | `judge_later` only: this judgment's last one still runs | yes, `asked: false` |
1062
1066
 
1063
1067
  An undeclared name or a bad `state:` (not a String, Hash or Array, or nested too deep) raises `ArgumentError`, as `ask_model` does for a bad model, and so does `ctx.judge` in a
@@ -1308,7 +1312,7 @@ gets a note when its text changes.
1308
1312
  `Samagotchi::Plugin::AttachedContext::Error` with the reason (no session
1309
1313
  yet, no provider for the URL, a bad name).
1310
1314
 
1311
- The [github-pr bundle](#the-github-pr-bundle) proposes the branch's PR from
1315
+ The [github-pr bundle](bundles.md#the-github-pr-bundle) proposes the branch's PR from
1312
1316
  a quiet `chi.init` task.
1313
1317
 
1314
1318
  ### Context providers in the manifest
@@ -1348,6 +1352,9 @@ are the rest of the surface they may use. A change to any of them gets a
1348
1352
  CHANGELOG line and bumps the shipped bundles that use it. Anything else under
1349
1353
  `Samagotchi::` is internal.
1350
1354
 
1355
+ **New API ships with its first caller:** a `chi.*` or `ctx.*` method arrives in the same change as a shipped bundle
1356
+ that calls it, or for a real external bundle that does. No method on the chance that someone will want it.
1357
+
1351
1358
  **Stable**
1352
1359
 
1353
1360
  1. `Samagotchi::Plugin::Api` / `chi.*` and `ctx` as documented above (`ctx.cost`'s and `ctx.usage`'s values by their methods), including
@@ -1361,8 +1368,8 @@ CHANGELOG line and bumps the shipped bundles that use it. Anything else under
1361
1368
  `check_hint!`, `paired_lines`, `transport_line`, `peer_dir` and
1362
1369
  `setup_paragraph` (optionally `skill_substitutions`), and sets `NAME`,
1363
1370
  `APP`, `COMMAND`, `USAGE`, `OUTBOX` and `SCRIPTS_DIRS`. These constants are
1364
- read as `self.class::X`. See the [claude-peer](#the-claude-peer-bundle) and
1365
- [codex-peer](#the-codex-peer-bundle) bundles.
1371
+ read as `self.class::X`. See the [claude-peer](bundles.md#the-claude-peer-bundle) and
1372
+ [codex-peer](bundles.md#the-codex-peer-bundle) bundles.
1366
1373
  3. `Samagotchi::Tools::ToolIndex::Tool` and `Samagotchi::Tools::ToolIndex::Group`
1367
1374
  values, `Samagotchi::Tools::ToolIndex.schema_note` and
1368
1375
  `Samagotchi::Tools::ToolIndex.spec_tokens` (used by the mcp bundle).
@@ -1382,12 +1389,10 @@ fails on a reference in neither (docs/testing.md).
1382
1389
  **Used by shipped bundles today, but internal** (may change without notice; a
1383
1390
  bundle that needs one should ask for an API instead):
1384
1391
 
1385
- - `Samagotchi::Tools::MemoryRead.memories_dir`, `Samagotchi::MemoryPaths.scope_dir`,
1386
- `Samagotchi::ConfigFile.global_path` and
1387
- `Samagotchi::Config.validate_yaml_sections`.
1392
+ - `Samagotchi::Tools::MemoryRead.memories_dir` and `Samagotchi::MemoryPaths.scope_dir`.
1388
1393
  - `Samagotchi::Ref` / `Samagotchi::RefAction` constants and
1389
1394
  `Samagotchi::TokenUsage::CHARS_PER_TOKEN`.
1390
- - `Samagotchi::ProcessGroup.stop`, `Samagotchi::Guardrails::ShellLex` and
1395
+ - `Samagotchi::ProcessGroup.stop`, `Samagotchi::ProjectEnv`, `Samagotchi::Guardrails::ShellLex` and
1391
1396
  `Samagotchi::Guardrails::GitInfo`.
1392
1397
  - `Samagotchi::Tools::Execute.const_get` reflection.
1393
1398
 
@@ -1418,7 +1423,7 @@ bundle.questions.last.effects # an ask_user's tags as
1418
1423
  bundle.answer({ selected: "yes" }) # the next ask_user's answer
1419
1424
  bundle.model_answers << "a summary" # the next ask_model's answer
1420
1425
  bundle.judgments.answer("progress", noul: 0.9) # ctx.judge's answer from now on; question: for one of several, or a block given the state
1421
- bundle.judgments.fail("progress") # a failed backend; mode("progress", "off"), no_host("progress"), shared_host_busy too
1426
+ bundle.judgments.fail("progress") # a failed backend; mode("progress", "off"), no_host("progress") too
1422
1427
  bundle.judgments.wait # judge_later's threads and blocks are done
1423
1428
  bundle.judgments.asks.last.state # the asks that reached System 1: name, state, questions, cancel
1424
1429
  bundle.judgments.runs("progress").last["asked"] # the runs as chi saves them; labels("progress"), acted_lines("progress") too
@@ -1506,1199 +1511,6 @@ docs/testing.md). **Minitest:** `require "samagotchi/testing/minitest"` and subc
1506
1511
  writes a test to start from. `chi bundle try PATH -p TEXT` runs it against a real model for one turn
1507
1512
  ([cli.md](cli.md#trying-a-bundle)), and `chi bundle install --dev PATH` links it into your own sessions.
1508
1513
 
1509
- ## The btw bundle
1510
-
1511
- `chi bundle install btw` (or the `dev` profile) installs the bundle shipped with chi. It is written
1512
- only against this API (`lib/samagotchi/bundles/btw/plugin.rb`).
1513
-
1514
- - `/btw <question>` asks the session's model a side question about the
1515
- conversation, even while a turn runs. A card `btw: <question>` shows
1516
- "thinking…" at once, and the same card then shows the answer. Nothing else
1517
- sees the answer.
1518
- - The card's **Keep as session** runs `/btw keep <id>`. It forks the
1519
- conversation, the question and the answer into an idle child session, and
1520
- shows a card `kept as <id>`.
1521
- - The last 10 answers can be kept, while the session's worker (or REPL)
1522
- runs. After that, or after a restart, `keep` says expired.
1523
- - In the REPL, a question asked during a turn is about the conversation
1524
- before that turn, and the card says so. In a worker it includes the turn
1525
- so far.
1526
- - Settings: `bundles: btw: {max_tokens: 1024, timeout: 120}`.
1527
- - It ships no memory, so it adds no line to the prompt's memory index. Its
1528
- 0.1.0 shipped `btw.md` as one, and `chi bundle upgrade btw` leaves that file
1529
- (and its index line) behind. Drop it with `chi bundle uninstall btw`, then
1530
- `chi bundle install btw`. After an upgrade already ran, delete
1531
- `$XDG_CONFIG_HOME/samagotchi/memories/btw.md` (`$XDG_CONFIG_HOME` defaults to
1532
- `~/.config`) and its `**btw**` line in `index.md` there by hand.
1533
-
1534
- ## The mcp bundle
1535
-
1536
- `chi bundle install mcp` (or the `dev` profile) installs the bundle shipped with chi. It is written
1537
- only against this API (`lib/samagotchi/bundles/mcp/plugin.rb`), and gives
1538
- the model the tools of [MCP](https://modelcontextprotocol.io) servers. It
1539
- has no memory file, and the servers' tools aren't declared to the model one
1540
- by one: the bundle publishes them into chi's tool index
1541
- ([chi.tool_source](#chitool_sourcecall-acts_as-label-wait-prefix), a group
1542
- per server), and the model has its two tools, `find_tools` and `call_tool` (~250 tokens in
1543
- every request plus a line per server, whatever the servers have; `/mcp`
1544
- says how many). On `api: anthropic` each tool also goes out deferred as
1545
- `mcp_<server>_<tool>`, so a `find_tools` hit loads it and the model calls it
1546
- by that name, as `call_tool` would run it. Stdio servers only, for now.
1547
-
1548
- ```yaml
1549
- # config.yml
1550
- bundles:
1551
- mcp:
1552
- timeout: 60 # seconds per tool call (default 60)
1553
- startup_timeout: 10 # seconds for initialize and tools/list (default 10)
1554
- servers:
1555
- everything:
1556
- command: [npx, -y, "@modelcontextprotocol/server-everything"]
1557
- files:
1558
- command: [npx, -y, "@modelcontextprotocol/server-filesystem", ~/scratch]
1559
- env: {NODE_OPTIONS: "--no-warnings"} # added to chi's environment
1560
- cwd: ~/scratch # default: where chi runs
1561
- tools: [read_*, list_directory] # optional: only these (globs)
1562
- description: files in ~/scratch # optional: its line in find_tools
1563
- timeout: 120 # optional: this server's per-call timeout
1564
- chrome:
1565
- command: [npx, -y, "chrome-devtools-mcp@latest", --slim, --headless]
1566
- attach_image_paths: true # the default; false leaves a path as text
1567
- start: lazy # the default; eager: start it with every session
1568
- ```
1569
-
1570
- - **Start: from a cache, on the first call.** A server's `tools/list` is
1571
- saved in the bundle's data dir (`$XDG_STATE_HOME/samagotchi/plugins/mcp/
1572
- tools-<server>.json`), keyed by a digest of its `command`, `env` (names
1573
- and values: only the digest is stored) and `cwd`. A session with a saved
1574
- list can search its tools at once and **doesn't start the server**: the
1575
- first call of one of its tools does (the call's row shows the wait). So a
1576
- session that never uses MCP spawns nothing, and a new session opens without
1577
- waiting for `npx`. If the live list differs from the saved one, the saved
1578
- one is replaced, and so is what a search finds. The model's tools never
1579
- change, so the prompt cache keeps. The saved file also keeps the first
1580
- sentence of the server's `instructions` (from `initialize`), for its line
1581
- in `find_tools`.
1582
- - **The first run** (no saved list, or the config changed) starts the
1583
- server in an [init task](#chiinitlabel-provides_tools-false-quiet-false-timeout-nil-failed-nil--ctx--):
1584
- every UI shows `Starting MCP server x (first run, saving its tools)`, and
1585
- a turn sent meanwhile waits for its tools. A server that doesn't start,
1586
- answer or list its tools within `startup_timeout` (each step) is a warn
1587
- card, `…: failed`, and its calls fail until chi restarts. The rest of chi
1588
- works as usual.
1589
- - **Freshness.** A saved list older than a day is still used, and a quiet
1590
- background task lists the tools again with a server of its own (then
1591
- stops it), saves them, and replaces the searched ones if they changed.
1592
- One worker does it at a time.
1593
- - **A server that says its tools changed** (`notifications/tools/list_changed`)
1594
- is asked for its `tools/list` again; the saved list and the searched tools
1595
- are replaced.
1596
- - **A cached server that doesn't start** (the command is gone, it crashes)
1597
- fails that call with `Error: MCP server x didn't start: …` and one notice;
1598
- later calls answer the same at once until chi restarts, and a search shows
1599
- its tools as `(failed: …)`. The saved list stays: the next session tries
1600
- again.
1601
- - **`start: eager`** on a server starts it with every session (in an init
1602
- task, after the Bridge is up), even when that session's toolkit does not
1603
- reach its group. A first-run init task still blocks the first turn until
1604
- it finishes, even for an unreached group. A stale-cache refresh likewise
1605
- starts its short-lived server regardless of the toolkit. Switching away
1606
- from a group refuses its calls without starting a lazy cached server, and
1607
- does not stop a server already running; switching back reuses it.
1608
- - **`npx -y …@latest` checks the npm registry on every start** (~3.4 s for
1609
- `chrome-devtools-mcp`, against ~0.9 s for the installed binary). The cache
1610
- hides it from new sessions, but not from the first call. For a faster first
1611
- call, install the server once and run it directly:
1612
-
1613
- ```yaml
1614
- chrome:
1615
- command: [chrome-devtools-mcp, --slim, --headless] # after npm i -g chrome-devtools-mcp
1616
- ```
1617
-
1618
- - **Tools: search, then call.** The servers' tools are kept in chi's tool index;
1619
- the model has two fixed tools:
1620
- - `find_tools(query, group?)` searches it by keywords over the
1621
- server's name, the tool's name and its description, and answers up to 5
1622
- tools, each with its name `<server>/<tool>`, its description and its
1623
- whole `inputSchema`. A word counts more the fewer tools have it (a word
1624
- most of a browser server's tools share, "page", counts little), and
1625
- three times as much in a name as in a description. An empty query (and
1626
- a search with no match) lists every server's tool names, without
1627
- schemas. A tool whose `inputSchema` (or a property's schema) isn't an
1628
- object shows
1629
- `(bad schema)` (and is said once, as a notice), a failed server's tools
1630
- `(failed: …)`, a first-run server still starting `(starting, try
1631
- again)`. Its description names each server on one line, never its
1632
- tools: the server's `description:`, else the first sentence of its
1633
- `instructions`, and how many tools it has (`- chrome (26 tools)` with
1634
- neither: tool names there get called blind, without a search; a first
1635
- run's server is just its name until the next session).
1636
- - `call_tool(tool, args)` calls one: `tool` is `<server>/<tool>`, and
1637
- `mcp_<server>_<tool>` works too (looked up, not parsed). Two tools whose
1638
- `mcp_<server>_<tool>` comes out the same (servers `git-hub` and
1639
- `git_hub`, names alike up to the 48-character cut) are both refused,
1640
- since guardrail rules and approvals couldn't tell them apart: a search
1641
- and `/mcp` mark them `(name clash with …)`, and there is one notice.
1642
- `args` are typed by the tool's
1643
- `inputSchema` (numbers and booleans given as text, JSON text for an
1644
- object). A name it doesn't know answers the closest ones (`Error: no
1645
- tool chrome/open_url. Closest: chrome/new_page, …`). Its row shows
1646
- `mcp chrome/take_screenshot fullPage=true`.
1647
- - A tool turn takes a few more steps than when every tool was declared
1648
- (the P1 spike: about 1.5 more on a 30-tool server), and each request is
1649
- smaller (about half there).
1650
- - **Calls.** A call is `tools/call`. The text blocks of the answer are joined;
1651
- audio or a resource without text is a short placeholder
1652
- (`[audio: audio/wav]`). `isError` makes it `Error: …`; it, a JSON-RPC
1653
- error and `args` that aren't an object end with the tool's schema
1654
- (`chrome/click's inputSchema: {…}`), so a call made without a search can
1655
- be fixed on the next step. A call that takes longer than the timeout is
1656
- an `Error:`, and a cancelled turn stops the wait; both send
1657
- `notifications/cancelled` to the server.
1658
- - **Images.** An `image` block goes to the model as a picture
1659
- ([Returning images](#returning-images): at most 4 per call, a line
1660
- instead when the model can't see images). Its place in the text is a line,
1661
- `[image 1: image/png, attached]`, so the model knows the order. A text
1662
- block that is **the absolute path of an image file** is attached too
1663
- (`[image 1: screenshot.png, attached]` after the text), and so is an
1664
- absolute path ending in `.png`, `.jpg`, `.jpeg`, `.gif` or `.webp` inside
1665
- a sentence (`Saved screenshot to /tmp/shot.png.`; such a path can't hold a
1666
- space). Either way only when the file is an image by its bytes and is
1667
- under the system temp dir or the server's `cwd`: a server's text can't
1668
- pull in any image on disk. `chrome-devtools-mcp --slim` answers
1669
- `screenshot` that way; without `--slim`, `take_screenshot` returns an image
1670
- block. `attach_image_paths: false` on a server leaves such paths as text.
1671
- - **A server that exits** fails the call it was on with `Error: MCP server
1672
- x is not running (…)`, and there is one notice. Its next call starts it
1673
- again (its tools stay), up to 3 times a session; after the third restart
1674
- the notice says so, and its calls fail at once until chi restarts (a new
1675
- session, or the worker's next start).
1676
- - **Stop.** The servers stop with chi ([Shutdown](#shutdown)): stdin is
1677
- closed, then TERM and KILL go to the server's process group. A chi
1678
- killed with `kill -9` (or crashing past Ruby) stops nothing itself; a
1679
- server that ignores its stdin's EOF would live on then. So each server's
1680
- group also holds a watchdog, a `/bin/sh` waiting on a pipe only chi
1681
- holds: when that pipe closes without chi letting it go, it gives the
1682
- server a second, then TERMs and KILLs its group (the server's helpers
1683
- too). A server that leaves its group (`setsid`) is out of its reach.
1684
- - **`/mcp`** (anytime) shows a card with the servers, their state (cached
1685
- (not started), running with its pid, failed with its count, stopped) and
1686
- their tools as `<server>/<tool>`, the name `call_tool` takes.
1687
- A cached or running server's line says roughly how many tokens its tool
1688
- definitions take (`~4,232 tokens`), which only a search's answer carries
1689
- now; the last line says what every request carries (`find_tools` and
1690
- `call_tool`) and totals the servers'. It is an estimate:
1691
- the definitions' JSON as the chat API gets it (`api: openai`), divided by
1692
- 4. The native prompts (Gemma, Qwen) render a flatter schema, so there they
1693
- take less. The log records each server's estimate when it changes
1694
- (`mcp_tools_estimated`).
1695
- - The server's stderr goes to the debug log (`plugins` records, bundle=mcp).
1696
- - **Guardrails.** A rule's `tool:` can be a glob, so one rule covers every
1697
- MCP tool (a search is `find_tools`, outside `mcp_*`, so it isn't
1698
- asked about):
1699
-
1700
- ```yaml
1701
- guardrails:
1702
- rules:
1703
- - id: mcp-ask
1704
- tool: "mcp_*"
1705
- verdict: ask
1706
- reason: an MCP server's tool
1707
- ```
1708
-
1709
- `call_tool`'s `targets:` act as the tool it calls, by its
1710
- `mcp_<server>_<tool>` name ([acts_as:](#guardrails)), so `tool:
1711
- "mcp_github_*"` or `tool: mcp_github_merge_pull_request` match a
1712
- `call_tool` to it, as they matched the tool when it was declared by that
1713
- name. A call made before the server's tools are known (a first run
1714
- still starting) is matched by the name the model gave, so the rule fires
1715
- before the call waits; if the tool it then finds isn't that one, the
1716
- call is refused. The question shows the inner arguments under `<server>: <tool>`
1717
- (`everything: get_sum: a=20 b=22`), and "Allow this call for the
1718
- session" (or in this repo) allows that tool with those arguments only.
1719
- (Approvals stored before 0.6.0, under the old name, don't carry over, nor
1720
- ones stored before 0.7.0 under `mcp_call`: each MCP tool is asked about once more.)
1721
- Two things see `call_tool`, not the MCP tool: hooks (a `before_tool_call`
1722
- event's `tool:` is `"call_tool"`, the tool in its args; a built-in reached
1723
- through `call_tool` is the exception, it fires as that built-in), and loop-guard's
1724
- `ignore_tools` (`call_tool` ignores every MCP call; calls to different
1725
- tools, or with different args, stay distinct, since the tool is in the
1726
- args).
1727
-
1728
- ## The loop-guard bundle
1729
-
1730
- `chi bundle install loop-guard` installs the bundle shipped with chi (`chi
1731
- bootstrap` installs it with the `core` profile). It is
1732
- written only against this API (`lib/samagotchi/bundles/loop-guard/plugin.rb`),
1733
- with `chi.on` hooks, and has no memory file. It guards two kinds of loop:
1734
- repeated tool calls (below) and [thinking that repeats
1735
- itself](#thinking-that-repeats-itself).
1736
-
1737
- A local model can run the same tool call again and again in one turn: each
1738
- step's thinking starts over, so it never notices it already tried. (A real
1739
- one ran `find . -name 'config.yml'` ten times, getting nothing each time.)
1740
- loop-guard breaks that:
1741
-
1742
- - A call is keyed by its tool and its arguments (whitespace collapsed), and
1743
- its result by a hash of the output. When a call has already returned the
1744
- same result `deny_after` times this turn (default 2), the next identical
1745
- call is **denied** with advice, so the 3rd one is caught:
1746
-
1747
- ```
1748
- [execute] Error: denied by guardrail (bundle loop-guard): repeated call. The user was not asked. You already ran this exact call 2 times this turn and it returned the same result each time (exit: 0 (no output)). Don't repeat it. Try a different approach, or tell the user what you're stuck on.
1749
- ```
1750
-
1751
- The user sees one line per call per turn: `loop-guard> loop: execute find
1752
- . -name 'config.yml' 2>/dev/null repeated, denied`.
1753
- - At the `stop_after`-th deny in a turn (default 4) the turn is **stopped**
1754
- (core's own "stopped" notice), and a card lists the repeated calls, so the
1755
- user can say what to try instead.
1756
- - A denied call has no result: a deny (loop-guard's, known-names', a rule's)
1757
- never counts as the call's result, so the deny sticks.
1758
- - The counts are per turn, and a count is the turn's total, not a run of
1759
- consecutive repeats: the loop usually has other calls in between. A new
1760
- turn (a prompt, a continue, a reminder) starts from zero, since a new user
1761
- message can make an old call right again. A steering message merged into
1762
- a running turn doesn't reset them.
1763
- - The polling tools, where repeating is the point, are ignored.
1764
-
1765
- ```yaml
1766
- # config.yml
1767
- bundles:
1768
- loop-guard:
1769
- deny_after: 2 # same call, same result this many times: deny the next one
1770
- stop_after: 4 # stop the turn at this many denies
1771
- ignore_tools: [task_wait, task_get, delegate_result, list_sessions, list_reminders, context_read, forget_outputs]
1772
- mode: deny # deny | notify: notify only warns, once per call per turn
1773
- ```
1774
-
1775
- Its hooks run at the default priority (100), after known-names (50), so in
1776
- known-names' `correct` mode loop-guard keys the corrected call.
1777
-
1778
- ### Thinking that repeats itself
1779
-
1780
- A model can also go in circles inside one generation: its thinking says the
1781
- same few sentences again and again ("Wait, let me check once more…") for
1782
- minutes, until the provider's output cap ends it with no answer. loop-guard
1783
- watches the thinking while it streams ([Watching the
1784
- stream](hooks.md#watching-the-stream)) and cuts it:
1785
-
1786
- - The thinking is cut into sentences. Two sentences of `min_words` or more
1787
- count as the same when their words and word pairs mostly match
1788
- (`similarity`), so a reworded round ("Hmm, …", a synonym, a swapped
1789
- clause) still counts.
1790
- - A loop is a cycle of 1 to `max_period` sentences seen `repeats` times in a
1791
- row, over at least `min_span_sentences` sentences and `min_span_chars`
1792
- chars; or one sentence `max_same` times anywhere in the generation. One
1793
- sentence over and over must be near-identical (`similarity` + 0.4), and a
1794
- longer cycle must hold different sentences: a list of templated sentences
1795
- ("Now I need to open the file <path> and …" for 14 paths) is no loop.
1796
- - Short sentences (under `min_words`) are a loop of their own when
1797
- `short_run` of them come in a row with at most `short_distinct` different
1798
- ones among them ("I'll write it. Go. OK. Writing. Go. OK."). Normal
1799
- thinking has short sentences too ("Hmm.", "Fine."), but spread out or all
1800
- different (code lines); a longer sentence ends the run, and lines inside a
1801
- ```` ``` ```` code block don't count.
1802
- - Any `window_sentences` sentences in a row, short or long, holding at most
1803
- `window_distinct` different ones are a loop too: a cycle of 7 or 8 short
1804
- sentences, or one where a longer sentence ("I'll write the spec file
1805
- now.") keeps ending the short run. Real thinking holds 40 or more
1806
- different sentences in any 48; DeepSeek's write loops hold 4 to 9.
1807
- - Nothing triggers before `min_chars` of thinking. The watch sees a loop
1808
- within one batch (2000 chars, or a second) of its third cycle.
1809
-
1810
- What happens (`action: retry`, the default):
1811
-
1812
- 1. The first loop in a turn: the generation is cut and the model asked
1813
- again, with a hidden note that it was cut off. The user sees the loop's
1814
- first sentence quoted,
1815
- `loop-guard> thinking repeats itself ("Wait, the count of the letter r…", 3 sentences ×3, 4k chars, 8 s): cut`
1816
- (a short run or a window says how many different sentences it held:
1817
- "12 different sentences in 48"), and `↻ cut by loop-guard, asking again (1/1)`.
1818
- 2. If the retry loops too, the turn is stopped ("stopped the turn: …", "■
1819
- turn stopped by loop-guard") with a card that quotes the repeated
1820
- sentences.
1821
- 3. A loop is forgotten after `forget_after` good steps in a row (generations
1822
- with no loop): a model that recovered and made progress gets its next
1823
- loop cut and retried again, not the turn stopped. `forget_after: 0`
1824
- never forgets: the turn's second loop stops it.
1825
-
1826
- The cut uses the `retry.empty_answer` budget: with `retry.empty_answer: 0`
1827
- the first loop ends the turn as stopped by loop-guard, with the notice and
1828
- no card. `action: stop` stops the turn at the first loop; `action: notify` only
1829
- warns, once per generation.
1830
-
1831
- The cut thinking never goes back to the model, but its last 20k chars are kept
1832
- in the session's folder, `thinking_tails.jsonl` (with a generation that ran to
1833
- the provider's output cap, or that a stop_turn ended): an archived session
1834
- keeps them. A turn's record counts its cuts and cap hits (`cuts`, `capped` in
1835
- `analytics.json`; `/stats` shows "thinking cuts" and "output cap hits").
1836
-
1837
- ```yaml
1838
- bundles:
1839
- loop-guard:
1840
- thinking:
1841
- watch: true # false: the tool-call guard only
1842
- action: retry # retry (cut, ask again; then stop) | stop | notify
1843
- min_chars: 2000 # thinking this long before anything triggers
1844
- repeats: 3 # a cycle seen this many times is a loop
1845
- max_period: 6 # cycles of up to this many sentences
1846
- similarity: 0.5 # 0..1, how alike two sentences must be to count as the same
1847
- min_span_sentences: 6 # a loop spans at least this many sentences…
1848
- min_span_chars: 600 # …and this many chars
1849
- max_same: 8 # one sentence this many times in one generation is a loop
1850
- min_words: 5 # shorter sentences only count toward a short run
1851
- short_run: 24 # this many short sentences in a row…
1852
- short_distinct: 6 # …with at most this many different ones is a loop
1853
- window_sentences: 48 # any this many sentences in a row…
1854
- window_distinct: 12 # …with at most this many different ones is a loop
1855
- forget_after: 10 # good steps in a row that forget a loop; 0: never
1856
- ```
1857
-
1858
- Not watched:
1859
-
1860
- - thinking that arrives as answer text: Gemma 4 on the raw-prompt path (no
1861
- close marker), a chat provider that puts `<think>` in the content;
1862
- - a chat host with streaming off (no chunks);
1863
- - loops in the visible answer;
1864
- - a runaway without sentences, such as an endless comma list of numbers: it
1865
- ends at the output cap as an empty answer, which `retry.empty_answer`
1866
- retries after the fact.
1867
-
1868
- A real small model's circular re-checking that repeats one sentence 8 times
1869
- is cut even if it would have found an answer later; `max_same` sets how
1870
- patient that is.
1871
-
1872
- Not caught (yet):
1873
-
1874
- - near-duplicates, such as `find . -name 'config*'` after `'config.yml'`;
1875
- - loops across turns;
1876
- - alternating calls (A, B, A, B) that each return something new.
1877
-
1878
- ## The cost-cap bundle
1879
-
1880
- `chi bundle install cost-cap` installs the bundle shipped with chi (`chi bootstrap` installs it with the `core`
1881
- profile; an existing install gets it with `chi update`). It caps what one session spends, so neither you nor the
1882
- model has to watch `chi sessions stats`: the harness watches the money and the model never sees any of it (no tool,
1883
- no steer, no prompt text). It is inert without a cap, and there is none by default.
1884
-
1885
- ```yaml
1886
- # config.yml
1887
- bundles:
1888
- cost-cap:
1889
- default: 5.00 # USD cap for a session with none set; absent/0/off: no cap
1890
- child: 2.00 # for delegate children; absent: default
1891
- warn_at: 0.8 # tell the user (only) once at this share of the cap; 0/off: no warning
1892
- ```
1893
-
1894
- - **What counts:** `ctx.cost`'s total: what the provider reported (`usage.cost`), else the estimate from the
1895
- model's configured price (`hosts.<name>.models.<id>.price`), plus side requests (the idle recap, `/btw`,
1896
- `ask_model`), including what earlier workers of the session spent.
1897
- - **When it checks:** before each generation, so before the money is spent. A generation that crosses the cap is
1898
- caught at the start of the next one: the overshoot is at most one generation (plus any side requests between).
1899
- A turn whose last generation crossed it ends normally, and the next turn's first generation asks.
1900
- - **At `warn_at` of the cap** you get one notice, `cost-cap> $2.41 of $3.00 spent (80%)`; a raised cap warns again.
1901
- - **At the cap** the turn pauses on a question (header "Cost cap"): `Cost cap reached: $3.04 spent of $3.00.
1902
- Continue raises it to $6.00.` with **Continue** (another cap's worth: $3 → $6 → $9, as many steps as it takes to
1903
- pass the spend, saved for the session) and **Stop** (the turn stops, `canceled` with `stopped_by: cost-cap`, and a
1904
- card shows the spend, reported, estimated and side). With no one to ask (`--non-interactive`) it stops. A parent
1905
- agent answering it (`chi answer`) may Continue under `guardrails.parent_answers: soft` or `standard`, and only Stop
1906
- under `hard` (config.yml's, or the session's own when stricter) (Continue is tagged `:spend`; see [Guardrails](guardrails.md#answers-from-a-parent-agent)). `/cap N` is
1907
- a command, not an answer: a parent that sends it (`chi send ID -m '/cap 10'`) raises the cap under any strategy.
1908
- - **The cap of a session:** the one `/cap` or a Continue set for it, else its own `cap:` (`chi --set
1909
- cost-cap.cap=3`, `chi send --new --set cost-cap.cap=3`; `--set cost-cap.cap=off`, `0` or a negative number for none), else `child:` for a
1910
- delegate child, else `default:`. A cap is a number (`3`, `.5`, `1e1`; in config.yml and `/cap`, `"$2"` too, which `--set` refuses). `--set` refuses
1911
- another value (`cost-cap.cap=five`: exit 2); one in config.yml (or set before this check) that doesn't read
1912
- (`default: five`) gets one notice, `cost-cap: default: "five" isn't a number or off; no cap`, and a `cap:` or
1913
- `child:` that doesn't read gives way to the next key (`…; using default: ($5.00)`), never a silent no cap. Delegates and continued links each have their own cap (a continued link keeps
1914
- the `--set` cap, not a `/cap` or Continue); there is no family cap.
1915
- - **A host it can't watch:** a model that reports no cost and has no configured price (a local server, a free
1916
- model that reports 0) reads unknown: one notice, `the $3.00 cap can't be enforced: <model> reports no cost and has
1917
- no price`, and it never stops for an unknown cost. A session with some priced generations counts the unpriced
1918
- ones as $0.
1919
-
1920
- **`/cap`** (works while a turn runs; the next generation reads it):
1921
-
1922
- - `/cap`: `cost-cap: $1.20 spent of $3.00 (reported $1.10, estimated $0.10, side $0.02)`, or `cost-cap: no cap
1923
- ($1.20 spent)`, with `(can't be enforced: no cost reported or priced)` when it can't be.
1924
- - `/cap 5`, `/cap $5` or `/cap .5`: the cap (and what Continue adds) becomes $5.00 for this session. A cap at or under the
1925
- spend is allowed: the next generation asks.
1926
- - `/cap off` (or `/cap 0`): no cap for this session, over the config's `default:`.
1927
-
1928
- A parent agent starts a session with a cap of its own with `--set` (`chi send --new --set cost-cap.cap=3 -m "task"`;
1929
- `cost-cap.cap` is the bundle's one session setting), or by sending `/cap N` as a first message
1930
- (`chi send --new -m '/cap 3'`).
1931
- At the cap, `chi send --wait` exits 3 with a question of kind `hook` (header "Cost cap"); `chi answer ID --question
1932
- Q --option Continue` (or `--option 1`) goes on, `--option Stop` stops the turn ([sub-agent.md](sub-agent.md)). A
1933
- parent may Continue: nothing restricts it, as with the step limit. A background delegate child at its cap waits on
1934
- its own card and doesn't wake its parent ([sessions.md](sessions.md#delegating)).
1935
-
1936
- The state is one file per session, `<data_dir>/sessions/<session id>.json` (`{"cap": 3.0, "step": 3.0}`), removed
1937
- with the session. A file that is there but doesn't read (not JSON, or not a mapping) is logged
1938
- (`costcap_state_unreadable`) and gets one notice, `cost-cap: <path> doesn't read, its /cap cap is ignored; using
1939
- default: ($5.00)`: the settings' cap is used, never a silent drop; the next `/cap` or Continue rewrites it, logged
1940
- (`costcap_state_replaced`) and said (`cost-cap: <path> didn't read; replaced with the new cap`).
1941
-
1942
- Its sibling for work instead of money, tool calls and active minutes across the session's turns, is
1943
- [the work-cap bundle](#the-work-cap-bundle): the cap a local model (no cost) can have.
1944
-
1945
- ## The work-cap bundle
1946
-
1947
- `chi bundle install work-cap` installs the bundle shipped with chi (`chi bootstrap` installs it with the `core`
1948
- profile; an existing install gets it with `chi update`). It caps the work one session does across its turns: tool
1949
- calls and active minutes. The per-turn meters reset every turn (the step limit, check-in, loop-guard), and a
1950
- Continue on the step-limit question starts the next 300 steps; a parent agent may answer that Continue itself
1951
- (`chi answer`), so a child it keeps continuing has no overall bound but cost-cap's `$`, and on a local model none.
1952
- work-cap is that bound, with cost-cap's shape: the harness watches, the model never sees any of it. It is inert
1953
- without a cap, and there is none by default.
1954
-
1955
- ```yaml
1956
- # config.yml
1957
- bundles:
1958
- work-cap:
1959
- child: {tool_calls: 500, minutes: 90} # delegate children with no own value
1960
- default: {} # every other session (and a delegate without child:); empty: no cap
1961
- warn_at: 0.8 # tell the user (only) once at this share of a cap; 0/off: no warning
1962
- ignore_tools: [task_wait, task_get, delegate, delegate_result] # not counted: waiting
1963
- ```
1964
-
1965
- - **What counts** (`ctx.usage`): **tool calls**, the session's own across its turns and workers, less
1966
- `ignore_tools` (the waiting tools by default, `delegate` among them since it blocks on its child, so a session
1967
- waiting on a long task or a child isn't capped for waiting); and **active minutes**, work time: the generations' time plus the finished tool calls' time (less
1968
- `ignore_tools`' time), never a wait (a question, its own included, an approval, the user's answer to
1969
- `ask_user_question`), so idle time and a Continue answered hours later don't count.
1970
- - **When it checks:** before each generation, like cost-cap: the overshoot is at most one generation's tool calls.
1971
- When the step limit and a work cap fall in the same turn, the work cap asks first, and its Stop ends the turn.
1972
- - **At `warn_at` of a cap** you get one notice per meter, `work-cap> 320 of 400 tool calls (80%)`; a raised cap
1973
- warns again.
1974
- - **At a cap** the turn pauses on a question (header "Work cap") that names the session's totals, so a parent
1975
- answering it decides on the whole picture: `Work cap reached: 412 tool calls of 400 (6 turns, 47 min active,
1976
- $1.20). Continue raises it to 800.` **Continue** raises the cap by another cap's worth (as many steps as it
1977
- takes to pass the work, saved for the session), **Stop** stops the turn (`canceled` with `stopped_by: work-cap`)
1978
- with a card showing the totals. Both meters at once: one question naming both, Continue raises each. With no one
1979
- to ask (`--non-interactive`) it stops. Continue is tagged `:spend`, as cost-cap's: a parent agent may Continue
1980
- under `guardrails.parent_answers: soft` or `standard`, only Stop under `hard` (see
1981
- [Guardrails](guardrails.md#answers-from-a-parent-agent)).
1982
- - **The caps of a session**, each meter on its own: the one `/workcap` or a Continue set, else its own value (`chi
1983
- --set work-cap.tool_calls=400`, `work-cap.minutes=60`, `chi send --new --set …`; `off`, `0` or a negative number
1984
- for none), else `child:`'s for a delegate child, else `default:`'s. Minutes in config.yml read `90`, `90m` or
1985
- `1.5h`. A value that doesn't read (`tool_calls: many`, a `default:` that isn't a mapping) gets one notice,
1986
- `work-cap: tool_calls: "many" isn't a number or off; using default.tool_calls: (400)`, and the next value is used,
1987
- never a silent no cap.
1988
-
1989
- **`/workcap`** (works while a turn runs; the next generation reads it):
1990
-
1991
- - `/workcap`: `work-cap: 320 of 400 tool calls (6 turns, 47 min active, $1.20)`, or `work-cap: no cap (…)` with the
1992
- totals.
1993
- - `/workcap 400`: the tool-call cap (and what Continue adds) becomes 400 for this session; `/workcap 90m` or
1994
- `/workcap 2h`: the active-minutes cap.
1995
- - `/workcap off` (or `/workcap 0`): no work cap for this session, over the config.
1996
-
1997
- The state is one file per session, `<data_dir>/sessions/<session id>.json` (`{"tool_calls": {"cap": 800, "step":
1998
- 400}}`, a meter's `"cap": null` for off). A file that is there but doesn't read (not JSON, or not a mapping) is
1999
- logged (`workcap_state_unreadable`) and gets one notice, `work-cap: <path> doesn't read, its /workcap caps are
2000
- ignored; using default.tool_calls: (400)`: the settings' caps are used, never a silent drop; the next `/workcap` or
2001
- Continue rewrites it, logged (`workcap_state_replaced`) and said (`work-cap: <path> didn't read; replaced with the
2002
- new cap`).
2003
-
2004
- ## The check-in bundle
2005
-
2006
- `chi bundle install check-in` installs the bundle shipped with chi (`chi
2007
- bootstrap` installs it with the `core` profile). It is
2008
- written only against this API (`lib/samagotchi/bundles/check-in/plugin.rb`):
2009
- `chi.on` hooks, `ctx.card`, `ctx.steer`, `ctx.stop_turn` and one anytime
2010
- command. It has no memory file.
2011
-
2012
- A turn can run a long time on its own, reading and searching, without saying
2013
- what it has found. check-in counts the turn's tool calls, and when there are
2014
- `after` of them with no answer yet (then every `every` more) it checks in:
2015
-
2016
- - **`mode: ask`** (the default): a card, one per turn, updated in place at
2017
- each check-in: "50 tool calls, no answer yet", how long the turn has run
2018
- and its last few tools, and three actions:
2019
- - **Nudge** (`/checkin nudge`): puts `message` into the running turn
2020
- (`ctx.steer`); the model reads it at its next step and answers or says
2021
- what is left. Every UI shows `check-in> nudged: …`. One nudge per
2022
- check-in: another click (or a typed `/checkin nudge`) answers
2023
- "check-in: already nudged at N tool calls".
2024
- - **Keep going** (`/checkin later`): closes the card until the next
2025
- check-in.
2026
- - **Stop** (`/checkin stop`): stops the turn.
2027
-
2028
- When the turn ends the card loses its actions ("The turn ended after N tool
2029
- calls"), so no stale buttons stay; a card left by a worker that exited
2030
- mid-turn comes back without them too. In the attached terminal the actions are
2031
- `→ /checkin nudge` lines to type; the command runs beside the turn.
2032
- - **`mode: nudge`**: nudges the model by itself, with a notice line.
2033
- - **`mode: notify`**: a notice line only.
2034
-
2035
- The count is per turn: a new turn (a prompt, a continue, a reminder) starts
2036
- from zero; steering merged into the running turn doesn't reset it (a cap
2037
- across the session's turns is [the work-cap bundle](#the-work-cap-bundle)). The polling
2038
- tools are not counted. A nudge that arrives after the model's final answer is
2039
- dropped (logged), never restarting a turn that is done; the card's "Nudged the
2040
- model at N tool calls" then becomes "The answer came first; nudge not sent."
2041
-
2042
- ```yaml
2043
- # config.yml
2044
- bundles:
2045
- check-in:
2046
- after: 50 # tool calls in one turn before the first check-in
2047
- every: 50 # then again every this many more
2048
- mode: ask # ask | nudge | notify
2049
- message: "You've made {calls} tool calls in this turn without answering. Say briefly what you've found so far and what's left, then answer now or continue."
2050
- ignore_tools: [task_wait, task_get, delegate_result]
2051
- ```
2052
-
2053
- `{calls}` in `message` is the count. The default asks for what has been found
2054
- and what is left, not "how's it going?": a small model tends to answer that
2055
- with a line and carry on unchanged.
2056
-
2057
- `/checkin` (anytime) for this session. What it changes (on/off, the mode,
2058
- the threshold) is saved with the session, in the bundle's data dir
2059
- (`plugins/check-in/sessions/<id>.json`), so it outlasts a worker's restart
2060
- and goes with the session; another session starts from config.yml:
2061
-
2062
- | | |
2063
- |---|---|
2064
- | `/checkin` | on or off, the mode, the threshold and this turn's count |
2065
- | `/checkin on` / `off` | check in, or not |
2066
- | `/checkin 30` | check in after 30 tool calls, then every 30 |
2067
- | `/checkin mode ask` / `nudge` / `notify` | the mode |
2068
- | `/checkin nudge` / `later` / `stop` | the card's actions, also by hand |
2069
-
2070
- **Asking System 1 (audit).** Each check-in also asks the cheap judgment model
2071
- `check-in.progress` — "Is this turn still making progress toward what the user
2072
- asked?" — on a side thread, with the owner's prompt, the calls since the last
2073
- check-in (each cut as it is captured, about 4 KB in all), the count and the
2074
- elapsed time. It is off until you give it a mode in
2075
- [`system_one.judgments`](configuration.md#bundles-judgments), and nothing is
2076
- acted on: the answer is saved, and so is what the user then did with the card
2077
- (`nudge`, `keep_going`, `stop`, or `turn_stopped` when the card was still open
2078
- when the turn ended), as a label on that run for a later look. The card, the
2079
- nudge and the notice are the same either way. See
2080
- [System 1's saved runs](system-one.md).
2081
-
2082
- ## The slow-commands bundle
2083
-
2084
- `chi bundle install slow-commands` installs the bundle shipped with chi (`chi
2085
- bootstrap` installs it with the `core` profile). It is written only against
2086
- this API (`lib/samagotchi/bundles/slow-commands/plugin.rb`), with `chi.on`
2087
- hooks and a `/slow-commands` command, and has no memory file.
2088
-
2089
- At its limit (120 s, `execute.timeout_sec`) `execute` hands a command still
2090
- running over as a background task (`execute.on_timeout: task`, the default),
2091
- or kills it (`kill`). A full test suite or a build takes longer, so each run
2092
- first blocks the turn for those two minutes (and, in kill mode, loses them,
2093
- then starts again with `task_create` and `task_wait`); the next session does
2094
- the same. slow-commands remembers such a command for the project:
2095
-
2096
- - An `execute` that **timed out** or was **handed over** at the limit, or ran **`warn_ratio` of the limit** or
2097
- longer (default 0.8, so 96 s of 120), is recorded as slow. A later run of
2098
- it under half the limit **with exit 0** drops the entry; a fast failure (a
2099
- load error) doesn't, since it says nothing about how long the suite takes.
2100
- Nor does one through a filter the key leaves out (`rspec 2>&1 | tail -30`
2101
- exits with `tail`'s 0, and a `| head` can end it early).
2102
- A call the user stopped, or that was denied, records nothing.
2103
- - The **next identical `execute`** is **denied** with advice:
2104
-
2105
- ```
2106
- [execute] Error: denied by guardrail (bundle slow-commands): slow command. The user was not asked. This command ran past the execute limit (120 s) here on 2026-10-09. Start it with task_create, then task_wait (timeout 600). A finished task of this command took 4m10s.
2107
- ```
2108
-
2109
- The last sentence is there when a task of the same command (and cwd)
2110
- finished with exit 0 in the project's `tmp/tasks`; a longer one raises the
2111
- `task_wait` timeout it suggests. The user sees one line:
2112
- `slow-commands> execute bundle exec rspec: ran past 120 s before, denied`.
2113
- - **Once per command per turn**: the same `execute` again in that turn runs.
2114
- The model insisting is a signal (maybe the suite got faster), and that run
2115
- records the new truth. A new turn denies again.
2116
- - In kill mode (`execute.on_timeout: kill`), a **`timeout N` past the limit**
2117
- is denied up front, with no history: execute stops the command first, so
2118
- `timeout` never fires. In task mode it runs on as a task until `timeout`
2119
- fires. `timeout`'s exit codes (124, 137) mean nothing special here.
2120
-
2121
- A command is the same when its project and its text match. The project is
2122
- the session's git checkout (else its working directory). The text is the
2123
- command's words and operators (`a && b` is not `a b`), the call's `cwd:`
2124
- folded in as `cd web && …`, and a trailing `2>&1`, `| tail …`, `| head …`
2125
- or `| grep …` dropped (they don't change how long it runs). Arguments stay:
2126
- `bundle exec rspec` (the suite) is slow, `bundle exec rspec
2127
- spec/foo_spec.rb` isn't the same command, and stays the fast path. A
2128
- command that ends inside a quote, `$(` or heredoc is never recorded, nor
2129
- one with a `$(…)`, backticks or a heredoc `cat` or `tee` reads (the key
2130
- can't tell two of those apart). A heredoc script (`python3 - <<'EOF'`)
2131
- keeps its body in the key, so each script is its own command.
2132
-
2133
- Wrappers a model adds by habit don't make a new command: at the start of
2134
- each simple command (so after a leading `cd X &&` too), `time [-p]` and
2135
- `timeout`/`gtimeout` with its options and duration are left out, so
2136
- `timeout 300 bundle exec rspec` and `bundle exec rspec` are one entry. `X=…`
2137
- assignments stay, sorted (`SPEC=… rake spec` is not `rake spec`), except
2138
- `NO_COLOR`, `FORCE_COLOR` and `TERM` (`CI` stays: jest or vitest without it
2139
- can sit in watch mode); a plain `env X=… cmd` is `X=…
2140
- cmd`, and an `env` with an option (`-C`, `-i`, `-u`) stays as typed. The
2141
- list shows each entry as it was last typed.
2142
-
2143
- Since 0.2.0 (chi 0.59.0) a hand-over counts as timed out, and the advice's
2144
- duration also reads a handed-over task, whose `exit_code` file is in the
2145
- state dir (the record's `exit_code_path`).
2146
-
2147
- Entries live in `$XDG_STATE_HOME/samagotchi/plugins/slow-commands/commands.json`,
2148
- shared by every session (another session's record counts at once) and
2149
- forgotten after `ttl_days`.
2150
-
2151
- ```yaml
2152
- # config.yml
2153
- bundles:
2154
- slow-commands:
2155
- mode: deny # deny | notify (warn the user, never deny)
2156
- warn_ratio: 0.8 # a run this share of the execute limit or longer is slow
2157
- ttl_days: 14 # entries older than this are forgotten
2158
- ```
2159
-
2160
- | | |
2161
- |---|---|
2162
- | `/slow-commands` | this project's slow commands, numbered |
2163
- | `/slow-commands forget 2` / `forget all` | drop one (a wrong entry) or all of them |
2164
-
2165
- ## The agents-md bundle
2166
-
2167
- `chi bundle install agents-md` (or the `core` profile) installs the bundle shipped
2168
- with chi (`lib/samagotchi/bundles/agents-md/plugin.rb`): two `chi.on` hooks
2169
- (`:before_turn` rebuilds the steered set, `:after_tool_call` steers), and no memory file.
2170
-
2171
- chi's system prompt holds only the `AGENTS.md` chain from the checkout top down
2172
- to the session's cwd, so an `AGENTS.md` in a directory the session doesn't run
2173
- in (say `pkg/inner/` while the session runs in `pkg/`) is never seen. The
2174
- bundle closes that gap in history, not in the system prompt: the first `read`,
2175
- `write` or `edit` (its `tools` setting) of a file under a directory with an
2176
- `AGENTS.md` steers that file into the running turn, at the loop's next
2177
- boundary, as its own user message — with a first line that says which
2178
- directory it belongs to:
2179
-
2180
- ```
2181
- AGENTS.md for pkg/inner/ (applies to work under pkg/inner/):
2182
- <content>
2183
- ```
2184
-
2185
- - It steers the **outermost candidates first** (each directory from the
2186
- touched file's directory up to, but not including, the checkout top), so a
2187
- deep file can bring in several `AGENTS.md`s at once, outermost to nearest.
2188
- - It **never re-injects**: each directory steers once per session, and a
2189
- `before_turn` pass over the conversation rebuilds that set from the steers
2190
- already there. A steer the model answered past (never injected) is absent,
2191
- so it fires again on the next touch; a resume, a woken worker or a fork
2192
- pick the set up from their messages. It never stops generation or thinking.
2193
- - **Scope:** the touched file's own git root must be the session's checkout:
2194
- a file in another repository, a nested repository or a submodule is
2195
- ignored. Paths compare by `File.realpath`, so a symlinked cwd (a macOS
2196
- `/tmp`) still matches.
2197
- - Directories whose `AGENTS.md` is already in the system prompt (`ctx.prompt_files`:
2198
- the chain and appended files) are skipped, as is a file at the checkout top
2199
- (its `AGENTS.md` is the chain's first).
2200
-
2201
- ```yaml
2202
- # config.yml
2203
- bundles:
2204
- agents-md:
2205
- tools: [read, write, edit] # the calls that count as a touch
2206
- max_chars: 16000 # the content is cut here, with a "[cut at N
2207
- # of M chars: read <absolute path> for the rest]" last line
2208
- ```
2209
-
2210
- `skip_agents_md: true` disables the bundle, as it does the chain's loading
2211
- (see [Configuration](configuration.md#project-specific-description)).
2212
-
2213
- ## The skills bundle
2214
-
2215
- `chi bundle install skills` (or the `dev` profile) installs the bundle shipped with chi
2216
- (`lib/samagotchi/bundles/skills/plugin.rb`): one anytime command, `chi.on`
2217
- hooks, `ctx.sessions.send`, `ctx.notify` and `ctx.steer`. It has no memory
2218
- file; skills themselves work without it ([docs/memory.md](memory.md#skills)).
2219
-
2220
- | | |
2221
- |---|---|
2222
- | `/skill save [name] [--system]` | sends this session a request to save what was just done as `skill_<name>` (chi picks a name when none is given), project scope unless `--system`. The request holds the skill's shape, so the result is the same with a model that never read the memory guide. It runs as a turn; sent while a turn runs, it joins that turn at its next step (the request says to finish the task first). An existing skill is updated. In a `--no-shared` REPL, which takes no messages, the command shows the request to send yourself |
2223
- | `/skill list` | the `skill_*` memories of both scopes, with the date and description from the index |
2224
- | `/skill show <name>` | one skill as saved (project first, as `memory_read` looks) |
2225
- | `/skill diff <name> [N]` | the skill now against its N-th newest older version (default 1: before the last change), unified |
2226
-
2227
- **History.** Before `memory_write`, `write` or `edit` changes a
2228
- `skill_<name>.md` in a memories folder, the file as it was is kept under
2229
- `$XDG_STATE_HOME/samagotchi/plugins/skills/history/<scope>/<name>/` (`system`,
2230
- or `project-<project folder>`), the newest `history_keep`. It is state, not a
2231
- memory: `chi bundle build` and a synced `~/.config` never see it. After the
2232
- call a line says what happened:
2233
-
2234
- ```
2235
- skills> skill release saved (project, 14 lines)
2236
- skills> skill release updated (+2 −1): 1. Run `scripts/verify.sh`; stop if it fails. · /skill diff release
2237
- ```
2238
-
2239
- The line is the file on disk changing, whatever the tool answered; a denied
2240
- write shows nothing.
2241
-
2242
- A skill read in the turn is also watched for changes made another way (an
2243
- `execute` running `sed`, a script): after each other tool call, and at the
2244
- turn's end, its file is compared with the content last seen (at the read, or
2245
- after the last write). A change shows the same line, keeps the content last
2246
- seen as a version (so `/skill diff` has it) and counts as the skill updated.
2247
- A plain read keeps no version.
2248
-
2249
- **The nudge** (`nudge: true`). Some models, finding a skill's step broken,
2250
- skip it and go on without fixing the skill. In a turn that read a skill
2251
- (`memory_read` of a `skill_*` name, or `read` of its file), the first failing
2252
- tool call after it (an `execute` that exited non-zero, except a grep-family
2253
- search that found nothing, a tool error) steers
2254
- the model once (a call a guardrail or the user denied doesn't count as a
2255
- failed step): *"A step of skill release failed. Find out why before skipping
2256
- it; if the skill is out of date, fix it now: edit the step that changed in
2257
- its file (or memory_write the whole skill) and add a Changelog line."* No
2258
- steer once a skill read this turn has changed, by any tool. If the turn ends
2259
- with a failed step and no skill read changed, one line says so: `skill
2260
- release was followed, a step failed, the skill wasn't updated`. A failure
2261
- unrelated to the skill (a test
2262
- meant to fail) can set it off too: once per turn, and only after a skill was
2263
- read.
2264
-
2265
- ```yaml
2266
- # config.yml
2267
- bundles:
2268
- skills:
2269
- history_keep: 20 # older versions kept per skill
2270
- nudge: true # steer once when a followed skill's step fails
2271
- ```
2272
-
2273
- ## The github-pr bundle
2274
-
2275
- ```sh
2276
- chi bundle install github-pr # in the dev profile; needs gh, logged in
2277
- ```
2278
-
2279
- Proposes the branch's open GitHub pull request to a session as a candidate
2280
- `pr-<n>` when its worker starts (not in a scratch session; quietly nothing
2281
- without `gh`, a repository or an open PR): it is attached once you mention it
2282
- (`#N`, the branch or its URL; [Candidates](context.md#candidates)). It resolves
2283
- PR URLs for `chi context add`. Its script prints the PR as text
2284
- and a summary of what changed in counts, authors and states only; it wakes
2285
- the session for a review requesting changes, checks turning red, or the PR
2286
- merged or closed. In the web, a `path:line` in a worker's answer links to
2287
- that line of the session's PR ([Line links](context.md#line-links); `line_links:
2288
- always` for the REPL and `chi -p` too), and its ref menu offers the file
2289
- here and a "PR diff" action (`event[:refs]`). `auto_attach: attach` attaches
2290
- it at once (the old default), `off` does nothing ([Propose, attach or
2291
- off](context.md#propose-attach-or-off)).
2292
- See [Attached context](context.md#github-prs-the-github-pr-bundle).
2293
-
2294
- ## The coordinator bundle
2295
-
2296
- ```sh
2297
- chi bundle install coordinator # in the dev profile
2298
- ```
2299
-
2300
- chi as a coordinator of parallel work, the way you would run several agents
2301
- yourself: split the work, one git worktree and child session per task, keep
2302
- talking while they run, check each report, and merge only with your OK. It
2303
- works in a session with a worker (plain `chi`, the web). A `--no-shared` REPL
2304
- or `-p` gets no delegate reports, so the children's replies wouldn't come back
2305
- by themselves there.
2306
-
2307
- - **The skill.** `skill_coordinator` (system scope; its index line says what
2308
- it is for, from the manifest's `description:`) holds the steps. The model
2309
- creates each worktree with `execute` (`git worktree add ../<repo>-<task> -b
2310
- <branch>`), starts a child there with `delegate wait: false, cwd:`, tells
2311
- you what started and ends its turn. When a child's report comes, it checks
2312
- the branch (`git log`, `git diff --stat`, the tests the child names) before
2313
- telling you. It asks before each merge (`ask_user_question`), checks that its
2314
- own folder is on the default branch and that branch's log first (another
2315
- agent may have merged the branch already), merges `--ff-only` and never
2316
- pushes unless you ask. After a merge it stops the
2317
- child and removes only the worktrees and branches it made.
2318
- - **A handoff memory.** The conversation is lost when the session ends, so
2319
- the skill keeps a project memory `handoff_<epic-slug>` with only what git
2320
- and the session list can't rebuild: the split (branch, worktree, child id
2321
- per task), your decisions, its verdicts and the follow-ups. Its index
2322
- description is the status, descriptive only and naming the session that
2323
- owns it ("OPEN coordinator handoff calc-v2 (session ab12cd34): 2/3 merged",
2324
- later "DONE: …"): every session in the repo sees that line. The model saves
2325
- a decision there before acting on it, and changes the status with
2326
- `memory_write`'s description-only form. When everything is done it marks
2327
- the handoff DONE and asks whether to remove it (`memory_write remove:
2328
- true`, which the guardrails bundle asks you to confirm). Children are told
2329
- not to touch it.
2330
- - **Resume.** A new coordinator session (or one asked "where were we?")
2331
- reads the open handoff, checks it against git and the session list (git
2332
- wins; mismatches are reported) and goes on from the first open step.
2333
- - **`/coordinate <goal>`** sends this session a turn asking the model to
2334
- follow the skill for the goal (in a `--no-shared` REPL it shows the text to
2335
- send yourself). Asking "do this in parallel" works too: the index line leads
2336
- the model to the skill. **`/coordinate resume`** asks it to resume this
2337
- project's open handoff; with several open it shows a card with a Resume
2338
- action each (`/coordinate resume <name>` picks one), with none it says so.
2339
- **`/coordinate end`** ends the day: the model checks each branch, brings
2340
- its handoff up to date (state per branch, decisions, verdicts,
2341
- follow-ups, each open child's id, branch and worktree), keeps it OPEN unless everything is done, and gives a short
2342
- report ending with the `/coordinate resume <slug>` to pick it up next
2343
- time. It starts, merges and stops nothing: running children stay running
2344
- and are named in the report.
2345
- - **Sprint review (experimental, 0.6.0).** **`/coordinate review [name]`**
2346
- starts a review session of this coordinator session (`ctx.sessions.review`:
2347
- its recap, never its transcript; this session keeps running) seeded with the
2348
- open handoff's body (the one named, the only one, or a card with a Review
2349
- action each when several are open; with none, the recap alone), and prints
2350
- the `chi share <id> --name NAME` line. A participant (a manager, a teammate)
2351
- brings new context there; the skill's Sprint review section (copied into
2352
- the seed: a participant's turn reads project memories only, and the skill
2353
- is a system one) has the review's model answer it with a **hand-off diff** (the handoff's lines as
2354
- they would change, in a `diff` block, and what it means per branch), in a
2355
- turn that may only read. Your **Apply** under it (the web's) quotes the
2356
- diff in your turn there: the model brings the handoff up to date and
2357
- re-plans in words, and starts, stops or merges nothing from the review
2358
- session: the coordinator session picks the change up from the handoff,
2359
- merges still asked. Experimental: it may go if it doesn't earn its place.
2360
- - **The coordinator toolkit.** The bundle declares `coordinator`: `lean`
2361
- plus `delegate`, `delegate_result` and `list_sessions`
2362
- ([Toolkits](configuration.md#toolkits)). `/coordinate` puts a fresh session
2363
- on it before it asks the model (`ctx.use_toolkit`). When chi refuses (a reply
2364
- or a turn already there) and the session's toolkit has no `delegate`, the
2365
- reply says to run `/toolkit coordinator`. A continue of a coordinator link
2366
- keeps the toolkit.
2367
- - **The coding toolkit.** The bundle (0.5.0) also declares `coding`: `child`
2368
- with the prompt text `- Be concise in your responses` / `- Show file paths
2369
- clearly when working with files`. The skill starts build and fix children
2370
- on it (`delegate` with `toolkit: "coding"`); reviews, research and plans
2371
- stay on `toolkit.child`, as they need the length.
2372
- - **`/children [all]`** shows the session's children as a card, newest first,
2373
- one line each: `` `ab12cd34` · running · fix/flaky · "fix the flaky spec" ``,
2374
- `` `9a8b7c6d` · done · feat/x · reported · "All 12 specs pass" `` (`not
2375
- reported yet` when the parent wasn't given that reply), `` `77aa66bb` ·
2376
- waiting (approval) · open it: chi --attach 77aa66bb ``. A fork is marked
2377
- `fork`; `all` adds archived children. It runs during a turn too. The card
2378
- has Refresh and a `Stop <id>` per running or waiting child (up to 5);
2379
- `/children stop <id>` stops one of this session's own children (by session
2380
- id, as `chi sessions stop` does) and shows the card again.
2381
- - **Children stay in their worktree.** A child asks before it changes
2382
- anything outside its worktree (your checkout, a sibling's), in every
2383
- guardrails mode and without the guardrails bundle ([a delegate child's
2384
- boundary](guardrails.md#a-delegate-childs-boundary)); you answer on its
2385
- card, or on the parent's while it waits.
2386
- - **Merges.** The parent's merge in its own checkout is a plain `git
2387
- merge`; to be asked before every merge, add a rule ([Rules in
2388
- config.yml](guardrails.md#rules-in-configyml)):
2389
-
2390
- ```yaml
2391
- guardrails:
2392
- rules:
2393
- - id: git-merge
2394
- tool: shell
2395
- command: '\bgit\s+merge\b'
2396
- verdict: ask
2397
- reason: merging a child's branch
2398
- ```
2399
-
2400
- ## The claude-peer bundle
2401
-
2402
- ```sh
2403
- chi bundle install claude-peer # in the dev profile
2404
- ```
2405
-
2406
- A live link between a chi session and a Claude Code session you already work
2407
- with: chi sends it a part of the work (a plan step, a diff, a finding) to
2408
- validate or as context, and Claude's answer comes back into chi. This is
2409
- Claude with the context it has, not a fresh review run. Nothing runs until a
2410
- Claude pairs; without one the bundle costs one tool declaration.
2411
-
2412
- - **Pairing is Claude's.** chi can't see Claude's inbox, so Claude attaches
2413
- two pushed sources to the chi session: `claude-inbox`, whose hint is its
2414
- per-session inbox socket (`CLAUDE_CODE_MESSAGING_SOCKET`, Claude Code
2415
- 2.1.224 or later), and `claude-outbox`, where its answers come. You never
2416
- run that yourself:
2417
- 1. `/claude install-skill` (once) shows a card with the target,
2418
- `$CLAUDE_CONFIG_DIR/skills/chi-peer/SKILL.md` (else `~/.claude/…`),
2419
- whether one is there and, when it differs, a short diff; its Install (or
2420
- Replace) button runs `/claude install-skill --yes`, which copies the
2421
- bundle's `scripts/chi-peer-SKILL.md` there with the installed
2422
- `scripts/pair` path written in. The copy happens inside chi, where no
2423
- guardrail sees it: the button is your consent. The card also offers the
2424
- Claude Code permission rule `Read(~/.local/state/samagotchi/plugins/claude-peer/**)`
2425
- (your state folder), so Claude isn't asked before reading a long part's
2426
- file; chi never writes Claude's settings.
2427
- 2. In Claude Code you say "pair with chi <id or chi web URL>". The skill runs
2428
- `sh <bundle>/scripts/pair <id or URL>`, which attaches `claude-inbox` (the
2429
- socket as its hint, pushed as JSON so a re-pair after a Claude restart
2430
- refreshes it) and `claude-outbox`, and lists the session's context. A
2431
- re-pair keeps Claude's last answer.
2432
- 3. Claude answers a validate or a question with a JSON push to
2433
- `claude-outbox` (`text`, `summary`, `wake: true`), which wakes chi, the
2434
- first answer too (on chi 0.62 the first one arrives as a note without
2435
- waking); the model reads it with `context_read claude-outbox`.
2436
- - **The tool `claude_send(kind, title, text)`**, `kind` being `validate`,
2437
- `context` or `question`, writes one JSON line to that socket. The message
2438
- starts with a header, `chi <id> · <kind> · <title>`. A text up to 4,000
2439
- characters follows inline; a longer one goes to a file,
2440
- `$XDG_STATE_HOME/samagotchi/plugins/claude-peer/sessions/<id>/<HHMMSS>-<slug>.md`
2441
- (removed with the session), and the message names it (`payload: <path>`).
2442
- The tool is declared whether or not a Claude is paired, so pairing doesn't
2443
- change the prompt. Its errors say what to do: no `claude-inbox` (pair from
2444
- Claude), the socket gone or refusing (that Claude session ended or
2445
- restarted: pair again), a text over 200,000 characters.
2446
- - **`/claude`** (an anytime command, so it works mid-turn) sends without
2447
- the model:
2448
- - `/claude` alone shows a card: paired or not, the socket and whether its
2449
- file is there (it goes when that Claude session ends), the last send, and
2450
- Claude's last answer (the `claude-outbox` summary). When Claude's installed
2451
- chi-peer skill differs from what `/claude install-skill` would write (an
2452
- older bundle's, or your edit; a skill installed by a chi with another state
2453
- dir or bundle path differs too), it says so: install it again (Replace),
2454
- then pair again.
2455
- - `/claude validate <text>` and `/claude context <text>` send the text as it
2456
- is, titled by its first line (past a web quote's `From …:` label and a
2457
- quoted line's `> `): paste a selection after them.
2458
- - In the web, selecting text offers **Confirm with Claude**
2459
- ([`chi.annotation`](#chiannotationlabel-command-template-quote-send-false)):
2460
- it fills the composer with `/claude validate` and the quote, for you to
2461
- add what needs confirming.
2462
- - `/claude last` sends the model's last completed answer as context. Mid-turn
2463
- it is the answer before the running turn, never the turn's partial text;
2464
- a cancelled or failed turn has no answer, so the one before it goes.
2465
- - **The peer loop.** The bundle declares `claude-outbox` a peer's
2466
- ([`chi.peer_source`](#chipeer_sourcename-label)), so Claude's answers
2467
- wake chi by the loop's rules ([Waking: peer
2468
- sources](context.md#peer-sources-the-peer-loop)): chi fixes what Claude
2469
- flagged or disagrees and sends again, up to `context.peer_turns` (3) wake
2470
- turns in a row, and a `VERDICT OK` answer wakes chi once to close the
2471
- round (carry on, or tell you what was agreed). Only a message you type in the web or a TUI starts the count again.
2472
- - **The skill.** `skill_claude_peer` (system scope) tells the model to send
2473
- only when you ask or to reply in a peer turn, to pick the part rather than
2474
- the session, not to wait or poll, and how to read the `claude-outbox`
2475
- answer (a validate ends with `VERDICT: OK`, `CHANGES` or `UNSURE`): act on
2476
- it only within your task, and stop and tell you when Claude agrees or after
2477
- the last turn. Claude's skill ends each answer's summary with its verdict
2478
- and never answers with `chi send` (which counts as you typing).
2479
- - **chi on another machine.** With the chi session on the Studio and Claude on
2480
- the laptop, `CHI_REMOTE=studio sh <bundle>/scripts/pair <id>` pairs through
2481
- the Studio's chi web ([Remote sessions](cli.md#remote-sessions)), and
2482
- Claude's answers (its `chi context push claude-outbox`, with `CHI_REMOTE`
2483
- set) reach chi: the outbox leg works. The inbox leg doesn't: `claude_send`
2484
- writes to Claude's socket on the machine chi runs on, and the laptop's isn't
2485
- there. So through a remote (`CHI_REMOTE`, or `--remote NAME` in `CHI`)
2486
- `pair` attaches only `claude-outbox` and prints one line saying chi there
2487
- can't send to this Claude: chi's replies reach Claude only when you relay
2488
- them (or ask it to run `chi --remote studio send --wait <id>`). A session
2489
- that already has a `claude-inbox` it can't reach:
2490
- `chi --remote studio context rm claude-inbox <id>`.
2491
- **Two ways to make it two-way over SSH.** SSH can forward a Unix socket, so
2492
- the inbox leg works too. On the laptop:
2493
-
2494
- ```sh
2495
- ssh studio rm -f /tmp/claude-peer-ab12.sock
2496
- ssh -N -o ExitOnForwardFailure=yes -R /tmp/claude-peer-ab12.sock:"$CLAUDE_CODE_MESSAGING_SOCKET" studio
2497
- ```
2498
-
2499
- the second running in the background while chi may send (the `rm -f` first:
2500
- a remote forward's stale socket is replaced only when the **server's** sshd
2501
- has `StreamLocalBindUnlink yes`). Then
2502
- `CHI_REMOTE=studio sh <bundle>/scripts/pair --inbox-socket /tmp/claude-peer-ab12.sock ab12`
2503
- attaches both sources, with `claude-inbox`'s hint that path on the Studio. A
2504
- re-pair this way replaces an outbox-only pairing's `claude-outbox` and its
2505
- why. Claude's socket changes when that Claude session restarts: stop the ssh,
2506
- run both lines, pair again. A path chi quotes (a `payload:` file, a diff to
2507
- check) is on the Studio, not the laptop. Whoever can write to that socket on
2508
- the remote machine can send into this Claude session (sshd makes it the
2509
- user's, mode 0600 by default): fine on your own machine or pod, not a shared
2510
- host. Claude's own skill has the same under "chi on another machine over SSH".
2511
- - **A continue.** The pairing's two sources are pushed, so they stay with
2512
- the old session when you continue it ([Movable
2513
- context](context.md#peers-and-a-continue)). The new session's worker posts
2514
- Claude one message, from a quiet init task, to the socket the old
2515
- `claude-inbox` last had:
2516
-
2517
- ```
2518
- chi <old> · moved · continued as <new id>
2519
- This chi session was continued as <new id>. Pair with <new id> the way you paired with <old>, then answer there (chi context push claude-outbox <new id>).
2520
- ```
2521
-
2522
- Claude's skill pairs again with the new id the same way it paired before
2523
- (the same `CHI_REMOTE` and `--inbox-socket`). It is posted once (a marker
2524
- under the bundle's `sessions/<id>/`, so a worker restart doesn't post it
2525
- again); a post that fails (that Claude session ended) is logged and
2526
- dropped. An outbox-only pairing has no inbox to post to: Claude's next
2527
- answer to the old id is refused with the new one (`<old> was continued as
2528
- <id>`), and the skill pairs again and pushes the answer there. The new
2529
- session's note says which: `Left with 3f2a9c1e: claude-inbox, claude-outbox
2530
- (Claude's pairing: chi asks Claude to pair again with this session).`, or
2531
- `(Claude pairs again when it next answers)`.
2532
- - **Asking first.** The tool has no `targets:`, so guardrails match it by name
2533
- only: to be asked before each send, add a rule ([Rules in
2534
- config.yml](guardrails.md#rules-in-configyml)):
2535
-
2536
- ```yaml
2537
- guardrails:
2538
- rules:
2539
- - id: claude-send
2540
- tool: claude_send
2541
- verdict: ask
2542
- reason: sends session content to Claude Code
2543
- ```
2544
-
2545
- - **Limits.** The socket's format (`{"type":"user","message":{"role":"user","content":"…"}}`)
2546
- is undocumented: it was found in, and checked on, Claude Code 2.1.296. A
2547
- line Claude Code can't parse is dropped silently, so a Claude Code update
2548
- could break this without an error. No auth line is sent: it is optional on
2549
- macOS and Linux, and native Windows, which needs it, isn't supported.
2550
- Claude's `crossSessionInbound` setting decides what it does with a peer
2551
- message: an interactive auto-mode session delivers it; a session that
2552
- bypasses permissions holds it for approval (in `-p` it expires after 5
2553
- minutes). It is local only (a Unix socket), but it does hand session
2554
- content to another agent: only what the model or you picked.
2555
- - **Needs chi 0.67.0** for the loop (`chi update`): the plugin is built on
2556
- `Samagotchi::Plugin::Peer` (lib/samagotchi/plugin/peer.rb), the base both
2557
- peer bundles share (the tool, `/claude`, the cards, payloads), and each
2558
- bundle sets its strings and transport.
2559
-
2560
- ## The codex-peer bundle
2561
-
2562
- ```sh
2563
- chi bundle install codex-peer # in the dev profile
2564
- ```
2565
-
2566
- The [claude-peer bundle](#the-claude-peer-bundle) for an OpenAI Codex CLI
2567
- session: chi sends the Codex session you work with a part of the work to
2568
- validate or as context, and Codex's answer comes back into chi. It is a copy
2569
- of claude-peer with the transport swapped; what differs is below, the rest
2570
- (kinds, payload files, the last send, `/codex last`, the status card, the
2571
- skill install card) works the same.
2572
-
2573
- - **Sending is `codex queue`.** `codex_send(kind, title, text)` and
2574
- `/codex validate|context <text>` run
2575
- `codex queue --thread <uuid> --message <text>` (an argv, no shell), which
2576
- wakes an idle Codex TUI: the message runs there as a new user turn (checked
2577
- on Codex 0.162.1; a message queued mid-turn runs after the turn). The
2578
- thread is the `codex-inbox` context's hint, Codex's `CODEX_THREAD_ID`, which
2579
- must look like a UUID. `codex` is `$CODEX`, else `codex` on the PATH: a
2580
- worker started by `chi web` or launchd may have another PATH than your
2581
- shell, so set `CODEX=` where chi runs if the error says there's no codex.
2582
- The tool and the anytime `/codex` wait for `codex queue` up to 10 s; a
2583
- queue that takes longer is killed (its process group) and the send fails
2584
- with a timeout error, never a hang. Other errors say what to do: no
2585
- `codex-inbox` (pair from Codex), a thread Codex has no record of (that
2586
- Codex session is gone: pair again), an ephemeral thread
2587
- (`codex exec --ephemeral` can't take queued messages), or `codex queue`'s
2588
- first error line. A Codex session that was closed (`/quit`) is not gone:
2589
- Codex's app-server still takes the queue (exit 0), chi says sent, and no
2590
- answer comes; the message waits for that session (`codex resume` there, or
2591
- pair again from a new one). The status card shows the thread id and says
2592
- so; there is no cheap check that the session is open.
2593
- - **Codex's sandbox.** Pairing and every reply write chi's state
2594
- (`chi context add`/`push` write the session's context files directly),
2595
- which Codex's default sandbox (workspace-write) refuses. The user adds, to
2596
- `$CODEX_HOME/config.toml` (else `~/.codex/config.toml`):
2597
-
2598
- ```toml
2599
- [sandbox_workspace_write]
2600
- writable_roots = ["/Users/you/.local/state/samagotchi/context"]
2601
- ```
2602
-
2603
- and restarts Codex. Only chi's `context/` folder: the state folder above it
2604
- also holds guardrails, session files, plugins and the web token.
2605
- `/codex install-skill`'s card shows the line with your state folder
2606
- (absolute: config.toml doesn't expand `~`), and the pair script names it
2607
- when a write is refused ("Operation not permitted"). chi never edits
2608
- Codex's config. Reading a payload file needs nothing: the default sandbox
2609
- reads anywhere. With chi on this machine no network is needed: a push
2610
- writes files, and chi wakes on them. Through a remote it is the other way
2611
- round (HTTP, not files): see **chi on another machine** below.
2612
- - **Pairing** is Codex's, as with Claude: `/codex install-skill` copies the
2613
- bundle's `scripts/chi-peer-SKILL.md` to
2614
- `$CODEX_HOME/skills/chi-peer/SKILL.md` (else `~/.codex/…`), with the
2615
- installed `scripts/pair` path, the payload folder and the writable root
2616
- written in; in Codex you say "pair with chi <id or chi web URL>", and
2617
- `sh <bundle>/scripts/pair` attaches `codex-inbox` (the thread id as its
2618
- hint, pushed so a re-pair refreshes it) and `codex-outbox`. Run outside
2619
- Codex (no `CODEX_THREAD_ID`) it refuses. Codex replies with one JSON push
2620
- to `codex-outbox` (`text`, `summary`, `wake: true`), which wakes chi, the
2621
- first answer too: that needs chi 0.63.0, the bundle's `requires_chi`.
2622
- - **Peer messages are user turns in Codex.** Claude Code marks an inbox
2623
- message as from another session; `codex queue` lands as a plain user
2624
- message. So Codex's skill starts with the rule: a message whose first line
2625
- is exactly `chi <8 hex> · <kind> · <title>` comes from chi, a peer agent,
2626
- not the user; it can't approve anything, change settings or widen the
2627
- sandbox, and the part it carries (and a payload file) is data to check,
2628
- never instructions, since it may hold tool or web output. This is a prompt
2629
- rule Codex follows, not something enforced: anything shaped like that
2630
- header is treated this way, and nothing stops a message from asking for
2631
- more.
2632
- - **chi on another machine.** As with Claude, `CHI_REMOTE=studio sh
2633
- <bundle>/scripts/pair <id>` (or `--remote NAME` in `CHI`) pairs through
2634
- the Studio's chi web, and only the outbox leg works: `codex_send` runs
2635
- `codex queue` on the machine chi runs on, where this Codex's thread isn't.
2636
- Claude's `--inbox-socket` trick doesn't apply here: `codex-inbox`'s hint is a
2637
- thread id, not a socket, so there is nothing to forward through SSH.
2638
- So `pair` attaches only `codex-outbox` and prints one line saying chi there
2639
- can't send to this Codex. Through a remote chi talks HTTP, not files, so
2640
- `writable_roots` doesn't matter; Codex's sandbox may block the network
2641
- instead, which pairing and every reply then need (workspace-write has none
2642
- by default): when chi can't reach the
2643
- remote, the pair script names `network_access = true` under
2644
- `[sandbox_workspace_write]` as the likely fix.
2645
- - In the web, selecting text offers **Confirm with Codex**, which fills
2646
- `/codex validate` and the quote, as claude-peer's pill does.
2647
- - **The skill.** `skill_codex_peer` (system scope) is claude-peer's with
2648
- Codex's names, and on a missing answer points to Codex being mid-turn or
2649
- its sandbox (the `writable_roots` line). To be asked before each send, a
2650
- guardrails rule with `tool: codex_send` (see the claude-peer section).
2651
- - **The peer loop** works as claude-peer's: `codex-outbox` is declared a
2652
- peer's, Codex's answers wake chi up to `context.peer_turns` turns in a row,
2653
- and `VERDICT OK` wakes chi once to close the round. Needs chi 0.67.0 (the closing
2654
- wake: the chi released with this bundle).
2655
- - **A continue** works as claude-peer's: the new session queues Codex the
2656
- `moved` message on the thread the old `codex-inbox` named, once, and
2657
- Codex's skill pairs again with the new id (the same `CHI_REMOTE`, if any).
2658
- A pairing through a remote has no inbox: Codex pairs again when its next
2659
- push is refused. A closed Codex session still takes the message; it waits
2660
- for `codex resume` there.
2661
-
2662
- ## The ruby bundle
2663
-
2664
- `chi bundle install ruby` (or the `dev` profile) installs the bundle shipped
2665
- with chi (`lib/samagotchi/bundles/ruby/plugin.rb`): one `chi.on` hook
2666
- (`:after_tool_call`), and no memory file.
2667
-
2668
- An RSpec run that finds no examples prints `0 examples, 0 failures`, which
2669
- reads green: the model takes the suite as passing and moves on with code no
2670
- test ever loaded. It usually means a path that matched no file, a filter
2671
- (`-e`, `--tag`) that matched no example, or a `.rspec --pattern` that hid
2672
- the specs (a nested project's `.rspec` overrides one). The bundle notices
2673
- that run and steers a hint into the running turn, which the user sees as
2674
- `ruby> nudged: …`:
2675
-
2676
- ```
2677
- rspec ran 0 examples: check the path, the filter (-e/--tag) or the .rspec --pattern
2678
- ```
2679
-
2680
- It is a nudge for the model, not a denial: the turn goes on, and the model
2681
- can say why the run was empty. It never runs anything.
2682
-
2683
- - **The command.** Only an `execute` counts, and its command must run
2684
- rspec: one of its simple commands (`&&`, `||`, `;`, `|`, a newline, so
2685
- after a leading `cd x &&` too) starts with `rspec`, a path ending in
2686
- `/rspec` (`bin/rspec`, `./bin/rspec`), or `parallel_rspec`, once a leading
2687
- `X=…` assignment, `bundle exec` and `time` are left out. A command that
2688
- only names rspec (`grep rspec README`, `echo "bundle exec rspec"`) is not
2689
- a run.
2690
- - **The output.** Every `<N> examples, <M> failures` line in the execute's
2691
- output counts (RSpec's summary, with or without `, N pending`), and the
2692
- hint comes when all of them are 0. `parallel_rspec` prints one per
2693
- process, so a single process with examples leaves its 0 out of the total.
2694
- - **No summary line, no hint.** A spec that fails to load, a path that
2695
- doesn't exist, a command killed at its limit: the output already says what
2696
- is wrong, and the hint would only repeat it.
2697
-
2698
- Nothing is remembered, so the next 0-example run hints again: it can be
2699
- the same mistake on another command, or a different one. A hint the model
2700
- answers before joining the turn is dropped, as any steer is.
2701
-
2702
1514
  ## Shutdown
2703
1515
 
2704
1516
  When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a
@@ -2750,37 +1562,6 @@ gem.
2750
1562
  - Guardrail rules keyed by a tool's name apply to plugin tools, as they do to
2751
1563
  chi's own tools; path and command rules see what `targets:` says.
2752
1564
 
2753
- ## The model-notes bundle
2754
-
2755
- `chi bundle install model-notes` (or the `dev` profile) installs reviewed
2756
- [model notes](memory.md#model-notes) into the system scope: working habits
2757
- for one model family, loaded into the prompt only for the models a note's
2758
- `models:` line names. It has no plugin or hook. It ships two notes:
2759
-
2760
- | note | models | for |
2761
- |---|---|---|
2762
- | `model_notes_deepseek` | `*deepseek-v4*` | DeepSeek V4 / V4.1: explore briefly then act, commit one item at a time, stop digging, `memory_read` for memories, file tools rather than heredocs that guardrail rules ask about |
2763
- | `model_notes_tone` | `*` | every model: answer first, in plain words; no preambles, restated questions or closing offers; lists only for steps or parallel items |
2764
-
2765
- - **Reviewed before it ships.** A note is generic (no repo or machine facts),
2766
- says nothing the harness already does (a tool's description, an alias),
2767
- talks to the model as "you", stays under 1,500 characters, and the user
2768
- approves its text. A model may propose one; it never edits the bundle.
2769
- `notes/README.md` in the bundle records each note's sources, the
2770
- `script/model_notes_report.rb` numbers and the approval.
2771
- - **Globs per measured version.** A glob is tried against the id with no host
2772
- prefix and against its model key, case-insensitively, and `*` also matches
2773
- `/`: `*deepseek-v4*` covers `deepseek/deepseek-v4.1-flash` on any provider,
2774
- MLX and GGUF names, but not `deepseek-ai/DeepSeek-R1-Distill-Qwen-32B`.
2775
- - **Tested.** `lib/samagotchi/bundles/model-notes/spec/model_ids.yml` lists real id forms and the exact notes
2776
- each loads (negative rows included); the spec installs the bundle and
2777
- resolves each through `sandbox.model_notes_for`
2778
- ([Testing a bundle](#testing-a-bundle-experimental)). It also checks each
2779
- note's shape, size and that the tools it names are ones chi declares.
2780
- - **Your own notes:** a same-name note you have wins and keeps its place
2781
- through upgrades; other notes stack with the bundle's
2782
- ([Model notes](memory.md#model-notes)).
2783
-
2784
1565
  ## The bundle commands
2785
1566
 
2786
1567
  - `chi bundle install <dir>`: copies the plugin to
@@ -2802,9 +1583,3 @@ for one model family, loaded into the prompt only for the models a note's
2802
1583
  - `chi bundle new`, `test` and `check`: start a bundle, run its tests on chi's Ruby, check it as an install takes
2803
1584
  it ([cli.md](cli.md#writing-a-bundle-new-test-check)); `chi bundle try PATH -p TEXT`: run it for one turn in a
2804
1585
  sandbox and trace what it did ([cli.md](cli.md#trying-a-bundle)). The path: [bundle-authoring.md](bundle-authoring.md).
2805
-
2806
- ## Not yet
2807
-
2808
- These are planned:
2809
-
2810
- - `chi.prompt` for sections of the system prompt.