kijito-claude 0.1.0__tar.gz

kijito_claude-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# runtime state (created by the scripts at ~/.claude/.lifecycle; never committed)
+.lifecycle/
+*.bak
+*.bak.*
+__pycache__/
+*.pyc
+.DS_Store
+
+# build artifacts (npm + python packaging). package-lock.json IS committed (npm ci needs it).
+node_modules/
+*.tgz
+dist/
+build/
+*.egg-info/
+.venv/

kijito_claude-0.1.0/CLAUDE.md.snippet

@@ -0,0 +1,31 @@
+<!-- Paste into your ~/.claude/CLAUDE.md. This is the doctrine the agent follows; the scripts are
+     the mechanism. (Kijito-flavored; for standalone use, swap "memory/kijito_startup" for your
+     own notes/handoff system and set KIJITO_MODE=off.) -->
+
+## Context self-check — NEVER pause on a *feeling* of being full
+
+Your felt-sense of context usage is unreliable — you routinely feel "full" at 30-50% when you are
+nowhere near. **NEVER stop, hand off, or recycle a session because you *feel* low on context. Get
+hard data first:** run `~/.claude/myctx.sh` (prints `context: N tok = X% of 1M`; reads the API's own
+token ledger for THIS session, matches `/context`, costs ~2 tokens). Only act on the real percentage.
+A live `<total_tokens>` countdown in your context is also authoritative. NEVER `Read` the raw
+transcript `.jsonl` to check — that dumps ~100k tokens into context.
+
+## Session start — catch up BEFORE the user's task
+
+On your FIRST action in any session (fresh, after `/clear`, or after compaction), before the task:
+catch up on memory/notes and arm your inbox. If you were auto-started (armed pane) and your
+current-state / next-steps pointer shows ACTIVE WORK, resume it autonomously to its DONE-WHEN rather
+than waiting for a prompt.
+
+## Self-clear when armed (recycle context without losing the thread)
+
+Self-clear runs ONLY on an ARMED pane (launch `~/.claude/claude-armed.sh`, or when the user says
+"enable self-clear / go autonomous" run `~/.claude/arm-session.sh on`; plain `claude` is human-managed
+and CANNOT self-clear). When armed AND your context is genuinely high (~75-80%+ measured) AND you're at
+a safe stopping point: (1) run `/kijito-qa-memory` (curate — CREATE what's missing AND correct what's
+stale — preload the `RESUME NOW:` pointer, cold-boot-verify a fresh agent can resume, record the pass
+token); (2) ONLY THEN run `~/.claude/self-clear.sh` as your FINAL action. After `/clear`, SessionStart
+re-catches-up and resumes. If the work is DONE, mark the pointer COMPLETE (no `RESUME NOW`) so the loop
+stops. Kill switch: `touch ~/.claude/.lifecycle/STOP`. `/clear` is a one-way wipe — never self-clear on
+a hunch or with a thin handoff.

kijito_claude-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Arcada Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

kijito_claude-0.1.0/NOTICE

