Self-Improving AI

A skill lifecycle for OpenCode, Claude Code, and Codex. It turns useful lessons from completed work into reusable Agent Skills.

It does not retrain the model. It writes and maintains instructions that the model can use on later tasks.

Memory and skills

The loop has two durable outputs:

• Memory stores facts, decisions, preferences, corrections, and ongoing context.
• Skills store reusable procedures, decision rules, tool usage, and verification.

It pairs naturally with GBrain: GBrain provides the memory layer, while this starting skill grows and refines the procedural skill layer. GBrain is optional; agents without it can use their existing memory mechanism.

Install

Each adapter uses the model and credentials already configured in its client. There is no second provider account or API key to set up.

OpenCode

Install the skill globally for OpenCode:

npx skills add https://github.com/hueyexe/self-improving-ai \
  --skill self-improving --agent opencode --global --yes

Append this entry to the existing plugin array in ~/.config/opencode/opencode.json. Keep your other plugin entries:

{
  "plugin": ["self-improving-opencode@latest"]
}

Use the tuple form only when overriding defaults:

[
  "self-improving-opencode@latest",
  {
    "minToolCalls": 10,
    "correctedMinToolCalls": 5,
    "readOnlyMinToolCalls": 20,
    "staleAfterDays": 30,
    "archiveAfterDays": 90,
    "curatorIntervalDays": 7,
    "debug": false
  }
]

Fully quit and restart OpenCode after changing the config. OpenCode installs the package from npm when it starts.

Claude Code

Install the skill globally for Claude Code:

npx skills add https://github.com/hueyexe/self-improving-ai \
  --skill self-improving --agent claude-code --global --yes

Then add the plugin marketplace and install the completion adapter inside Claude Code:

/plugin marketplace add hueyexe/self-improving-ai
/plugin install self-improving@self-improving-ai

Start a new session after installation. After the transcript reaches 12,000 bytes, the hook launches a detached claude -p review using the user's existing Claude Code model and credentials. If detached execution is unavailable, it falls back to the guarded in-session completion check.

Codex

Install the skill globally for Codex:

npx skills add https://github.com/hueyexe/self-improving-ai \
  --skill self-improving --agent codex --global --yes

Then add the plugin marketplace and install the completion adapter:

codex plugin marketplace add hueyexe/self-improving-ai
codex plugin add self-improving@self-improving-ai

Open /hooks in Codex and trust the new hook, then start a new thread. The adapter launches a detached codex exec review after the transcript reaches 12,000 bytes, using the user's existing Codex model, provider, and credentials. If detached execution is unavailable, it falls back to the guarded in-session completion check.

Other agents

Other clients can use the skill without an automatic completion adapter. Install it for every client supported by the Skills CLI:

npx skills add https://github.com/hueyexe/self-improving-ai --all --global

