{"id":47692173,"url":"https://github.com/kajogo777/bento","last_synced_at":"2026-04-26T15:00:48.349Z","repository":{"id":347359642,"uuid":"1193302891","full_name":"kajogo777/bento","owner":"kajogo777","description":"Checkpoint everything git misses in AI agent workspaces. Save, fork, push to any OCI registry.","archived":false,"fork":false,"pushed_at":"2026-04-12T02:36:22.000Z","size":4389,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T04:24:19.106Z","etag":null,"topics":["ai-agents","checkpoint","coding-agents","developer-tools","docker","go","mcp","oci","oras","workspace-management"],"latest_commit_sha":null,"homepage":"https://georgebuilds.dev/blog/bento","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kajogo777.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-27T04:38:26.000Z","updated_at":"2026-04-12T02:36:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kajogo777/bento","commit_stats":null,"previous_names":["kajogo777/bento"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/kajogo777/bento","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kajogo777%2Fbento","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kajogo777%2Fbento/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kajogo777%2Fbento/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kajogo777%2Fbento/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kajogo777","download_url":"https://codeload.github.com/kajogo777/bento/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kajogo777%2Fbento/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32301330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","checkpoint","coding-agents","developer-tools","docker","go","mcp","oci","oras","workspace-management"],"created_at":"2026-04-02T15:47:18.033Z","updated_at":"2026-04-26T15:00:48.328Z","avatar_url":"https://github.com/kajogo777.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍱 bento\n\n\u003e **Warning:** This project is under heavy development. Expect breaking changes to the CLI, configuration format, and artifact structure between releases.\n\n**Portable agent workspaces. Pack, ship, resume.**\n\n![bento demo](docs/demo.gif)\n\nBento packages AI agent workspace state into portable, layered OCI artifacts. Save a checkpoint of your code, agent memory, and dependencies. Push it to any container registry. Open it anywhere.\n\nWorks with any agent. Works on macOS, Linux, and Windows. Works offline. One binary.\n\n```bash\nbento init                          # start tracking a workspace\nbento save -m \"auth module done\"    # checkpoint\nbento open cp-3                     # restore (backs up current state first)\nbento open undo                     # undo the last open\nbento open cp-1 ~/workspace-b      # parallel workspace (like git worktrees)\nbento push                          # share via registry\n```\n\n## The Problem\n\nAI coding agents checkpoint code via git, but lose everything else when the session ends: installed dependencies, agent memory, tool configurations, build caches, conversation history.\n\nGit tracks your source code. **Bento tracks everything git doesn't.**\n\n## How It Works\n\nEach `bento save` captures your workspace as a **bento workspace**, a portable OCI artifact containing your files, agent state, and dependencies organized into layers:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/bento-artifact.svg\" alt=\"Bento workspace structure\" width=\"600\"\u003e\n\u003c/p\u003e\n\nLayers that haven't changed share digests and aren't re-uploaded. Your 200MB `node_modules` is stored once, not once per checkpoint.\n\nEach checkpoint also stores workspace metadata: environment variables, secret references (resolved on demand, never stored), the git repos the workspace depends on (branch, sha, remote for each), active extensions, and the OS/arch it was created on. This makes checkpoints self-describing so `bento open` on a new machine knows what the workspace needs.\n\n## Install\n\n```bash\n# macOS / Linux (Homebrew)\nbrew tap kajogo777/bento https://github.com/kajogo777/bento\nbrew install kajogo777/bento/bento\n\n# Upgrade\nbrew upgrade kajogo777/bento/bento\n\n# From source\ngo install github.com/kajogo777/bento@latest\n\n# Or download a binary from GitHub Releases\n# https://github.com/kajogo777/bento/releases\n```\n\n\u003e **Note:** A different `bento` package exists in homebrew-core. Always use the fully-qualified `kajogo777/bento/bento` to get the right one.\n\n## Quick Start\n\n```bash\ncd my-project\nbento init\n# Detected agent: claude-code\n\nbento save -m \"refactored auth module\"\n# Scanning workspace...\n#   deps:     1204 files, 89MB (unchanged, reusing)\n#   agent:    8 files, 64KB (changed)\n#   project:  42 files, 128KB (changed)\n# Tagged: cp-1, latest\n\n# Keep working, save more checkpoints...\nbento save -m \"added tests\"\n# Tagged: cp-2, latest\n\n# Something went wrong? Restore an earlier checkpoint\nbento open cp-1\n# To undo: bento open undo\n\n# Parallel workspaces — agents work independently from the same checkpoint\nbento open cp-1 ~/workspace-a\nbento open cp-1 ~/workspace-b\n\n# Push to a registry\nbento push ghcr.io/myorg/workspaces/my-project\n```\n\n## Core Concepts\n\n### Checkpoints\n\nImmutable, content-addressed snapshots of your workspace. Each directory tracks its own position via a `head` field in `bento.yaml`, enabling parallel workspaces like git worktrees. Checkpoints form a DAG through parent references:\n\n```\ncp-1 → cp-2 → cp-3 → cp-4 (workspace A)\n          ↘→ cp-5 → cp-6 (workspace B)\n```\n\n### Layers\n\nThree core layers, ordered bottom to top:\n\n| Layer | Contents | Change frequency |\n|-------|----------|-----------------|\n| **deps** | Installed packages, build caches | Rarely |\n| **agent** | Agent memory, plans, skills, commands | Often |\n| **project** | Everything else (source, tests, configs, binaries) | Often |\n\nThe project layer is a catch-all. Any workspace file not matched by agent or deps patterns is captured here.\n\nUnchanged layers are deduplicated automatically. Custom layers can be defined in `bento.yaml`.\n\n### Auto-Detection\n\nBento uses composable **extensions** that auto-detect agents, languages, and tools in your workspace on every `save` and `diff`. If you add a new agent or framework mid-project, bento picks it up automatically.\n\n```bash\nbento init\n# Detected extensions: claude-code, agents-md, node\n\n# Later, start using Codex too...\nbento save -m \"multi-agent\"\n# Detected extensions: claude-code, codex, agents-md, node\n```\n\nEach extension contributes patterns to the right layer. Multiple extensions merge naturally -- their patterns are unioned into the same layer. Extensions capture a superset of all known storage paths across agent versions, so state is never silently missed when a user runs an older or newer release. Directories that do not exist on disk cost nothing (no files matched = no bytes in the layer).\n\nBuilt-in agent extensions: **Claude Code**, **Codex**, **OpenCode**, **OpenClaw**, **Cursor**, **Stakpak**, **AGENTS.md** (cross-agent).\nBuilt-in deps extensions: **Node** (npm, yarn, pnpm, bun, deno), **Python** (pip, uv, pipenv, poetry), **Go**, **Rust**, **Ruby**, **Elixir**, **OCaml**.\nBuilt-in tool extensions: **tool-versions** (asdf / mise).\n\nDefine custom layers in `bento.yaml` for unsupported agents. Patterns starting with `~/` or `/` capture files from outside the workspace:\n\n```yaml\nlayers:\n  - name: deps\n    patterns: [\".venv/**\", \"~/.cache/pip/\"]\n  - name: agent\n    patterns: [\".my-agent/**\", \"~/.my-agent/sessions/\"]\n  - name: project\n    patterns: [\"**\"]\n```\n\n### Hooks\n\nOptional shell commands at lifecycle points:\n\n```yaml\nhooks:\n  pre_save: \"make clean-temp\"\n  post_restore: \"make setup\"\n  pre_push: \"npm test\"\n```\n\nPre-hooks abort the operation on failure. Post-hooks warn but continue.\n\n### Watch Mode\n\n`bento watch` runs a background file-system watcher that automatically creates checkpoints as you work:\n\n```bash\nbento watch                          # start watching (Ctrl-C to stop)\nbento watch --debounce 5 -m \"wip\"   # 5s quiet period, custom message\n```\n\nEach layer is monitored according to its watch method:\n\n| Layer | Watch | Behavior |\n|-------|-------|----------|\n| **project** | `realtime` | Instant detection via fsnotify |\n| **deps** | `periodic` | Checked every ~30s (avoids FD exhaustion on large dirs) |\n| **agent** | `periodic` | Checked every ~30s |\n\nUnchanged saves are skipped automatically. Old checkpoints are pruned via tiered retention (full granularity for the last hour, hourly for 24h, daily for 7d).\n\nOverride watch methods per layer in `bento.yaml`:\n\n```yaml\nlayers:\n  - name: build-cache\n    patterns: [\"dist/**\"]\n    watch: off             # don't trigger saves on build output\n```\n\n### Secrets\n\nBento never stores secrets. It stores references that are resolved on demand:\n\n```yaml\nenv:\n  NODE_ENV: development\n  DATABASE_URL:\n    source: env\n    var: DATABASE_URL\n  API_KEY:\n    source: file\n    path: /run/secrets/api-key\n```\n\nManage env vars and secrets from the CLI:\n\n```bash\nbento env set NODE_ENV development                           # plain env var\nbento env set DATABASE_URL --source env --var DATABASE_URL   # secret ref\nbento env show                                               # inspect config\nbento env export -o .env                                     # generate .env file\n```\n\nA pre-save scan powered by [gitleaks](https://github.com/zricethezav/gitleaks) (~200+ rules) catches credentials before they're stored. Files are scanned concurrently with a SHA256 cache so repeat saves skip unchanged files.\n\nTo suppress false positives, add a `.gitleaksignore` file to your workspace root with one fingerprint per line (`file:ruleID:line`). When a scan fails, bento prints the fingerprints in copy-pasteable format:\n\n```\nSecret scan found 3 potential secret(s):\n\n  .stakpak/session/cached-page.txt:generic-api-key:42\n  config/dev.env:aws-access-token:7\n  config/dev.env:private-key:15\n\nTo suppress false positives, copy the lines above into .gitleaksignore (one per line).\n```\n\n## Use Cases\n\n**[Resume where you left off.](docs/tutorials/resume-where-you-left-off.md)** Agent sessions lose context when they end. Save a checkpoint mid-task, come back days later, and `bento open` restores everything: code, deps, agent memory, build caches. No re-explaining context to your agent.\n\n**[Move workspaces between machines.](docs/tutorials/move-workspaces-between-machines.md)** Working locally but need a cloud VM with more power? `bento push` from your laptop, `bento open` on the remote. Same workflow moving between cloud providers, no rsync, no reinstalling deps.\n\n**[Undo agent mistakes.](docs/tutorials/undo-agent-mistakes.md)** An agent trashed your build cache or went off the rails. `bento open` auto-backs up before restoring, and `bento open undo` reverses it. Watch mode auto-checkpoints as you work so you can roll back to any point.\n\n**[Hand off between agents.](docs/tutorials/hand-off-between-agents.md)** Started with Claude Code, need Cursor for the frontend? Save a checkpoint and open it with a different agent. The new agent gets the full workspace state, not just the code.\n\n**[Portable sandboxes.](docs/tutorials/portable-sandboxes.md)** Save in E2B, open in Docker, push to Fly.io. Bento artifacts are standard OCI images, so any container registry works as transport and any OCI-compatible runtime can consume them.\n\n**[Parallel exploration.](docs/tutorials/parallel-exploration.md)** Fork the same checkpoint into multiple directories. Let different agents try different approaches independently. Compare results, keep the winner.\n\n**[Warm-start CI.](docs/tutorials/warm-start-ci.md)** Instead of cold-starting every agent CI run, pull a checkpoint with pre-installed deps and agent config. Agents start warm. Failed runs are saved as checkpoints for debugging.\n\n**[Share workspaces with teammates.](docs/tutorials/share-workspaces.md)** Push a checkpoint to a shared registry. Your teammate pulls it and gets your exact environment, not a recipe to rebuild it, but the actual state.\n\n**[Workspace templates.](docs/tutorials/workspace-templates.md)** Publish a \"starter\" checkpoint with scaffolded code, pre-installed deps, and pre-configured agent memory. New projects start ready to go.\n\n**[Audit agent work.](docs/tutorials/audit-agent-work.md)** Every checkpoint is an immutable snapshot. `bento diff cp-3 cp-5` shows what changed across code, deps, and agent state, not just code diffs.\n\n## CLI Reference\n\n```\nbento init [--task \u003cdesc\u003e]                    Initialize workspace tracking\nbento save [-m \u003cmessage\u003e] [--tag \u003ctag\u003e]       Save a checkpoint\nbento open \u003cref\u003e [\u003ctarget-dir\u003e]               Restore a checkpoint (backs up current state first)\nbento open undo                               Undo the last open\nbento open --no-backup \u003cref\u003e                  Restore without backup\nbento list                                    List checkpoints\nbento diff [ref1] [ref2]                      Compare workspace or two checkpoints\nbento tag \u003cref\u003e \u003cnew-tag\u003e                     Tag a checkpoint\nbento inspect [ref]                           Show metadata and layer summary\nbento inspect [ref] --files                   Show metadata with file listing\nbento push [\u003cremote\u003e]                         Push to registry\nbento watch [-m \u003cmessage\u003e] [--debounce \u003cs\u003e]   Watch and auto-checkpoint on changes\nbento gc [--keep-last \u003cn\u003e] [--keep-tagged]    Clean up old checkpoints and blobs\nbento env show                                Show env vars and secret refs\nbento env set \u003ckey\u003e \u003cvalue\u003e                   Set a plain env var\nbento env set \u003ckey\u003e --source \u003csrc\u003e [flags]    Set a secret reference\nbento env unset \u003ckey\u003e                         Remove an env var or secret\nbento env export [-o \u003cfile\u003e] [--template t]   Export resolved .env file\n```\n\n## Configuration\n\n`bento.yaml` at your workspace root:\n\n```yaml\ntask: \"refactor auth module\"\n\nstore: ~/.bento/store\nremote: ghcr.io/myorg/workspaces\nhead: sha256:abc123...    # this directory's current checkpoint (managed by bento)\n\n# Optional: override auto-detected layers\n# layers:\n#   - name: deps\n#     patterns: [\"node_modules/**\", \".venv/**\"]\n#   - name: agent\n#     patterns: [\".claude/**\", \"CLAUDE.md\", \"~/.claude/projects/*/\"]\n#   - name: project\n#     patterns: [\"**\"]\n\nenv:\n  NODE_ENV: development\n  DATABASE_URL:\n    source: env\n    var: DATABASE_URL\n\nignore:\n  - \"*.log\"\n  - \"tmp/\"\n\nhooks:\n  post_restore: \"make setup\"\n\nretention:\n  keep_last: 10\n  keep_tagged: true\n```\n\n## Artifact Format\n\nBento artifacts follow the [OCI Image Spec v1.1](https://github.com/opencontainers/image-spec). Each checkpoint is an OCI manifest with typed layer descriptors:\n\nBento uses standard OCI media types for native Docker compatibility:\n\n| Component | Media Type | Identified by |\n|-----------|-----------|--------------|\n| Config | `application/vnd.oci.image.config.v1+json` | - |\n| All layers | `application/vnd.oci.image.layer.v1.tar+gzip` | `org.opencontainers.image.title` annotation |\n| Artifact type | `application/vnd.bento.workspace.v1` | manifest `artifactType` field |\n\nThis means `COPY --from=\u003cbento-ref\u003e` works natively in Dockerfiles.\n\nFull format details in [SPEC.md](specs/SPEC.md).\n\n## Architecture\n\n```\n├── cmd/bento/            # entrypoint\n├── internal/\n│   ├── cli/              # cobra commands\n│   ├── workspace/        # scanning, layer packing, .bentoignore\n│   ├── registry/         # OCI image layout store\n│   ├── manifest/         # OCI manifest construction\n│   ├── secrets/          # scanning, hydration, .env population\n│   ├── extension/        # composable extensions (agent, deps, tool detection)\n│   ├── hooks/            # lifecycle hook execution\n│   └── policy/           # retention and GC\n```\n\n## Comparison\n\n| | git | Docker checkpoint | E2B pause | Bento |\n|---|---|---|---|---|\n| Tracks source code | yes | - | - | yes |\n| Tracks agent memory | - | - | yes | yes |\n| Tracks dependencies | - | yes | yes | yes |\n| Portable | yes | - | - | yes |\n| Deduplication | yes | - | - | yes |\n| Inspectable | yes | - | - | yes |\n| Branching | yes | - | - | yes |\n| Undo restore | yes | - | - | yes |\n| Parallel workspaces | yes (worktrees) | - | - | yes |\n| Docker interop | - | yes | - | yes |\n| Works offline | yes | yes | - | yes |\n| Open standard | yes | - | - | yes |\n\n## FAQ\n\n**Why not just use git?**\nGit doesn't track dependencies, agent memory, build caches, or conversation history. Bento tracks everything git doesn't.\n\n**Why not Docker commit / CRIU?**\nThose capture raw process memory: opaque, architecture-dependent, uninspectable. Bento captures semantic file layers you can inspect, diff, and partially restore.\n\n**Why OCI?**\nThe infrastructure exists. Every cloud runs an OCI registry. No new accounts or tools needed.\n\n**What about sandboxes?**\nBento makes workspaces portable across sandboxes. Save a checkpoint in one sandbox (E2B, Docker, Fly.io), open it in another. Move between providers based on cost, GPU availability, or region without rebuilding context.\n\n**Can I use this without an AI agent?**\nYes. Bento works on any directory.\n\n**Cross-platform?**\nYes. Checkpoints are portable across macOS, Linux, and Windows.\n\n## Roadmap\n\n- [x] Core CLI (init, save, open, list, diff, tag, inspect, gc)\n- [x] Local OCI store with shared blob deduplication\n- [x] Secret scanning and hydration\n- [x] Agent support:\n  - [x] Claude Code (with session capture)\n  - [x] Codex (with session capture)\n  - [x] OpenCode (with session capture)\n  - [x] OpenClaw (with session capture)\n  - [x] Cursor\n  - [x] Stakpak\n  - [ ] GitHub Copilot\n- [x] Remote registry push/pull\n- [ ] Store schemes (`oci://`, `file://`)\n- [ ] `bento attach` (OCI referrers for diffs, test results, logs)\n- [ ] MCP server (agents checkpoint themselves)\n- [x] `bento watch` (auto-checkpointing)\n- [x] Restorable open (`bento open undo`)\n- [x] Per-workspace head tracking (parallel workspaces)\n- [ ] Docker sandbox integration\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkajogo777%2Fbento","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkajogo777%2Fbento","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkajogo777%2Fbento/lists"}