ctxbin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 superlucky84
+
+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.

package/README.md

@@ -0,0 +1,133 @@
+# ctxbin
+
+Minimal, deterministic CLI to save and load **context**, **agents**, and **skills** in Upstash Redis hashes.
+It is designed for fast handoff between AI agents working on the same repo/branch,
+with branch-based context keys inferred inside git repositories.
+
+> **Core idea:** ctxbin exists to make AI-agent handoffs reliable and repeatable.
+
+## Agent workflow (core)
+This is the most important usage. Paste the add-on into your agent instruction file
+so agents consistently save and load branch context.
+
+- Add: [`agent-addon.md`](agent-addon.md) → copy the block into your project's agent instruction file
+  (e.g. `AGENT.md`, `CLAUDE.md`, or any equivalent).
+- Then you can simply ask:
+  - “Use ctxbin to save the current context.”
+  - “Use ctxbin to load the current context.”
+
+The add-on tells agents how to format context (summary, next steps, decisions) and how to use
+`ctxbin ctx save/load` correctly.
+
+## Features
+- Branch-scoped `ctx` keys (auto-inferred from git repo + branch)
+- `agent` and `skill` storage for reusable prompts and workflows
+- `skillpack`: tar.gz + Base64 directory bundles (deterministic)
+- `skillref`: GitHub directory reference (default branch or pinned commit)
+- `list` command with type mapping (`--value`, `--dir`, `--url`)
+
+## Install
+Recommended (no install):
+```bash
+npx ctxbin --version
+```
+
+Or add it to your toolchain:
+```bash
+pnpm add -g ctxbin
+```
+
+## Upstash requirement
+ctxbin stores data in **Upstash Redis**. You need an Upstash database and its REST URL/token.
+
+- Create a database at: https://upstash.com/
+- Use the REST URL and token as `CTXBIN_STORE_URL` / `CTXBIN_STORE_TOKEN`
+
+## Configure storage
+Use environment variables (recommended):
+```bash
+export CTXBIN_STORE_URL="https://..."
+export CTXBIN_STORE_TOKEN="..."
+```
+
+Or create `~/.ctxbin/config.json` via interactive init:
+```bash
+npx ctxbin init
+```
+
+## Quick usage
+### ctx (branch-scoped, key optional in git repos)
+```bash
+ctxbin ctx save --value "summary / next steps"
+ctxbin ctx load
+ctxbin ctx list
+ctxbin ctx delete
+```
+
+When the key is omitted, ctxbin infers it **only inside a git repository**:
+```
+key = {project}/{branch}
+project = git repository root directory name
+branch  = git rev-parse --abbrev-ref HEAD
+```
+
+Explicit key example (useful outside git repos; not recommended for normal use):
+```bash
+ctxbin ctx save my-project/main --value "summary / next steps"
+ctxbin ctx load my-project/main
+ctxbin ctx delete my-project/main
+```
+
+### agent (string-only)
+```bash
+ctxbin agent save reviewer --value "# Agent role"
+ctxbin agent load reviewer
+ctxbin agent list
+ctxbin agent delete reviewer
+```
+
+### skill (string, skillpack, or skillref)
+```bash
+ctxbin skill save my-skill --value "# Skill markdown"
+ctxbin skill load my-skill
+ctxbin skill list
+ctxbin skill delete my-skill
+```
+
+Skillpack (directory bundle):
+```bash
+ctxbin skill save fp-pack --dir ./skills/fp-pack
+ctxbin skill load fp-pack --dir ./tmp/fp-pack
+```
+
+Skillref (GitHub directory reference):
+```bash
+# Track default branch
+ctxbin skill save fp-pack \
+  --url https://github.com/OWNER/REPO \
+  --path skills/fp-pack
+
+# Pin to a commit
+ctxbin skill save fp-pack \
+  --url https://github.com/OWNER/REPO \
+  --ref <40-hex-commit-sha> \
+  --path skills/fp-pack
+```
+
+> `skill load` for skillpack/skillref requires `--dir`.
+
+## Built-in guidance
+Print the bundled ctxbin skill text (built-in):
+```bash
+npx ctxbin skill load ctxbin
+```
+
+## Development
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+## License
+MIT

package/agent-addon.md

@@ -0,0 +1,47 @@
+# ctxbin Agent Add‑On
+
+Copy/paste the block between the markers below into your AGENT.md / CLAUDE.md.
+
+<!-- BEGIN CTXBIN AGENT ADDON -->
+
+## ctxbin (Context Persistence)
+
+Use `ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
+> Tip: `npx ctxbin skill load ctxbin` prints the bundled ctxbin skill text
+> so agents can reference the full ctxbin guidance.
+
+### How ctx keys are inferred (when key is omitted)
+```
+key = {project}/{branch}
+project = git repository root directory name
+branch  = git rev-parse --abbrev-ref HEAD
+```
+
+### Save context (preferred)
+```bash
+ctxbin ctx save --value "<summary + next steps + decisions>"
+```
+
+### Save via stdin
+```bash
+echo "<context>" | ctxbin ctx save
+```
+
+### Load context
+```bash
+ctxbin ctx load
+```
+
+### What to include in ctx
+- What changed (summary)
+- What remains (next steps)
+- Completed vs remaining checklist items
+- Important decisions/constraints
+- Files touched and why
+- Failing tests or warnings
+
+### Do not
+- Don’t store secrets
+- Don’t overwrite with trivial messages
+
+<!-- END CTXBIN AGENT ADDON -->

package/dist/agent-addon.md

@@ -0,0 +1,47 @@
+# ctxbin Agent Add‑On
+
+Copy/paste the block between the markers below into your AGENT.md / CLAUDE.md.
+
+<!-- BEGIN CTXBIN AGENT ADDON -->
+
+## ctxbin (Context Persistence)
+
+Use `ctxbin ctx save` to store **branch‑scoped context** so the next agent can continue without re‑explanation.
+> Tip: `npx ctxbin skill load ctxbin` prints the bundled ctxbin skill text
+> so agents can reference the full ctxbin guidance.
+
+### How ctx keys are inferred (when key is omitted)
+```
+key = {project}/{branch}
+project = git repository root directory name
+branch  = git rev-parse --abbrev-ref HEAD
+```
+
+### Save context (preferred)
+```bash
+ctxbin ctx save --value "<summary + next steps + decisions>"
+```
+
+### Save via stdin
+```bash
+echo "<context>" | ctxbin ctx save
+```
+
+### Load context
+```bash
+ctxbin ctx load
+```
+
+### What to include in ctx
+- What changed (summary)
+- What remains (next steps)
+- Completed vs remaining checklist items
+- Important decisions/constraints
+- Files touched and why
+- Failing tests or warnings
+
+### Do not
+- Don’t store secrets
+- Don’t overwrite with trivial messages
+
+<!-- END CTXBIN AGENT ADDON -->