Self-Improve (Grok Build)

Self-Improve is AI OS's platform-upgrade planner: an agent called dev-architect-grok, powered by xAI's grok-build-0.1 model, reads this platform's own real source code and proposes a structured upgrade plan — either to apply to your own running instance, or as a draft pull request against the public distribution repo. Every apply and every PR always requires your explicit approval; nothing executes automatically, regardless of your Auto-Mode setting.

How it works

You describe a goal in plain language — a feature, a refactor, a dependency upgrade, a bug fix — from the Self-Improve dashboard view or via Hermes's dev-project delegation mode. From there:

1. dev-architect-grok reads the real codebase using bounded, read-only Read/Grep/Glob tools — it never guesses at a file it hasn't actually looked at
2. It returns a structured plan: a summary, a risk rating, rollback notes, and the complete new content of every file it touches
3. You review the plan in the dashboard, including the full proposed content of every file — not just a path and a one-line reason
4. You choose to apply it to this instance, propose it as a distribution blueprint, or discard it
5. Either action queues to your Approvals inbox; nothing happens until you approve it there

The agent has no write access of its own — Read/Grep/Glob only. A separate, code-enforced executor is the only thing that ever touches disk or calls the GitHub API, and only after your approval.

Two ways to use a plan

Apply to this instance

Writes the plan's files directly into your own running AI OS installation. Before any write happens, the apply engine takes a git snapshot commit as a rollback point — if anything fails partway through, it automatically reverts to that snapshot rather than leaving a half-applied repo. Every file path is checked against a denylist (secrets, .git/, node_modules/, the private commercial module) and every write is atomic.

Propose a distribution blueprint

Opens a draft pull request on a brand-new branch against your configured distribution repository (by default, the public wholefoo/ai-os repo). This path has no code that can update an existing branch ref, so it structurally cannot touch your default branch. You review, edit, close, or merge the resulting PR yourself on GitHub — Self-Improve never merges anything.

Safety architecture

Self-Improve is the platform proposing changes to its own code, so it's held to a higher bar than routine automation:

• Always gated, no exceptions — applying a plan and opening a distribution PR are hard-coded to always require human approval, independent of your Auto-Mode setting (even "auto" mode, which lets other action types run unattended, does not bypass this)
• Git snapshot before every write — no snapshot, no apply; this is enforced, not best-effort
• A checked path denylist — re-validated at apply time even though the plan was already checked when proposed, and hardened against case-insensitive filesystems, symlink/junction escapes, and reserved Windows device names
• Draft-PR-only distribution — the only way to publish a blueprint is a new branch and a draft PR; there is no path that writes to your default branch

Hermes integration

Self-Improve's dev-project planning is also reachable through Hermes, alongside two other real Hermes skills that ship with this feature: news-brief (a live intelligence sweep via the scout agent) and uptime-check (a health-snapshot review via the sysadmin agent, backed by real disk, memory, and load metrics). Hermes's other skills — inbox summaries, GitHub repository backups, and social comment monitoring — remain simulated pending their own real integrations.

Configuration

Setting	Where	Description
xai_api_key	Settings → AI Keys	xAI API key used to call grok-build-0.1 (same key used for Grok live search)
self_improve.github_pat	Settings → Self-Improve	GitHub personal access token, repo scope — used only to open draft distribution PRs
self_improve.distribution_repo	Settings → Self-Improve	Target owner/repo for distribution blueprints (defaults to wholefoo/ai-os)

API Endpoints

Frequently asked questions