OpenCode note: the global agent-compatible location opencode v2 reads is ~/.agents/skills/ (one of six search paths — https://opencode.ai/docs/skills/). If the Skills CLI writes elsewhere for your setup, copy skills/self-improving/ to ~/.agents/skills/self-improving/ manually. OpenCode requires a restart to see skills added while it is running (Skill.state caches per process).

Eve and PromptScript currently report failures because they do not support global skill installation. Other supported clients still install successfully.

OpenCode background flow

The plugin records tool activity during a session. This is a small local JSON update; it does not call a model after every tool use.

When the session becomes idle, the plugin checks the work since the previous review. A review is queued after:

• 10 tool calls when files changed;
• 5 tool calls when failures were encountered;
• 20 tool calls for read-only work.

Idle detection (v0.3.0): interactive sessions emit session.idle, but headless opencode run finishes with session.execution.{succeeded,failed,interrupted} instead — verified empirically on v2.0.5, a full headless run emits no session.idle at all. The plugin now treats both shapes (plus the session.status+idle variant) as review triggers, so reviews queue in either mode.

The queued job opens an isolated OpenCode child session with the same provider and model as the parent session. The child has no tools. It reads the relevant conversation and returns one structured decision: create a skill, patch a managed skill, or do nothing.

The model never applies its own proposals (v0.3.0). Plugin code checks the response, rejects unsafe paths and changes to unmanaged skills, and writes it as a pending proposal to ~/.local/share/self-improving-ai/proposals/. Nothing is applied to your skills directories until a human runs:

self-improving-ai proposals            # list pending proposals with diffs
self-improving-ai proposals apply <id>
self-improving-ai proposals reject <id>

This is the safe-inheritance gate from the RSI literature (unattended self-modification regresses in a nontrivial share of trials — The Last AI Built by Humans, https://arxiv.org/abs/2609.11873 §6; Dream-RSI, https://arxiv.org/abs/2609.14858) and mirrors the Warp production skill loop: inner skill does work, outer reviewer proposes, human merges. A Hermes-side companion cron (~/.hermes/scripts/skill_improver_scan.py) also surfaces pending proposals weekly. The child session is deleted when the review ends.

Interrupted jobs are retried up to three times after a restart.

This work happens after idle and does not block the conversation. It does use a model call when a review threshold is reached. Ordinary chat and short sessions do not trigger one.

Files and ownership

State is stored under ~/.local/share/self-improving-ai/ by default. Skill files remain under ~/.agents/skills/, where OpenCode and other clients can find them. Generated skills are marked in SKILL.md:

metadata:
  managed-by: self-improving-ai
  provenance: self-improving
  maturity: candidate

The state directory contains the review queue, registry, audit log, session counters, backups, and archived skills. Only skills created by this plugin or explicitly adopted by the user are managed. Other installed and hand-written skills are left alone. Pinned skills are also left alone.

Managed skills become stale after 30 days without use and are moved to the recoverable archive after 90 days. Curation runs at most once a week. It never deletes, commits, pushes, or publishes anything.

Manage the lifecycle

Inspect and manage the lifecycle with the package CLI:

npx self-improving-opencode status
npx self-improving-opencode dry-run
npx self-improving-opencode consolidation-report
npx self-improving-opencode pin api-error-triage
npx self-improving-opencode unpin api-error-triage
npx self-improving-opencode adopt existing-skill ~/.agents/skills/existing-skill
npx self-improving-opencode archive api-error-triage
npx self-improving-opencode restore api-error-triage

consolidation-report performs a conservative, read-only overlap scan of managed skills. It reports possible duplicates but does not merge them.

Claude Code and Codex

Claude Code and Codex review at most once per session. Both default to a 12,000-byte transcript threshold. Their detached workers use the model and credentials configured in the client. Claude Code disables reviewer tools; Codex runs the reviewer in its read-only sandbox.

Optional GBrain context

For Claude Code or Codex, enable GBrain context for their completion review by setting this environment variable before launching the client:

export SELF_IMPROVING_GBRAIN=1

Reviewers currently handle procedural skills only; they do not write factual memory. This flag does not install or configure GBrain. Follow the GBrain repository for setup. The flag only tells the review to use GBrain, when available, for durable non-procedural memory while keeping procedures in Agent Skills.

Claude Code and Codex threshold overrides:

export SELF_IMPROVING_MIN_TRANSCRIPT_BYTES=12000 # Claude Code and Codex

Set the transcript threshold to 0 to review every Claude Code or Codex session. Lower thresholds increase cost and low-value skill churn.

Set OpenCode's debug option to true, or set SELF_IMPROVING_DEBUG=1, to record activity decisions and review outcomes in the OpenCode log. Debug logging does not add messages to the session.

Manage the skill

List the installed skill and its source:

npx skills list --global

Update it from GitHub:

npx skills update self-improving --global --yes

Remove it:

npx skills remove self-improving --global --yes

Release the OpenCode package

Maintainers publish releases explicitly. Update version in package.json, then run:

bun run check
bun test
bun run build
bun publish --access public
git tag -a "v$(bun -p 'require("./package.json").version')" -m "Release"
git push origin main --follow-tags
gh release create "v$(bun -p 'require("./package.json").version')" \
  --generate-notes --verify-tag

Skill conventions

• skills/self-improving is the only starting skill.
• Skills created by the loop use clear capability-based names.
• Generated skills carry controlled provenance and maturity metadata so they remain easy to identify and export. Skills may also define their own category and scope metadata.
• New workflows start as candidate, become validated after focused testing or successful reuse, and become proven after repeated use.
• Repository-specific procedures remain with their repository rather than being generalized into this collection.

Each directory under skills/ follows the Agent Skills specification.