๐บ๐ธ English ๏ฝ ๐ฏ๐ต ๆฅๆฌ่ช ๏ฝ ๐จ๐ณ ็ฎไฝไธญๆ ๏ฝ ๐น๐ญ เนเธเธข
Your AI keeps suggesting improvements to its own setup โ new tools, better prompts, workflow tweaks.
Adopting them by hand doesn't scale; letting the AI change things by itself is how setups get quietly broken.
self-growth-loop turns every suggestion into a tracked proposal that must earn its way through testing, risk-scaled review, and your explicit approval before anything changes.
Growth you can audit. Every change passes a human gate.
๐ง Engineering guide ๏ฝ ๐ Specifications
generation: 1d006b1 (2026-09-07T06:16:41Z) ยท verify: API HEAD ยท status.json
- Your AI assistant says "we should adopt tool X" โ and the idea dies in a chat log because there's no process for it
- You tried letting an agent tweak its own configuration once, and spent an evening figuring out what changed
- Improvement ideas pile up with no record of what was tried, what worked, and what was rejected
- You want your AI to get better over time, but not behind your back
self-growth-loop exists for exactly this gap: it gives AI-driven improvement a paper trail and a brake pedal.
Every improvement idea becomes one file in a ledger that moves through five gates. Nothing skips the human gate.
flowchart LR
S[sense<br/>collect ideas] --> P[propose<br/>one file per topic]
P --> T[trial<br/>isolated test run]
T --> C[council<br/>multi-model review]
C --> H{{human approval<br/>PENDING_OWNER}}
H --> A[adopt<br/>backup + rollback plan on record]
style H fill:#f9e79f,stroke:#b7950b,stroke-width:3px
- ๐ Tracks โ every proposal is a plain-text file with a full state history: who proposed it, what was tested, who voted, who approved
- ๐งช Tests first โ proposals run as isolated trial tasks in a sandboxed engine workspace, never in your live setup
- ๐ณ๏ธ Cross-examines โ anything beyond the lowest risk tier gets a council of different AI models reviewing the trial evidence independently before it reaches you
- โ Waits for you โ every adoption stops at an approval queue until a human says yes; nothing applies itself
- ๐ Backs out โ every adoption records a verified backup reference and a rollback plan, and a lint โ run daily by the bundled cron once installed โ catches stuck or damaged records
Here is one proposal's life, start to finish.
One proposal's life: a feed item ("tool X looks useful") becomes a ledger record (PROPOSED). The trial runner packages it as a task and hands it to the engine, which runs it in an isolated workspace (TRIALING). Results come back as evidence files; for anything beyond the lowest risk tier, a panel of different AI models each reads the evidence and votes (COUNCIL โ the lowest, reversible tier records a sealed skip instead and goes straight to your queue). If it passes, the record waits in your approval queue (PENDING_OWNER) โ the queue report shows you every waiting decision. Only after you approve does the record move to ADOPTED, with a verified pre-adoption backup reference and a quantified rollback plan already on the file โ the owning runtime then applies the change. Reject it, and the record says so forever โ the same idea won't come back unless something material changes. To run this yourself, you need very little.
| Requirement | Notes | |
|---|---|---|
| OS | macOS | โ tested (stock bash 3.2 + system ruby, no gems) |
| Linux | โ CI tested | |
| WSL2 | โ with caveats โ see Linux / WSL2 scheduling | |
| Standalone use | nothing else | ledger + lint + queue report work with just this repo |
| Trials | a local checkout of caty-agent-harness | the engine that runs trial tasks (pinned: v0.6.0) |
Paste this to your coding agent (Claude Code, Codex, etc.):
Clone https://github.com/caty-ai/self-growth-loop and run
make test. Then show me how to create a demo proposal with scripts/propose.sh against a temporary vault directory.
git clone https://github.com/caty-ai/self-growth-loop.git
cd self-growth-loop
# create a demo proposal in a throwaway vault
mkdir -p /tmp/sgl-demo-vault
bash scripts/propose.sh --vault /tmp/sgl-demo-vault \
--topic-key demo-tool__acme --title "Trial the demo tool" \
--state PROPOSED --proposer mine \
--url https://example.com/item --report reports/demo.md
# run the health check and read the queue report it writes
bash scripts/growth-lint.sh --vault /tmp/sgl-demo-vault
cat /tmp/sgl-demo-vault/25_review-pending/self-growth-queue.mdYou just ran the loop's bookkeeping end to end: a proposal record was created, linted, and reported. (The report will shout SENSE BROKEN โ expected: a standalone demo has no feed collector wired in.) Undo everything with rm -rf /tmp/sgl-demo-vault โ the repo itself was never written to.
Run the full test suite (needs the engine)
# ~/claude-workspace/caty-agent-harness is the default lookup path (SGL_ENGINE_SOURCE)
git clone https://github.com/caty-ai/caty-agent-harness.git ~/claude-workspace/caty-agent-harness
cd self-growth-loop
make test # full suite; the engine integration test drives the real enginePoint SGL_ENGINE_SOURCE at your engine checkout if it lives somewhere else.
- The human gate is structural, not polite. Every adoption stops at
PENDING_OWNER, the dedicated owner-approval queue (engine governance rules, rule R4) โ and this repo's own adoption rules apply it to every tier: the lowest-risk council-skip path never skips the owner. No code path advances a record toADOPTINGwithout a verified owner-authorization artifact; identity-critical changes always additionally pass the full council (rule R12a). - Trials never touch your live setup. They run in an isolated engine workspace (docs/trial-isolation.md); the only thing this plugin ever writes into an engine is a task file.
- A single-writer protocol with locking. The ledger names one writer of record (plus the lint's narrow timeout lane), every write goes through the same lock, and every transition leaves an event line โ a state won't be silently rewritten (docs/ledger-spec.md).
- Rollback is part of adoption. A record can't be approved without a verified pre-adoption backup reference on it, and a quantified rollback path that the daily lint audits (docs/adoption-wiring.md).
Not for you if: you want a fully-automatic self-improving agent with no human in the loop โ this tool is built to prevent exactly that.
- Standalone โ this repo + a directory for the ledger. Propose, lint, and review by hand. (That's what the Quickstart above does.)
- Connected โ plug into a wider setup, all optional: a feed collector supplying ideas (sense โ e.g. X Collector), the caty-agent-harness engine running trials, launchd or Linux systemd/cron scheduling for the wrappers (
ops/, install note in INTEGRATION.md), and a dead-man heartbeat if you have external monitoring.
| Component | Status | Where |
|---|---|---|
| Proposal ledger (schema, state machine, single-writer) | โ implemented | docs/ledger-spec.md, scripts/propose.sh (#1) |
| Failure visibility (growth-lint, queue report, timeouts) | โ implemented | scripts/growth-lint.sh (#2, #5) |
Trial runner (task bundles via engine tr-enqueue) |
โ implemented | scripts/trial-enqueue.sh, trial-poll.sh (#6, #21) |
| Council (cross-model verdicts, quorum by tier) | โ implemented | scripts/council-*.sh, docs/council-wiring.md (#10, #13) |
| Adoption executor (approval queue, rollback records) | โ implemented | scripts/adopt-*.sh, docs/adoption-wiring.md (#11, #16) |
| Shared-library extraction | โณ deferred | deliberately waits for a second plugin (see extraction policy in the engine's plugin-convention) |
Every โ
row ships with tests โ run them with make test; the suite includes an engine integration test that drives the real engine at its pinned tag.
- CI: Every pull request runs the shared test-and-lint caller on Ubuntu and macOS, plus gitleaks, history-check, PR-size, publication-gate and risk-review.
mainrequires all eight checks.make testremains the local gate. - Verified environments: macOS and Ubuntu (bash 3.2+, system ruby) โ both are exercised by CI on every pull request. No other OS has been verified.
- Maturity: reference โ campaign-designated for this repository. Publication-gate wiring is in place.
- Known constraints: ruby is required (entry scripts exit 127 without it); engine integration is pinned to caty-agent-harness v0.6.0.
| Doc | What's inside |
|---|---|
| INTEGRATION.md | Engine seams, pinned version, cron install, integration-test policy |
| docs/ledger-spec.md | Record schema, topic identity, state machine, locking |
| docs/trial-isolation.md | Isolation tiers per risk level |
| docs/council-wiring.md | Panel composition, verdict schema, quorum, retries |
| docs/adoption-wiring.md | Approval gate mechanics, rollout, rollback |
Part of the Caty AI family โ open tools for running a family of AI agents. The full map, including modules still being prepared for release, lives in Family OS.
| Axis | Module | What it does | State |
|---|---|---|---|
| Map | Family OS | The map of the whole family โ every module, its state, and how they fit | published, MIT |
| Rules | Family Dev Handbook | The rules of the road โ issues, PRs, worktrees, handoffs, parallel development | published, MIT |
| Vertical ยท foundation | Caty Agent Harness | Task backbone for AI agents โ retries, checkpoints, and honest completion | published, MIT |
| Vertical | context-kit | Six-piece context hygiene kit for one agent โ bounded output, delegation briefs, safety guards, recall, worktree snapshots | published, MIT |
| Vertical | Persona Engine | Layers relationship and emotion onto an agent's existing persona | published, MIT |
| Vertical | Persona Growth Loop | Grows the persona itself โ minimal, idempotent proposals | published, MIT |
| Vertical | X Collector | Turns X and the web into one daily digest โ for people and agents | published, MIT |
| Vertical | Self Growth Loop | Lets an agent grow its own abilities โ proposals, governance, adoption records | published, MIT |
| Horizontal ยท foundation | Family Memory Architecture | The memory bus โ how the family shares what it knows | published, MIT |
| Horizontal | Sitter | Babysits delegated agent runs โ watches, keeps evidence, restarts only within declared bounds | published, MIT |
| Horizontal | Alpha Nightshift | Nightly autonomous maintenance loop โ isolated night lanes behind a deny-by-default guard; humans cherry-pick in the morning | published, MIT |
| Horizontal | errmeter | Reports failed or silent AI agents and scheduled jobs across machines โ emit, spool, shared board, repair hook; a shout that is never lost | published, MIT |
| Vertical | Caty Gateway | PC-side gateway for CatyPhone โ one-line install; pairs your phone with the agent running on your machine (Claude Code / Codex CLI / OpenClaw / Hermes / OpenAI-compatible) | published, MIT |
Issue-first: 1 issue = 1 branch = 1 pull request, no self-merge. See CONTRIBUTING.md and the family dev handbook.
MIT โ so anyone can use, study, and build on this freely.
bash + ruby, no gems ๏ฝ one proposal = one file ๏ฝ every change passes a human gate