Stateroot

Install StateRoot

The harness is disposable. The work is not. StateRoot — the persistent, federated meta-harness for AI agents — carries personality, plans, tools and skills, memories, learnings, and project context across Claude Code, Codex, Cursor, Kimi, OpenClaw, and other supported AI agents.

This is the install skill. It installs the CLI and runs global stateroot setup to connect supported harnesses. After setup, the CLI-embedded session skill becomes the default.

Docs: https://stateroot.dev/docs/getting-started/installation · https://stateroot.dev/docs/getting-started/setup
Releases: https://github.com/CognizTech/stateroot/releases

Expire first

Run the check next to this SKILL.md (never writes):

sh scripts/check.sh

If scripts/check.sh is not on disk, equivalent:

command -v stateroot && stateroot --version

Stop using this skill when all of the following are true:

1. stateroot is on PATH
2. stateroot setup has already been run on this machine (harness hooks / identity exist; stateroot doctor is not a hard fail)
3. harnesses are interfaced (stateroot install is the non-interactive half of the same wiring; setup already does it)

Then follow the built-in skill only:

stateroot skill show stateroot

That skill is what setup/init wrote into the harness. Resume, checkpoint, handoff, memory, learnings, wiki, roots — all of it lives there. If this bootstrap skill is still in context, ignore it.

Keep using this skill only when:

1. the user asked to install or set up StateRoot
2. stateroot is missing (command not found)
3. the binary exists but setup has not been run yet

Unrelated questions: do not load this skill.

What this skill does

Three commands, in order. Exact commands — do not substitute package managers, random GitHub clones, or invented download URLs.

After step 2, StateRoot can be used. Step 3 is not a substitute for setup. Never create .stateroot/ with file tools.

Platform install details: references/install.md
What gets written / privacy: references/disclosure.md
Failures: references/failures.md

Step 1 — Install

Skip if stateroot --version works.

Ask before piping a remote script to a shell. Prefer that the user run the installer themselves if they hesitate. Official assets only.

Linux (x86_64):

curl -sSfL https://github.com/CognizTech/stateroot/releases/latest/download/install.sh | sh

Installs to ~/.local/bin. Put that directory on PATH if stateroot is still not found. Needs glibc 2.17 or newer (Ubuntu 16.04, Debian 9, RHEL 7, and later).

Windows: prefer the MSI: https://github.com/CognizTech/stateroot/releases/latest/download/StateRootSetup-x64.msi

irm https://github.com/CognizTech/stateroot/releases/latest/download/install.ps1 | iex

stateroot-windows-x64.exe is the portable CLI, not an installer.

macOS (Apple Silicon):

curl -sSfL https://github.com/CognizTech/stateroot/releases/latest/download/install.sh | sh

Installs the release artifact stateroot-macos-aarch64 to ~/.local/bin after SHA-256 verification. Intel Macs are not currently supported by a release binary; build from source per references/install.md.

Verify:

stateroot --version
stateroot doctor

doctor is designed to pass with zero config and zero keys. If it fails, quote the CLI output. Do not work around a broken install by writing state files.

Step 2 — Setup (global, required)

Once per machine, immediately after the binary works. Without this, harnesses are not interfaced and the built-in skill is not the default.

Interactive is preferred:

stateroot setup

Sections: identity, harnesses, skills.

• identity — canonical soul / USER.md (import OpenClaw or Hermes if present, or a deterministic draft)
• harnesses — detect agents, write session hooks
• skills — seed the built-in StateRoot skill into detected agent directories

Non-TTY agent shell (same as --yes; do not use interactive read):

stateroot setup --yes

Optional:

stateroot setup --dry-run
stateroot setup --only identity,harnesses,skills
stateroot setup --config answers.yaml

Do not run --blank-slate unless the user asked to reconfigure.

stateroot install is the non-interactive harness-integration half if identity is already done. Setup is the full onboarding flow. Use setup after a fresh install.

When setup finishes, this bootstrap skill is done for the machine. Tell the user to keep using their usual agent. The built-in skill is now the default.

Step 3 — Init (project, only if needed)

stateroot init is not global setup. Use it only from a project root that has no .stateroot/ and that the user wants as a StateRoot project.

stateroot init

Creates .stateroot/, registers the directory in projects.toml, seeds project stubs (Cursor rule, Claude command, AGENTS.md block), and seeds the objective / memory / first handoff from what the repo declares (README, TODO.md, git log — labeled observed; --synthesize opts into LLM enrichment, labeled unverified). Never mkdir .stateroot.

Then expire this skill.

After expiry

Do not continue from this file. Do not summarize a homemade session protocol. Run stateroot skill show stateroot (or follow the copy setup already wrote into the harness) and stop.

Anti-patterns

• Inventing download URLs or installing via npm / pip / a random clone
• Guessing unsupported release assets or architectures
• Piping install.sh without asking
• Creating or editing .stateroot/ or ~/.stateroot/ with file tools
• Running setup --blank-slate unprompted
• Teaching resume / checkpoint / handoff / memory here after setup succeeded
• Staying on this marketplace skill once harnesses are interfaced

About StateRoot

StateRoot — the persistent, federated meta-harness for AI agents. The harness is disposable. The work is not.

StateRoot is an open-source, local-first CLI that federates AI agents across harnesses: they share what they know, continue each other's work, delegate tasks, and work in parallel on independent project states that merge when the work converges. When a usage limit interrupts the work—or another harness is better for the next task—you can switch without rebuilding the working relationship and project context. Claude Code, Codex, Cursor, Kimi, OpenClaw, and other supported harnesses inherit the shared state around the work.

What it does:

• Session continuity and handoffs — hooks inject a bounded project digest at session start; the next agent starts knowing the goal, the plan, decisions, and next actions.
• Cross-agent shared memory — a three-layer memory (curated hot-apex facts, an evidence-compiled wiki, searchable episodic history) with every fact labeled verified, observed, or synthesized.
• Shared learnings and self-improvement — record a correction once and every agent on the machine lives by it immediately; the team of agents gets smarter together.
• Plans across agents — a plan store with an approval lifecycle; plan with a strong model in one agent, implement with a cheaper one in another.
• Cross-agent subagents — delegate a bounded task into another agent's CLI and get back the conclusion.
• State versioning — working-tree snapshots in Git plumbing: restore, fork, merge, compare, with receipts. Your branches are never touched.
• Skills and MCP sync — SKILL.md packages and MCP server configs pooled and projected across agent configs without clobbering user content.
• Personality sharing — one persona and user profile, injected in full at every session start.
• Local-first and private — one static binary, zero config to start, everything on your machine, Apache-2.0.

Keywords for search: AI agents, meta-harness, cross-agent memory, shared agent context, project state, session handoff, context engineering, multi-agent workflow, agent skills, MCP, Claude Code, Codex, Cursor, developer tools, local-first, open source.

Homepage: https://stateroot.dev · Source: https://github.com/CognizTech/stateroot