samagotchi 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da62382ff837576724b356e7ac03ccb484c382628b4a3a7fcfaacf799de4cc92
+  data.tar.gz: 2822682cf66025598dbb6effc4598f97b3658fec0153cfcfaf5088a7385764dd
+SHA512:
+  metadata.gz: 860855c62b763f58c44d06e137f8f45abceb81e4e8169c5c46182b69ae00442cc44c285c056e79120ce2b5a6ef2516c3e7fb75739188b650fc6c918644f25796
+  data.tar.gz: 429c0f7b9fc76def59cd87a9493bddaca7813d38f73f8ce974616f9f55af89767aca8b7f9b2cd629b8e0a7fe606e98eee05ee52199a74ec6d3d13c00f23c2e82

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to samagotchi (the `chi` command) are listed here. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+versions follow [Semantic Versioning](https://semver.org/); before 1.0, config
+and commands may change between minor versions. How releases are made:
+[docs/releasing.md](docs/releasing.md).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-27
+
+The first public release. chi is an agent harness for local models
+(llama.cpp, mlx-lm, oMLX) and OpenAI-compatible servers, built around memory
+and long-lived sessions.
+
+### Added
+
+- One session, three UIs: the terminal REPL, an attached terminal and a web UI
+  (`chi web`) join the same session and see the same turn live; a session keeps
+  running in a background worker when you detach (`chi --attach ID` comes back).
+- Saved sessions (`chi sessions list`, `chi --resume ID`) and a short recap of
+  what happened when you come back to one.
+- Memory in plain Markdown files, per project and system-wide, with
+  model-specific overlays; memory bundles to share and upgrade them
+  (`chi bundle install`, `chi bundle list`, `chi bundle upgrade`).
+- Plugins (commands, tools, cards, hooks) and an MCP bundle that brings in the
+  tools of MCP servers; shipped plugins: `btw` (a side question mid-turn),
+  `loop-guard` and `mcp`.
+- Guardrails: every tool call can be allowed, denied or asked about first, with
+  approvals per session, repo or rule; `chi bundle install guardrails` adds a
+  default set.
+- `delegate`: the model hands a task to a child session that runs in parallel
+  and reports back.
+- Images: `@shot.png` in a prompt, or a pasted or dropped image in the web UI,
+  for models that can see them.
+- `chi note` (background context for a session, no turn) and `chi send` (a
+  message into a session, which wakes it if it was stopped).
+- A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
+  hotkey panel that send selected text or the clipboard to your sessions.
+
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/dm1try/samagotchi/releases/tag/v0.2.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Dedov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# samagotchi
+
+An agent harness that relies heavily on memory. Samagotchi is the engine; chi
+(pronounced "chee") is its short name and CLI command.
+
+> **Pre-1.0:** config and commands may change between minor versions (0.2 →
+> 0.3); the [CHANGELOG](CHANGELOG.md) says what changed. chi is used daily and
+> stable.
+
+## Requirements
+
+- Ruby 3.3+
+- A model server: [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server`
+  by default; mlx-lm, oMLX and OpenAI-compatible servers also work
+  (see [Configuration](docs/configuration.md#model-server-transport))
+
+## Install
+
+```sh
+gem install samagotchi
+chi self            # version, source dir, config and memory paths
+```
+
+### From source
+
+```sh
+git clone https://github.com/dm1try/samagotchi && cd samagotchi
+bundle install
+bin/chi self
+```
+
+`bin/chi` runs the checkout; `bundle exec rake gem:install` installs it as a
+local gem, which puts `chi` on your PATH.
+
+## Configure
+
+Create `~/.config/samagotchi/config.yml` (or `$XDG_CONFIG_HOME/samagotchi/config.yml`):
+
+```yaml
+default:
+  model: gemma4            # the model id your server serves (required)
+server:
+  host: localhost
+  port: 8080
+```
+
+Other settings (multiple hosts, transports, timeouts, the idle recap) are in
+[Configuration](docs/configuration.md).
+
+## Use
+
+```sh
+chi                                       # interactive session the web UI can join too
+chi --no-shared                           # the plain in-process REPL
+chi -p "explain lib/" --non-interactive   # one turn, print the answer, exit
+chi --resume <session-id>                 # continue a saved session
+chi web --open                            # web UI: this project's sessions (--scope=all: every one)
+chi sessions list                         # this project's saved sessions (--scope=all: every one)
+pbpaste | chi note --source slack <id>    # background context for a session (no turn)
+pbpaste | chi send -m "same bug?" <id>    # a message to a session, the clipboard quoted above it
+```
+
+`@shot.png` in a prompt (or a pasted/dropped image in the web UI) shows the model an image, when it can see them; see [Images](docs/cli.md#images).
+
+`/model` switches models, Ctrl-C cancels a turn, and Ctrl-D or `/detach` detaches (the session keeps running; `chi --attach ID` comes back). `/exit` detaches and stops the session's worker too, unless something still needs it (a running turn, another UI); `chi --resume ID` picks the conversation up again. `/exit --delete` also deletes the session once the worker has gone; `chi sessions delete ID` deletes one from the shell.
+
+### Context notes
+
+`chi note` pushes text into one or more sessions as background, not as a
+prompt: nothing runs, and the model sees it on its next turn framed as a note
+(`[CONTEXT NOTE from slack, 14:02] … [END NOTE]`) that it uses when relevant and
+never takes orders from. The web and the attached terminal show it as a dim
+"note from …" line. `chi sessions list --live --scope=all --format tsv` lists the sessions
+a note reaches (`id<TAB>description`). Agents can do the same: `list_sessions`
+finds another session, `send_note` tells it something, and `delegate` hands a
+task to a child session that runs in parallel and reports back only its final
+reply (a normal session: `chi --attach <id>` steers it).
+
+`chi send` is the other half: the text goes in as your message, the same as
+typing it in the attached terminal or the web composer, and a turn runs. Piped
+stdin plus `-m` puts the stdin above the message as a `>` quote.
+
+### Send to chi (macOS)
+
+`chi desktop install` builds a small native helper: select text in any app →
+Services → **Send to chi** (or ⌃⌥⌘N with the clipboard) → pick sessions in a
+Spotlight-like panel → ⏎ sends it quoted under your question as a message, ⌘⏎ as a
+context note. It needs the
+Command Line Tools. See [Desktop helper](docs/desktop.md).
+
+### Guardrails
+
+Every tool call the model makes can be allowed, denied, or put to you first.
+Rules come from `config.yml` (`guardrails:`), installed bundles and hooks;
+`chi bundle install guardrails` adds a default set (asks before `git push`,
+history rewrites, wide `rm -rf`, `curl | sh`, writes outside the repo; denies
+writes to `.git/hooks`). You answer in the REPL, the attached TUI or the web:
+once, for the session, for the repo, or for the whole rule in the repo.
+`/guardrails` lists the rules and your approvals. See [Guardrails](docs/guardrails.md).
+
+## Documentation
+
+- [CHANGELOG](CHANGELOG.md): what changed in each release
+- [Releasing](docs/releasing.md): versions, the changelog, how a release is published
+
+- [CLI and REPL](docs/cli.md): flags, sharing a session, web UI, `/model`, status line
+- [Configuration](docs/configuration.md): `config.yml`, hosts, model server transports, timeouts, retries, logs
+- [Memory](docs/memory.md): scopes and model-specific overlays
+- [Sessions](docs/sessions.md): storage, retention, `chi sessions`
+- [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey
+- [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals
+- [Hooks](docs/hooks.md): plugin hooks and bundle hooks
+- [Plugins](docs/plugins.md): bundle plugins (commands, tools, hooks)
+- [Architecture](docs/architecture.md): Engine, TerminalUI, bridge, web
+- Internals: [Gemma 4 contract](docs/internals/gemma4-contract.md), [context telemetry](docs/internals/context-telemetry.md), [tool output limits](docs/internals/tool-guardrails.md), [background tasks](docs/internals/background-tasks.md)
+
+## Development
+
+```sh
+bundle exec rspec    # Ruby specs
+npm test             # web frontend specs
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).