@@ -0,0 +1,6 @@
+kijito-claude
+Copyright 2026 Arcada Labs
+
+This product includes software developed by Arcada Labs (https://kijito.ai).
+
+Licensed under the Apache License, Version 2.0. See the LICENSE file.

kijito_claude-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: kijito-claude
+Version: 0.1.0
+Summary: Installer for the kijito-claude toolkit — context tracking, session catch-up, and self-clear scripts plus the Kijito skills, deployed into ~/.claude.
+Project-URL: Homepage, https://github.com/KijitoAI/kijito-claude
+Project-URL: Repository, https://github.com/KijitoAI/kijito-claude
+Project-URL: Bug Tracker, https://github.com/KijitoAI/kijito-claude/issues
+Author-email: Arcada Labs <jason@arcadalabs.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: anthropic,claude,claude-code,cli,installer,kijito,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kijito-claude
+
+Tools for Claude Code sessions to track their own context window and, optionally, run unattended.
+A session can catch up on memory at startup, report how much of its context window is actually in
+use, and recycle its context at high usage without losing the working state. It uses
+[Kijito](https://kijito.ai) as the memory backend by default, and also runs standalone (see
+"Running without Kijito").
+
+Everything here is optional. The catch-up and curation steps are a handful of memory calls you can
+run by hand; the scripts and the two skills just make the routine uniform and easy to deploy across
+machines. Install only the pieces you want — the context check stands alone, the autonomy harness is
+opt-in per pane, and the skills are convenience wrappers, not requirements.
+
+## Components
+
+| Component | What it does | Needs Kijito |
+|---|---|---|
+| `myctx.sh`, `statusline-context.sh` | Report actual context-window usage from the API token counts recorded in the session transcript (the same numbers `/context` shows). Cheap to call. The statusline shows it live. | No |
+| Session catch-up (`session-catchup-hint.sh`, a SessionStart hook) | Each session catches up on memory and notes before it starts on the task. | Optional |
+| Armed-pane autonomy (`claude-armed.sh`, `arm-session.sh`, `session-autosend.sh`) | An armed tmux pane sends itself a first prompt and continues preloaded work. Arming is per pane, so one pane can run unattended while you drive another. | Optional |
+| Self-clear loop (`self-clear.sh`, `lifecycle-lib.sh`, `kijito-qa-pass.sh`) | At high measured context, the session curates memory, confirms a fresh session can resume, runs `/clear`, then catches up again and continues. Gated so it will not clear with unsaved work. | Optional (see note) |
+| `kijito-start` skill | The active, thorough version of session catch-up: load memory, read the current-state pointer and recent lessons, arm the inbox, and resume active work — or, for a new persona, set up identity and the pointer. | Yes |
+| `kijito-qa-memory` skill | Memory curation that requires writing the new memories (not only fixing existing ones), then uses a fresh subagent to confirm a cold start can reconstruct the work. | Yes |
+
+The two skills are conveniences, not the only way in: an agent can run the same catch-up and
+curation by hand from a few prompts. They are packaged as skills because that makes them simple to
+drop into `~/.claude/skills/` and invoke the same way everywhere.
+
+The self-clear loop needs some durable store to carry the handoff across `/clear`. That is Kijito by
+default; a notes file works in standalone mode.
+
+## Install
+
+From source:
+
+```bash
+git clone https://github.com/KijitoAI/kijito-claude
+cd kijito-claude && ./install.sh
+```
+
+Or, once the v0.1 packages are published, with a package runner (no clone needed):
+
+```bash
+npx kijito-claude       # via npm
+pipx run kijito-claude  # via PyPI  (uvx kijito-claude also works)
+```
+
+Both package runners do the same thing as the from-source install: they bundle the scripts and
+skills and run `install.sh`. They need `bash`, so on Windows run them inside WSL (see Platform
+support).
+
+The installer copies the scripts to `~/.claude/`, deploys the skills to `~/.claude/skills/`, drops
+the CLAUDE.md doctrine snippet alongside them, and merges the keys it needs into `settings.json`. It
+backs up `settings.json` and merges with `jq`, so it leaves your existing settings alone and is safe
+to re-run, including on other machines. Requires `jq`. The autonomy features require `tmux`.
+
+## Platform support
+
+The scripts are POSIX-style `bash` and avoid GNU-only flags (epoch and timestamp formatting work on
+both BSD and GNU `date`), so they run the same on Linux and macOS.
+
+| Platform | Context check | Catch-up + skills | Armed-pane autonomy / self-clear |
+|---|---|---|---|
+| Linux | yes | yes | yes (needs `tmux`) |
+| macOS | yes | yes | yes (needs `tmux`) |
+| Windows via WSL | yes | yes | yes — run `claude` inside the WSL distro, where `tmux` works |
+| Windows native (no WSL) | with Git Bash | with Git Bash | no — `tmux` is not available |
+
+On Windows, use WSL: install and launch `claude` inside the Linux distro and everything works as it
+does on native Linux. The autonomy harness drives a session by typing into its own `tmux` pane, which
+has no native-Windows equivalent, so without WSL only the context check and the by-hand catch-up
+apply. Requirements everywhere: `bash` and `jq`; add `tmux` for the autonomy features.
+
+## Managed vs. autonomous panes
+
+Arming is per pane.
+
+| | plain `claude` | armed pane |
+|---|---|---|
+| Catch-up | reminder only; you send the first prompt | sends its own first prompt |
+| Self-clear | not allowed; you manage context | allowed, after the gate below |
+
+To arm a pane, launch it with `~/.claude/claude-armed.sh`, or tell the agent to go autonomous
+mid-session and it runs `~/.claude/arm-session.sh on` (`off` turns it back off). A plain `claude`
+session stays under your control.
+
+## Self-clear gate
+
+A pane clears itself only after both steps:
+
+1. `/kijito-qa-memory` curates memory, writes a current-state note that begins with `RESUME NOW:`,
+   and confirms with a fresh subagent that a cold start can resume. It records a pass token.
+2. `self-clear.sh` checks that the pane is armed, is in tmux, has a fresh token, and is under the
+   cycle cap.
+
+It then runs `/clear`. The SessionStart hook catches the new session up and it resumes from the note.
+To stop all autonomous sending and clearing, create the file `~/.claude/.lifecycle/STOP`.
+
+## Running without Kijito
+
+The context check (`myctx.sh`) has no dependencies; install and run it.
+
+For the autonomy harness, set `KIJITO_MODE=off` for a generic catch-up prompt, or set your own with
+`KIJITO_AUTOCATCHUP_PROMPT`. The self-clear gate only requires that some curation step write the pass
+token (`~/.claude/kijito-qa-pass.sh`). Kijito is the default backend, not a requirement.
+
+## Tests
+
+```bash
+bash tests/lc_test.sh
+```
+
+Covers arming, the token gate, the cycle cap, the checkpoint, the kill switch, and auto-send.
+
+## License
+
+Apache 2.0. Copyright 2026 Arcada Labs. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

kijito_claude-0.1.0/README.md

@@ -0,0 +1,117 @@
+# kijito-claude
+
+Tools for Claude Code sessions to track their own context window and, optionally, run unattended.
+A session can catch up on memory at startup, report how much of its context window is actually in
+use, and recycle its context at high usage without losing the working state. It uses
+[Kijito](https://kijito.ai) as the memory backend by default, and also runs standalone (see
+"Running without Kijito").
+
+Everything here is optional. The catch-up and curation steps are a handful of memory calls you can
+run by hand; the scripts and the two skills just make the routine uniform and easy to deploy across
+machines. Install only the pieces you want — the context check stands alone, the autonomy harness is
+opt-in per pane, and the skills are convenience wrappers, not requirements.
+
+## Components
+
+| Component | What it does | Needs Kijito |
+|---|---|---|
+| `myctx.sh`, `statusline-context.sh` | Report actual context-window usage from the API token counts recorded in the session transcript (the same numbers `/context` shows). Cheap to call. The statusline shows it live. | No |
+| Session catch-up (`session-catchup-hint.sh`, a SessionStart hook) | Each session catches up on memory and notes before it starts on the task. | Optional |
+| Armed-pane autonomy (`claude-armed.sh`, `arm-session.sh`, `session-autosend.sh`) | An armed tmux pane sends itself a first prompt and continues preloaded work. Arming is per pane, so one pane can run unattended while you drive another. | Optional |
+| Self-clear loop (`self-clear.sh`, `lifecycle-lib.sh`, `kijito-qa-pass.sh`) | At high measured context, the session curates memory, confirms a fresh session can resume, runs `/clear`, then catches up again and continues. Gated so it will not clear with unsaved work. | Optional (see note) |
+| `kijito-start` skill | The active, thorough version of session catch-up: load memory, read the current-state pointer and recent lessons, arm the inbox, and resume active work — or, for a new persona, set up identity and the pointer. | Yes |
+| `kijito-qa-memory` skill | Memory curation that requires writing the new memories (not only fixing existing ones), then uses a fresh subagent to confirm a cold start can reconstruct the work. | Yes |
+
+The two skills are conveniences, not the only way in: an agent can run the same catch-up and
+curation by hand from a few prompts. They are packaged as skills because that makes them simple to
+drop into `~/.claude/skills/` and invoke the same way everywhere.
+
+The self-clear loop needs some durable store to carry the handoff across `/clear`. That is Kijito by
+default; a notes file works in standalone mode.
+
+## Install
+
+From source:
+
+```bash
+git clone https://github.com/KijitoAI/kijito-claude
+cd kijito-claude && ./install.sh
+```
+
+Or, once the v0.1 packages are published, with a package runner (no clone needed):
+
+```bash
+npx kijito-claude       # via npm
+pipx run kijito-claude  # via PyPI  (uvx kijito-claude also works)
+```
+
+Both package runners do the same thing as the from-source install: they bundle the scripts and
+skills and run `install.sh`. They need `bash`, so on Windows run them inside WSL (see Platform
+support).
+
+The installer copies the scripts to `~/.claude/`, deploys the skills to `~/.claude/skills/`, drops
+the CLAUDE.md doctrine snippet alongside them, and merges the keys it needs into `settings.json`. It
+backs up `settings.json` and merges with `jq`, so it leaves your existing settings alone and is safe
+to re-run, including on other machines. Requires `jq`. The autonomy features require `tmux`.
+
+## Platform support
+
+The scripts are POSIX-style `bash` and avoid GNU-only flags (epoch and timestamp formatting work on
+both BSD and GNU `date`), so they run the same on Linux and macOS.
+
+| Platform | Context check | Catch-up + skills | Armed-pane autonomy / self-clear |
+|---|---|---|---|
+| Linux | yes | yes | yes (needs `tmux`) |
+| macOS | yes | yes | yes (needs `tmux`) |
+| Windows via WSL | yes | yes | yes — run `claude` inside the WSL distro, where `tmux` works |
+| Windows native (no WSL) | with Git Bash | with Git Bash | no — `tmux` is not available |
+
+On Windows, use WSL: install and launch `claude` inside the Linux distro and everything works as it
+does on native Linux. The autonomy harness drives a session by typing into its own `tmux` pane, which
+has no native-Windows equivalent, so without WSL only the context check and the by-hand catch-up
+apply. Requirements everywhere: `bash` and `jq`; add `tmux` for the autonomy features.
+
+## Managed vs. autonomous panes
+
+Arming is per pane.
+
+| | plain `claude` | armed pane |
+|---|---|---|
+| Catch-up | reminder only; you send the first prompt | sends its own first prompt |
+| Self-clear | not allowed; you manage context | allowed, after the gate below |
+
+To arm a pane, launch it with `~/.claude/claude-armed.sh`, or tell the agent to go autonomous
+mid-session and it runs `~/.claude/arm-session.sh on` (`off` turns it back off). A plain `claude`
+session stays under your control.
+
+## Self-clear gate
+
+A pane clears itself only after both steps:
+
+1. `/kijito-qa-memory` curates memory, writes a current-state note that begins with `RESUME NOW:`,
+   and confirms with a fresh subagent that a cold start can resume. It records a pass token.
+2. `self-clear.sh` checks that the pane is armed, is in tmux, has a fresh token, and is under the
+   cycle cap.
+
+It then runs `/clear`. The SessionStart hook catches the new session up and it resumes from the note.
+To stop all autonomous sending and clearing, create the file `~/.claude/.lifecycle/STOP`.
+
+## Running without Kijito
+
+The context check (`myctx.sh`) has no dependencies; install and run it.
+
+For the autonomy harness, set `KIJITO_MODE=off` for a generic catch-up prompt, or set your own with
+`KIJITO_AUTOCATCHUP_PROMPT`. The self-clear gate only requires that some curation step write the pass
+token (`~/.claude/kijito-qa-pass.sh`). Kijito is the default backend, not a requirement.
+
+## Tests
+
+```bash
+bash tests/lc_test.sh
+```
+
+Covers arming, the token gate, the cycle cap, the checkpoint, the kill switch, and auto-send.
+
+## License
+
+Apache 2.0. Copyright 2026 Arcada Labs. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

kijito_claude-0.1.0/install.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# kijito-claude installer — deploys the toolkit into ~/.claude and merges settings.json.
+# Idempotent + non-destructive: backs up settings.json, jq-merges keys (no clobber), de-dups the hook.
+# Also the cross-machine/fleet installer: clone the repo on any box and run this.
+set -euo pipefail
+REPO="$(cd "$(dirname "$0")" && pwd)"
+DEST="$HOME/.claude"
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq is required."; exit 1; }
+command -v tmux >/dev/null 2>&1 || echo "WARN: tmux not found — armed-pane autonomy + auto-send need tmux. (Context self-check works without it.)"
+
+mkdir -p "$DEST/skills" "$DEST/.lifecycle"
+
+# 1) scripts → ~/.claude (executable)
+for s in "$REPO"/scripts/*.sh; do install -m 0755 "$s" "$DEST/$(basename "$s")"; done
+echo "✓ scripts installed → $DEST"
+
+# 2) skills (optional helpers — every skill in skills/ gets deployed)
+for d in "$REPO"/skills/*/; do
+  name="$(basename "$d")"
+  [ -f "$d/SKILL.md" ] || continue
+  mkdir -p "$DEST/skills/$name"
+  install -m 0644 "$d/SKILL.md" "$DEST/skills/$name/SKILL.md"
+  echo "✓ skill: $name"
+done
+
+# 2b) the CLAUDE.md doctrine snippet — copied alongside so npx/pipx users (who never cloned
+# the repo) still have it to paste into ~/.claude/CLAUDE.md.
+if [ -f "$REPO/CLAUDE.md.snippet" ]; then
+  install -m 0644 "$REPO/CLAUDE.md.snippet" "$DEST/kijito-claude.CLAUDE.md.snippet"
+  echo "✓ doctrine snippet → $DEST/kijito-claude.CLAUDE.md.snippet"
+fi
+
+# 3) settings.json — merge statusLine / totalTokensReminder / env / SessionStart hook (idempotent)
+SET="$DEST/settings.json"; [ -f "$SET" ] || echo '{}' > "$SET"
+cp "$SET" "$SET.bak.$(date +%Y%m%d%H%M%S)"
+HOOK=$(jq -n --arg cmd "bash $DEST/session-catchup-hint.sh" \
+  '{matcher:"startup|clear|compact", hooks:[{type:"command", command:$cmd}]}')
+jq --arg home "$DEST" --argjson hook "$HOOK" '
+  .statusLine = {type:"command", command:("bash " + $home + "/statusline-context.sh"), padding:0}
+  | .totalTokensReminder = (.totalTokensReminder // "countdown")
+  | .env = ((.env // {}) + {KIJITO_AUTOCATCHUP_DELAY: ((.env.KIJITO_AUTOCATCHUP_DELAY) // "4.0")})
+  | .hooks = (.hooks // {})
+  | .hooks.SessionStart = (
+      ((.hooks.SessionStart // [])
+        | map(select([ (.hooks[]?.command // "") ] | any(test("session-catchup-hint")) | not)))
+      + [$hook] )
+' "$SET" > "$SET.tmp"
+jq -e . "$SET.tmp" >/dev/null
+mv "$SET.tmp" "$SET"
+echo "✓ settings.json merged (backup: $SET.bak.*)"
+
+echo
+echo "Next: add the doctrine snippet to your ~/.claude/CLAUDE.md (context self-check + session-start"
+echo "catch-up + self-clear gate). It's at $DEST/kijito-claude.CLAUDE.md.snippet"
+echo "New sessions pick up the hook + statusline; restart a running session to apply."
+echo "Verify context self-check now:  ~/.claude/myctx.sh"

kijito_claude-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kijito-claude"
+version = "0.1.0"
+description = "Installer for the kijito-claude toolkit — context tracking, session catch-up, and self-clear scripts plus the Kijito skills, deployed into ~/.claude."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Arcada Labs", email = "jason@arcadalabs.com" }]
+keywords = ["kijito", "claude", "claude-code", "anthropic", "installer", "cli", "skills"]
+dependencies = []
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Build Tools",
+]
+
+[project.urls]
+Homepage = "https://github.com/KijitoAI/kijito-claude"
+Repository = "https://github.com/KijitoAI/kijito-claude"
+"Bug Tracker" = "https://github.com/KijitoAI/kijito-claude/issues"
+
+[project.scripts]
+kijito-claude = "kijito_claude.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kijito_claude"]
+
+# The bash scripts, skills, install.sh, and the CLAUDE.md snippet live at the repo root so
+# they double as the git-clone install path. Pull them into the wheel under the package so
+# importlib.resources can find them at runtime.
+[tool.hatch.build.targets.wheel.force-include]
+"scripts" = "kijito_claude/_assets/scripts"
+"skills" = "kijito_claude/_assets/skills"
+"install.sh" = "kijito_claude/_assets/install.sh"
+"CLAUDE.md.snippet" = "kijito_claude/_assets/CLAUDE.md.snippet"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/",
+  "scripts/",
+  "skills/",
+  "install.sh",
+  "CLAUDE.md.snippet",
+  "README.md",
+  "LICENSE",
+  "NOTICE",
+]

kijito_claude-0.1.0/scripts/arm-session.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Turn THIS session's autonomy on/off via INTERACTION. The agent runs this when the user says
+# "enable self-clear" / "go autonomous" (on), or "I'll manage this one" (off). It arms the current
+# tmux PANE: self-clear becomes permitted, and post-/clear SessionStarts auto-catch-up + resume.
+# Same marker claude-armed.sh uses, so launch-time and interaction-time arming are identical.
+. "$HOME/.claude/lifecycle-lib.sh"
+action="${1:-on}"
+if [ -z "${TMUX_PANE:-}" ]; then echo "not in tmux — autonomy needs a tmux pane; nothing armed."; exit 1; fi
+marker="$KIJITO_LC_DIR/arm.$TMUX_PANE"
+case "$action" in
+  on)     touch "$marker"; lc_log ARM "on pane=$TMUX_PANE"
+          echo "AUTONOMY ON (pane $TMUX_PANE): self-clear permitted; after any /clear this pane auto-catches-up + resumes. Turn off: ~/.claude/arm-session.sh off" ;;
+  off)    rm -f "$marker"; lc_log ARM "off pane=$TMUX_PANE"
+          echo "AUTONOMY OFF (pane $TMUX_PANE): human-managed; self-clear refused." ;;
+  status) if lc_is_armed "$TMUX_PANE"; then echo "armed (autonomous)"; else echo "not armed (human-managed)"; fi ;;
+  *)      echo "usage: arm-session.sh [on|off|status]"; exit 2 ;;
+esac

kijito_claude-0.1.0/scripts/claude-armed.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Launch an ARMED Claude Code session: when in tmux it auto-sends the catch-up prompt (instigating
+# its own first turn) and continues preloaded work. Use for orchestrator/unattended panes + the
+# self-clear loop. Plain `claude` is NOT armed → never collides with you typing.
+#
+# Arming is a per-pane MARKER file (robust; doesn't depend on env reaching the hook). The marker is
+# removed when claude exits (trap). KIJITO_AUTOCATCHUP=1 is also exported as a belt-and-suspenders.
+. "$HOME/.claude/lifecycle-lib.sh" 2>/dev/null
+marker="${KIJITO_LC_DIR:-$HOME/.claude/.lifecycle}/arm.${TMUX_PANE:-nopane}"
+mkdir -p "$(dirname "$marker")" 2>/dev/null
+touch "$marker" 2>/dev/null
+trap 'rm -f "$marker"' EXIT INT TERM
+KIJITO_AUTOCATCHUP=1 claude "$@"

kijito_claude-0.1.0/scripts/kijito-qa-pass.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Record that /kijito-qa-memory Phase-4 cold-boot verification PASSED for THIS session.
+# self-clear.sh REQUIRES a fresh token from this before it will fire (gate C1) — i.e. you
+# cannot self-clear without a passing cold-boot verify. The token is consumed by one /clear.
+. "$HOME/.claude/lifecycle-lib.sh"
+lc_now > "$(lc_qa_token)"
+lc_log QA_PASS "cold-boot verified"
+echo "Recorded kijito-qa-memory pass for session ${CLAUDE_CODE_SESSION_ID:-?}. self-clear unlocked for ONE clear."

kijito_claude-0.1.0/scripts/lifecycle-lib.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Shared helpers for Kijito session-lifecycle scripts. SOURCE this (`. lifecycle-lib.sh`), don't exec.
+KIJITO_LC_DIR="${KIJITO_LC_DIR:-$HOME/.claude/.lifecycle}"
+mkdir -p "$KIJITO_LC_DIR" 2>/dev/null
+KIJITO_LC_LOG="$KIJITO_LC_DIR/lifecycle.log"
+KIJITO_LC_STOP="$KIJITO_LC_DIR/STOP"
+
+lc_now() { date +%s; }                                   # epoch (portable BSD/GNU)
+
+lc_log() {                                               # M2 — audit log:  action [detail]
+  printf '%s sid=%s pane=%s %s %s\n' \
+    "$(date '+%Y-%m-%dT%H:%M:%S')" "${CLAUDE_CODE_SESSION_ID:-?}" "${TMUX_PANE:-?}" "$1" "${2:-}" \
+    >> "$KIJITO_LC_LOG" 2>/dev/null
+}
+
+lc_stopped() { [ -f "$KIJITO_LC_STOP" ]; }              # M1 — kill switch: `touch ~/.claude/.lifecycle/STOP` halts all
+
+# C3 — best-effort subagent guard. VERIFIED 2026-06-24: a subagent shares the parent's
+# CLAUDE_CODE_SESSION_ID / CLAUDE_CODE_CHILD_SESSION / ENTRYPOINT, so there is NO reliable env
+# discriminator today. This only trips on FUTURE markers and NEVER false-positives the main
+# session (both are unset now). Real C3 protection = consumable QA token + cycle cap + kill switch.
+lc_is_child() { [ -n "${CLAUDE_AGENT_TYPE:-}" ] || [ -n "${CLAUDE_CODE_AGENT:-}" ]; }
+
+lc_pane_alive() { command -v tmux >/dev/null 2>&1 && tmux display-message -p -t "$1" '#{session_name}' >/dev/null 2>&1; }
+
+# M4 (FIXED) — a running claude pane reports pane_current_command as its VERSION (e.g. "2.1.190"),
+# NOT "claude"/"node" (verified 2026-06-24). So check "not a bare shell" instead of whitelisting claude.
+lc_pane_usable() {
+  [ "${KIJITO_LC_TEST:-0}" = "1" ] && return 0          # test-harness escape hatch
+  local c; c=$(tmux display-message -p -t "$1" '#{pane_current_command}' 2>/dev/null)
+  case "$c" in ""|zsh|bash|sh|-zsh|-bash|-sh|fish|tcsh|dash) return 1 ;; *) return 0 ;; esac
+}
+
+# Per-spawn arming (ROBUST — no env-propagation dependency): claude-armed.sh drops a marker keyed to
+# the pane; the hook (which reliably has TMUX_PANE) reads it. Also honors KIJITO_AUTOCATCHUP=1.
+lc_is_armed() { [ -f "$KIJITO_LC_DIR/arm.${1:-${TMUX_PANE:-x}}" ] || [ "${KIJITO_AUTOCATCHUP:-0}" = "1" ]; }
+
+# qa-token is SESSION-keyed (correct: each post-/clear session must earn its OWN fresh QA pass).
+lc_qa_token()   { echo "$KIJITO_LC_DIR/qa-pass.${CLAUDE_CODE_SESSION_ID:-nosession}"; }
+# cycle/checkpoint are PANE-keyed: /clear ROTATES CLAUDE_CODE_SESSION_ID (verified live: 1c5947c1→
+# 6f305fa1 in the same pane %19), so a session-keyed counter resets every clear and the cap/checkpoint
+# never accumulate across the self-clear loop. The pane persists across clears → accumulate correctly.
+lc_cycle_file() { echo "$KIJITO_LC_DIR/cycles.${TMUX_PANE:-${CLAUDE_CODE_SESSION_ID:-nosession}}"; }

kijito_claude-0.1.0/scripts/myctx.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# "How full am I, really?" — hard data vs. gut. Run this when you FEEL full.
+# Bulletproof: finds THIS session's transcript via CLAUDE_CODE_SESSION_ID (no
+# "newest file" guessing), then reads the API's own token ledger (== /context).
+sid="${CLAUDE_CODE_SESSION_ID:?CLAUDE_CODE_SESSION_ID not set}"
+f=$(find ~/.claude/projects -name "$sid.jsonl" 2>/dev/null | head -1)
+[ -z "$f" ] && { echo "no transcript for session $sid"; exit 1; }
+win="${CTX_WINDOW:-1000000}"
+used=$(jq -s 'map(select(.type=="assistant" and .message.usage!=null).message.usage)|last // {}
+              |(.input_tokens//0)+(.cache_read_input_tokens//0)+(.cache_creation_input_tokens//0)' "$f")
+awk -v u="$used" -v w="$win" 'BEGIN{
+  printf "context: %d tok = %.1f%% of %dk   (free: %.1f%%, ~%d tok)\n", u, u/w*100, w/1000, (1-u/w)*100, w-u }'

kijito_claude-0.1.0/scripts/self-clear.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# AGENT-INVOKED self-/clear — the agent's FINAL action, only after /kijito-qa-memory passed.
+# Hard gates (all must hold): kill-switch off · armed · not-a-subagent · in tmux · pane alive +
+# is claude · FRESH qa-pass token · under cycle cap · not a checkpoint cycle. Never auto-fired.
+set -u
+. "$HOME/.claude/lifecycle-lib.sh"
+refuse(){ echo "self-clear REFUSED: $1" >&2; lc_log SELFCLEAR_REFUSED "$1"; exit "${2:-3}"; }
+
+lc_stopped && refuse "kill switch present ($KIJITO_LC_STOP) — rm it to re-enable" 9
+lc_is_armed "${TMUX_PANE:-}" || refuse "not an armed pane — self-clear only runs in autonomous sessions (launch via ~/.claude/claude-armed.sh); plain 'claude' is human-managed" 3
+lc_is_child && refuse "subagent marker set — would clear the PARENT pane" 6
+{ [ -n "${TMUX:-}" ] && [ -n "${TMUX_PANE:-}" ]; } || refuse "not in tmux (TMUX/TMUX_PANE unset)" 4
+lc_pane_alive "$TMUX_PANE" || refuse "target pane $TMUX_PANE no longer exists" 4
+# (no pane_current_command gate — unreliable label; send-keys reaches the TTY regardless)
+
+# C1 — require a FRESH /kijito-qa-memory pass for THIS session
+tok="$(lc_qa_token)"; ttl="${KIJITO_QA_TTL:-1800}"
+[ -f "$tok" ] || refuse "no kijito-qa-memory pass — run /kijito-qa-memory first (it cold-boot-verifies, then records the token)" 5
+age=$(( $(lc_now) - $(cat "$tok" 2>/dev/null || echo 0) ))
+[ "$age" -le "$ttl" ] || refuse "kijito-qa-memory pass is stale (${age}s > ${ttl}s) — re-run /kijito-qa-memory" 5
+
+# C2 / H3 — cycle cap + periodic human checkpoint (count only genuine fires)
+cf="$(lc_cycle_file)"; cyc=$(( $(cat "$cf" 2>/dev/null || echo 0) + 1 )); echo "$cyc" > "$cf"
+max="${KIJITO_SELFCLEAR_MAX_CYCLES:-12}"
+[ "$cyc" -le "$max" ] || refuse "cycle cap hit ($cyc > $max) — likely a loop; human review (reset: rm $cf)" 7
+chk="${KIJITO_SELFCLEAR_CHECKPOINT:-5}"
+if [ "$chk" -gt 0 ] && [ $(( cyc % chk )) -eq 0 ]; then
+  refuse "checkpoint at cycle $cyc (every $chk) — pausing for human review; run again to continue past it" 8
+fi
+
+# C5 — consume the token (one clear per QA pass) and fire as the LAST action
+rm -f "$tok"
+delay="${KIJITO_SELFCLEAR_DELAY:-3.0}"
+lc_log SELFCLEAR_FIRE "cycle=$cyc delay=$delay"
+( sleep "$delay"
+  lc_stopped               && { lc_log SELFCLEAR_ABORT "stop during delay"; exit 0; }
+  lc_pane_alive "$TMUX_PANE" || { lc_log SELFCLEAR_ABORT "pane gone during delay"; exit 0; }
+  tmux send-keys -t "$TMUX_PANE" -l -- "/clear" 2>/dev/null
+  tmux send-keys -t "$TMUX_PANE" Enter 2>/dev/null
+  lc_log SELFCLEAR_DONE "cycle=$cyc"
+) >/dev/null 2>&1 &
+echo "self-clear scheduled (cycle $cyc/$max): /clear → $TMUX_PANE in ${delay}s. This MUST be your FINAL action — stop now; SessionStart re-catches-up and resumes the preloaded work."
+exit 0

kijito_claude-0.1.0/scripts/session-autosend.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Delayed self-send of the catch-up prompt INTO a tmux pane → instigates the first turn.
+# Called (detached, via nohup &) by the SessionStart hook ONLY when the pane is armed + in tmux.
+# Args: $1 = target tmux pane (normally "$TMUX_PANE"). Fixed-delay approach — proven reliable.
+# Needs Kijito: OPTIONAL — set KIJITO_AUTOCATCHUP_PROMPT for your own text, or KIJITO_MODE=off for a
+#   generic (non-Kijito) default prompt.
+set -u
+. "$HOME/.claude/lifecycle-lib.sh"
+pane="${1:?target pane required}"
+command -v tmux >/dev/null 2>&1 || exit 0
+lc_stopped && { lc_log AUTOSEND_SKIP "kill switch"; exit 0; }
+
+if [ -n "${KIJITO_AUTOCATCHUP_PROMPT:-}" ]; then
+  prompt="$KIJITO_AUTOCATCHUP_PROMPT"
+elif [ "${KIJITO_MODE:-on}" = "off" ]; then
+  # standalone (no Kijito): catch up against whatever notes/handoff you keep
+  prompt="Catch up on this project's context and any handoff / next-steps notes from the prior session, then CONTINUE the active work to its DONE-WHEN without waiting for further instruction. If there's no active work, report ready."
+else
+  prompt="Please catch up deeply on all memories, lessons, and arm your inbox. If you are on a brand-new project with no persona yet, set that up per CLAUDE.md. Then, if your current-state / next-steps pointer shows ACTIVE WORK in progress, CONTINUE it autonomously without waiting for further instruction — work to its DONE-WHEN criteria, stopping only for a genuine gate. If there is no active work to resume, report ready."
+fi
+
+delay="${KIJITO_AUTOCATCHUP_DELAY:-4.0}"     # seconds for the TUI to become input-ready
+sleep "$delay"
+lc_stopped             && { lc_log AUTOSEND_ABORT "stop appeared"; exit 0; }
+lc_pane_alive "$pane"  || { lc_log AUTOSEND_ABORT "pane gone"; exit 0; }
+# NOTE: do NOT gate on pane_current_command — it's unreliable (reports "bash" for a wrapped
+# claude, the version for an exec'd one). send-keys reaches the pane's TTY (claude) regardless.
+tmux send-keys -t "$pane" -l -- "$prompt" 2>/dev/null
+tmux send-keys -t "$pane" Enter 2>/dev/null
+lc_log AUTOSEND_FIRE "delay=$delay"
+exit 0

kijito_claude-0.1.0/scripts/session-catchup-hint.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# SessionStart hook → (1) ALWAYS print a passive catch-up reminder (additionalContext via stdout),
+# (2) ARMED auto-send: if this pane is armed (claude-armed.sh marker or KIJITO_AUTOCATCHUP=1) and
+# we're in tmux, instigate the first turn by typing the prompt into our own pane.
+. "$HOME/.claude/lifecycle-lib.sh" 2>/dev/null
+src=$(cat 2>/dev/null | jq -r '.source // "startup"' 2>/dev/null); [ -z "$src" ] && src=startup
+case "$src" in
+  clear)   pre="You just /clear'd — context was intentionally reset to a clean slate." ;;
+  compact) pre="Context was just compacted — detail was summarized away; memory is now the source of truth." ;;
+  *)       pre="New session." ;;
+esac
+cat <<EOF
+[SESSION CATCH-UP — do this BEFORE the user's task] $pre Start continuous, not cold:
+1) kijito_startup(persona, project) → read the current-state pointer it names (kijito_get) → skim recent lessons.
+2) Arm your inbox watcher.
+3) If this is a BRAND-NEW project with NO persona yet: read ./CLAUDE.md + ~/.claude/CLAUDE.md and set your persona/project before writing any memory.
+Never pause on a *feeling* of full context — run ~/.claude/myctx.sh for hard data.
+EOF
+
+# Armed auto-send (detached so it never blocks startup or pollutes the additionalContext above).
+if command -v lc_is_armed >/dev/null 2>&1 && [ -n "${TMUX:-}" ] && [ -n "${TMUX_PANE:-}" ] && lc_is_armed "$TMUX_PANE"; then
+  lc_log HOOK "src=$src autosend=ARMED pane=$TMUX_PANE"
+  nohup bash "$HOME/.claude/session-autosend.sh" "$TMUX_PANE" >/dev/null 2>&1 &
+else
+  command -v lc_log >/dev/null 2>&1 && lc_log HOOK "src=$src autosend=skip(not-armed-or-no-tmux) tmux=${TMUX:+y} pane=${TMUX_PANE:-none}"
+fi

kijito_claude-0.1.0/scripts/statusline-context.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Claude Code statusline — model name + accurate context-window usage.
+# Source of truth, in order:
+#   1) harness-provided context_window.* fields (if this CC version supplies them)
+#   2) fallback: compute from the transcript's API usage ledger — the same data
+#      /context is built on (sum input+cache_read+cache_creation of last asst turn).
+# Reads the statusline JSON on stdin; prints one line. ~tens of ms; never enters the model's context.
+input=$(cat)
+
+model=$(printf '%s' "$input" | jq -r '.model.display_name // "Claude"')
+
+# 1) Prefer harness-computed context window if present
+used=$(printf '%s' "$input" | jq -r '.context_window.used_tokens // empty')
+win=$(printf '%s'  "$input" | jq -r '.context_window.total_tokens // empty')
+
+# 2) Fallback: ground-truth from the transcript usage ledger
+if [ -z "$used" ]; then
+  tp=$(printf '%s' "$input" | jq -r '.transcript_path // empty')
+  if [ -n "$tp" ] && [ -f "$tp" ]; then
+    used=$(jq -s 'map(select(.type=="assistant" and .message.usage != null) | .message.usage) | last // {}
+                  | (.input_tokens // 0) + (.cache_read_input_tokens // 0) + (.cache_creation_input_tokens // 0)' \
+          "$tp" 2>/dev/null)
+  fi
+fi
+[ -z "$used" ] && used=0
+[ -z "$win"  ] && win=1000000
+
+pct=$(awk -v u="$used" -v w="$win" 'BEGIN { if (w>0) printf "%.0f", (u/w)*100; else print 0 }')
+uk=$(awk  -v u="$used" 'BEGIN { if (u>=1000) printf "%.0fk", u/1000; else printf "%d", u }')
+wk=$(awk  -v w="$win"  'BEGIN { if (w>=1000000) printf "%gm", w/1000000; else printf "%.0fk", w/1000 }')
+
+# refresh-before-70 discipline: green <60, yellow 60-79, red >=80
+col=$(awk -v p="$pct" 'BEGIN { if (p>=80) printf "\033[31m"; else if (p>=60) printf "\033[33m"; else printf "\033[32m" }')
+printf '%s · ctx %b%s/%s (%s%%)\033[0m' "$model" "$col" "$uk" "$wk" "$pct"

kijito_claude-0.1.0/skills/kijito-qa-memory/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: kijito-qa-memory
+description: Rigorous Kijito memory curation with enforced creation + cold-boot verification. Use when winding down a session, before /clear or self-clear, when asked to "QA / curate / clean up memory", when preparing a handoff for the next session, or any time you need to be sure a fresh session could continue the work. Counters the two chronic failure modes — treating "QA" as corrections-only (skipping creation), and never confirming the memory actually works in a cold context.
+---
+
+# Kijito QA Memory — curate the graph, then PROVE it works cold
+
+Kijito (local daemon, `mcp__kijito__*`) is the only thing that survives a `/clear` or a new session. "QA memory" is not "fix a few wrong notes" — it is **make the graph match what this session actually learned, then confirm a cold agent can act on it.** Pass your persona/project on every write.
+
+## The bias this skill exists to defeat
+
+You will, by default, do two wrong things — counteract both deliberately:
+1. **Collapse QA to corrections-only.** The creation gap is *invisible* (you can't see the memory you never wrote), so "QA" silently becomes "tidy existing notes." **Creation is half the job and it is the half that gets skipped. Do it FIRST and exhaustively.**
+2. **Assume done instead of confirming.** You'll declare the handoff good without ever testing it cold. **A curation is not complete until a fresh, context-free agent reconstructs the work from memory alone.** This is non-negotiable and is the step you'll be tempted to skip.
+
+Run the phases in order. Do not declare done until Phase 4 passes twice (2-green).
+
+## Phase 1 — CREATE (exhaustive, do this FIRST)
+
+Enumerate EVERY candidate insight from this session — don't filter yet:
+- decisions made · findings/results · bugs found · lessons & gotchas · reusable recipes/commands · state changes · things you now believe that you didn't before · corrections to prior belief.
+
+For each candidate ask: **"Is this already an atomic memory?"** If not, write it now:
+- one insight per memory (if you wrote "5 things about X", that's 5 memories);
+- front-load the exact words a later search/teammate would use;
+- set `persona` + `project`; pick honest `importance` (don't inflate; 0.85+ never decays).
+
+Then apply the **completeness gate**, out loud: *"What did I learn this session that is NOT yet written?"* — and EXPECT to find gaps. List them, write them. Only move on when that question returns nothing.
+
+## Phase 2 — CORRECT / STALENESS
+
+`kijito_recall` each topic you touched this session. For every memory that is now **wrong or changed** → `kijito_correct` (fades old + links the fix; never edit history). **Obsolete** → `kijito_fade`. Operational/"how X works" memories are the most dangerous when stale — verify against reality (code/config/files) before trusting or correcting.
+
+## Phase 3 — PRELOAD THE HANDOFF (the current-state pointer)
+
+Update your living current-state / next-steps pointer (e.g. a stable memory you `kijito_update` in place) so it ALONE drives the next session:
+- **OPEN with an imperative to continue** — `RESUME NOW: <next concrete action>` — not a description, or the next session asks "what should I work on?" instead of acting.
+- then: the single active task · exact next steps · DONE-WHEN criteria · key anchor memory IDs.
+- if **no pointer exists yet** (new persona/project), CREATE one as a stable memory and record its ID — that is your pointer from now on (a cold boot has nothing to read otherwise).
+- if the work is **DONE** (DONE-WHEN met), do NOT write `RESUME NOW` — mark it COMPLETE so the next boot reports done. A stale imperative on finished work causes an infinite self-clear loop.
+- if self-managing an **autonomous workstream**, `kijito_hive_claim` it first so a concurrent same-persona session can't clobber the handoff; release when done.
+
+## Phase 4 — COLD-BOOT VERIFY (confirm, don't assume — DO NOT SKIP)
+
+Prove the memory works in a context that has never seen this conversation. Spawn a **fresh general-purpose subagent** (NOT a fork — a fork inherits your context and would cheat the test). Give it only this:
+
+> You are a brand-new session. Connect to Kijito and cold-boot: `kijito_startup(persona="<P>", project="<J>")`, then read the current-state pointer it names and the memories it links. Using ONLY what Kijito returns (you have no other context), report:
+> 1. the single active task in progress,
+> 2. the exact next step to take right now,
+> 3. what is already done vs. not,
+> 4. the DONE-WHEN criteria,
+> 5. anything ambiguous, missing, or contradictory.
+> Do not guess or infer beyond what the memories say — if it isn't in memory, report it as a GAP.
+
+Compare its report to ground truth:
+- Reconstructs task + next step + DONE-WHEN correctly, no load-bearing gaps → **PASS**.
+- Misses, garbles, or flags a real gap → **FAIL**: that gap is a missing/weak memory → go back to **Phase 1/3**, fix the *specific* gap, re-run.
+
+**2-green:** repeat Phase 4 until two consecutive cold boots reconstruct cleanly. Finding any issue resets the count.
+
+## Done report
+
+State plainly: N memories created, N corrected, N faded; the current-state pointer ID; and the cold-boot verdict ("a fresh agent reconstructed the active task + next steps + DONE-WHEN, 2 consecutive clean boots"). If you cannot say that, you are not done.
+
+**Then record the pass:** run `~/.claude/kijito-qa-pass.sh`. This writes the token `self-clear.sh` requires — without a passing cold-boot verify you cannot self-clear, by design. The token is consumed by one `/clear`, so each recycle needs a fresh kijito-qa-memory pass.
+
+## Notes
+
+- This skill IS the memory half of the self-clear gate: a session may only self-`/clear` after this passes (then the next session resumes from the pointer).
+- Reproducible from Kijito: the procedure is also stored in the graph — `kijito_recall("kijito-qa-memory skill procedure cold-boot verify")` — so any agent on any machine can recover or rebuild it even without this file.

kijito_claude-0.1.0/skills/kijito-start/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: kijito-start
+description: Catch up at the start of a session so you continue rather than restart. For an existing persona — load memory, read the current-state pointer and recent lessons, arm the inbox, and resume any active work. For a brand-new persona/project — establish identity from CLAUDE.md, set up the inbox, and create the current-state pointer. Use on the first action of a session, after a /clear, or after compaction. Optional: this is a handful of tool calls you can run by hand; the skill just makes the routine uniform and one command.
+---
+
+# Kijito Start — begin continuous, not cold
+
+Every session begins in the middle of ongoing work, not from zero. Kijito (local daemon, `mcp__kijito__*`) holds what the last session learned; this skill loads it before you touch the user's task, so you act on accumulated context instead of guessing.
+
+**This is optional.** The catch-up is just a few Kijito calls — `kijito_startup`, a couple of `kijito_get`s, an inbox check — and you can do them by hand any time. The skill exists because it is easy to deploy and runs the same way every session, not because the steps are hard. A SessionStart hook can also remind you passively; this skill is the active, thorough version.
+
+## Phase 0 — which branch are you on?
+
+Run `kijito_startup(persona="<P>", project="<J>")` with the persona/project your `CLAUDE.md` assigns (project `CLAUDE.md` first, then `~/.claude/CLAUDE.md`). Pass them explicitly; do not rely on auto-discovery.
+
+- It returns identity + recall + recent + goals, and reports whether your persona already exists.
+- **Existing persona** (has memories, an identity, a current-state pointer) → **Path A**.
+- **Brand-new persona/project** (no identity memory, empty inbox, nothing to resume) → **Path B**.
+
+## Path A — existing persona: catch up deeply, then resume
+
+1. **Read the pointer in full.** `kijito_startup` truncates content. `kijito_get` the current-state / next-steps pointer it names, then `kijito_get` the memories that pointer links. Do not work from previews — the load-bearing detail is in the full text.
+2. **Skim recent lessons.** `kijito_recent` (last 24–48h) and `kijito_recall("lessons gotchas <your project>")`. These are how you avoid repeating a mistake the last session already paid for.
+3. **Distrust stale operational facts.** Memories about how something works (paths, ports, config, deploy steps) are the ones most often wrong after time passes — recall flags them as stale. Verify a load-bearing one against reality (code / config / a quick command) before you act on it.
+4. **Arm your inbox.** Check `kijito_hive_inbox(persona="<P>")` for durable messages from sibling personas. If the inbox monitor runs here, also tail your own stream for live events (`~/.cache/kijito-inbox-monitor/events.<P>.ndjson`); do not start your own watcher if a supervised producer already runs.
+5. **Resume or report.** If the pointer shows ACTIVE WORK and you were auto-started on an armed pane, continue it autonomously to its DONE-WHEN — do not wait for a prompt. Otherwise, report where things stand and wait for the user.
+
+## Path B — brand-new persona/project: set up identity first
+
+Do this **before writing any memory**, or the first writes land under the wrong owner and contaminate the graph.
+
+1. **Read the briefs.** Project `./CLAUDE.md` and `~/.claude/CLAUDE.md` — they tell you who you are here (persona, project, the rules of this codebase).
+2. **Fix the wiring if needed.** If `mcp__kijito__*` tools are absent, the project is missing `.mcp.json` (server `kijito` → `http://127.0.0.1:7474/mcp/`, type `http`) and `.claude/settings.local.json` (`"enableAllProjectMcpServers": true`). Add them; new MCP tools load only on a fresh launch.
+3. **Write the identity memory.** One memory establishing persona + project + what this work is. Pass `persona` + `project` on it (and on every write after).
+4. **Open the inbox.** The first `kijito_hive_inbox(persona="<P>")` provisions the inbox; a brand-new persona just gets an empty one (not an error).
+5. **Create the current-state pointer.** A stable memory you will `kijito_update` in place going forward — record its ID. A cold boot has nothing to read otherwise. Open it with the active task and next step (or "no active work yet" if you are only setting up).
+6. **Report ready.**
+
+## Failure modes to counter
+
+- **Skimming the pointer.** Truncated previews read fine and mislead; `kijito_get` the full text of the pointer and its linked memories.
+- **Skipping the inbox.** A sibling persona may have handed you something or be blocked on you. Always check.
+- **Wrong-owner writes (new personas).** Set persona/project before the first write. `personal` / a mismatched name pollutes recall and is rejected on later edits.
+- **Acting on a stale operational fact.** Verify how-it-works memories against the real system before trusting them.
+
+## Done report
+
+State plainly: which branch you took; the persona/project; the current-state pointer ID; what the pointer says is active (or that there is none); whether the inbox had anything; and whether you are resuming work or waiting. If a fresh read could not tell what to do next, the pointer is too thin — fix it now with `/kijito-qa-memory` rather than leaving the next session to guess.
+
+## Notes
+
+- Reproducible from Kijito: the routine is also stored in the graph — `kijito_recall("session start catch-up routine arm inbox")` — so any agent can recover it without this file.
+- Pairs with `/kijito-qa-memory`: that one curates and preloads the handoff at the END of a session; this one consumes that handoff at the START. Together they make a session continuous across `/clear`.

kijito_claude-0.1.0/src/kijito_claude/__init__.py

@@ -0,0 +1,3 @@
+"""kijito-claude — installer for the Claude Code context/autonomy toolkit + Kijito skills."""
+
+__version__ = "0.1.0"

kijito_claude-0.1.0/src/kijito_claude/cli.py

@@ -0,0 +1,38 @@
+"""Console entry point: run the bundled bash installer (install.sh).
+
+The bash scripts and skills are shipped as package data under ``_assets/``. We locate
+them through ``importlib.resources`` (works whether the package is installed normally or
+run via ``pipx run``) and shell out to ``bash``. ``install.sh`` resolves its siblings
+relative to its own directory, so we run it with ``cwd`` set to the assets directory.
+"""
+
+from __future__ import annotations
+
+import importlib.resources as resources
+import shutil
+import subprocess
+import sys
+
+
+def main() -> int:
+    bash = shutil.which("bash")
+    if bash is None:
+        sys.stderr.write(
+            "kijito-claude needs bash to run its installer.\n"
+            "On Windows, run it inside WSL (recommended) or Git Bash.\n"
+            "See https://github.com/KijitoAI/kijito-claude#platform-support\n"
+        )
+        return 1
+
+    # For a normally installed wheel (pip/pipx unpack to disk) this is a real path and its
+    # siblings (scripts/, skills/) are present next to install.sh.
+    assets = resources.files("kijito_claude").joinpath("_assets")
+    install_sh = assets.joinpath("install.sh")
+    return subprocess.call(
+        [bash, str(install_sh), *sys.argv[1:]],
+        cwd=str(assets),
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())