Claude Code harness that refreshes its own context instead of compacting: at a threshold it writes a verified capsule, runs /clear, and resumes in a fresh session. Memory is plain markdown in git, readable with git log. MIT, runs locally, one install (Node 18+). Codex adapter included.
See the codeClaude Code that refreshes its own context instead of compacting.
Open-source (MIT) harness for one long-running Claude Code session. With Managed Auto-Refresh, when context reaches a threshold it saves a verified capsule, runs /clear, and resumes the work in a fresh session. No summary of a summary, no re-briefing. Around that loop sits an operator layer: skill routing, guarded memory and specialist sub-agents that help with the work itself.
Install · Demo · Evidence and limits · Operator · What it changes · Uninstall · FAQ · Alternatives · Docs
Stop re-briefing your AI every morning.
From the team behind The AIgent, a free media project for people building with AI.
Claude Code has a fixed context window. When it fills, the usual options are to let it auto-compact (the model summarizes the conversation and keeps going on the summary) or to /clear and re-explain everything yourself. aigent-OS takes a third path. Before the window fills (default 80%, configurable with AIGENT_PRESSURE_THRESHOLD_PCT), it asks Claude to write a resume-ready checkpoint file (a "capsule"). It waits for Claude to confirm the capsule is complete, sends exactly one /clear, checks that a fresh session started, and tells that new session to load the capsule and carry on. No confirmation, no clear. Your notes, decisions and open threads live in plain markdown files you keep in git (aigent-OS commits and pushes them at each capsule cycle when the install folder has a git remote), so you can read, diff and roll back exactly what your agent remembers. It runs on your machine; aigent-OS has no server of its own.
Requires Claude Code, Node.js 18+ with npm, and bash (on Windows, Git Bash from Git for Windows).
git clone https://github.com/wrg32786/aigent-os.git && cd aigent-os && bash install.sh --dry-run
The dry run prints the planned changes and writes nothing. When the plan looks right, run bash install.sh in the same folder, open a new terminal, and run aigent. The first launch runs guided setup.
To install into an existing project instead of the cloned folder, run bash install.sh --target <dir> from the clone (preview it with --dry-run first). Before you start working, read What this changes on your machine, including the note on vault sync and git remotes. More options: Quick Start.
/clear, and one fresh session, with zero stranded acknowledgements and zero duplicate clears. Write-up: the companion paper, governed-agent-organizations, hypothesis H2, and its continuity and Auto-Refresh case study. More detail: Release evidence./clear. Fixes for the three reproduced defects are in review, integrated on PR #62. Until that lands, check that the latest capsule and any work in flight are saved before you clear by hand. See the v1.1.0-rc.1 release notes.Auto-Refresh is what keeps a long-lived agent going. The rest of aigent-OS is about what that agent does with the time. It keeps working across days: each refresh resumes from a checked capsule, and it will not resume into one that recorded no next step. It remembers what matters: memory is markdown in git, a fact whose validity window has ended ranks below the current one, and guards keep always-loaded memory small and hold planted instructions for review. Live failures turn into guardrails: when the seats we run hit a problem, the fix comes back to this repo with a test. And on every prompt, it is pointed at the skill in your catalog that fits what you asked.
| Capability | What it does | Status |
|---|---|---|
| Live failure to fix loop | Problems found on the maintainers' live seats come back to this repo as fixes and regression tests, gathered in a weekly fleet-to-product port sweep (for example PR #69). A Stop hook also flags turns whose confident claims ("fixed", "verified") went unrecorded. | On by default (the fixes and the hook ship in the core; the sweep is how we maintain the repo) |
| Failure-to-fix procedure | A written procedure asks the agent to turn a failure seen twice into a skill, a check or a routing rule. No code forces it, and the ledgers ship empty. | Experimental (a skill the agent follows) |
| Memory guardrails | A size budget on always-loaded memory files, staged memory that tries to give instructions is held for review, anything read back from memory is treated as data and never as an instruction, and folders you mark confidential stay out of search | On by default |
| Skill caddy | A hook matches each prompt against your skill catalog and suggests the skill that fits. It never blocks the turn, and when nothing fits it points at /skill-recall so the gap gets logged. | On by default |
| Nine named specialist agents | A builder, a read-only scout, a researcher, a design spec writer, a memory architect, a critic, a vault custodian, an architecture reviewer and a prompt writer, each with a fixed model tier and tool set (roster). A hook checks every dispatch against the agent's declared tier (details). | On by default (warns); block is opt-in with AIGENT_MODEL_GUARD=enforce |
| C2 temporal supersession | A note can carry a validity window. Once it ends, search ranks the note below current ones instead of deleting it (details). | On by default for notes with a validity line; in v1.1.0-rc.1 |
| Hindsight and Jev memory bridge | Explicit retain, recall, reflect and ranking against providers you configure, with every result checked against a local source (details) | Opt-in; on master, not in a release, not verified against the live services |
| Gateguard | The first edit of each file in a session waits until the agent names what depends on it, what the change affects and the instruction it is following | Opt-in with AIGENT_GATEGUARD=enforce |
| Codex adapter | Routes one bounded, mechanical task type to codex exec and writes a diff for review; never commits or pushes (details) | Opt-in when you invoke it; one task type |
| fleet-band and fleet-delivery mods | A status line above the prompt, and delivery of messages and scheduled job results into an idle session, once each (mods) | Opt-in pilot (fleet-delivery runs on one seat); on master, not in a release. Delivery needs a message room and a job-results source that are not in this public repo yet |
| Agent teams ("crews") | Guidance on when to run a standing team, a one-shot fan-out or a solo agent | Guidance only; no code |
| Self-testing of its own operating rules | Testing a seat's behavior against its own rules | Roadmap |
Four aigent-OS seats, Titus, Pheme, Davinci and Metis, run The AIgent, a newsletter for people building with AI with close to 9,000 subscribers. When those seats fail in live use, the failure comes back to this repo as a fix and a test. One example: daemons/tests/capsule-sentinel-selection.test.mjs records a check of the four live seat vaults on Aug 1, 2026, which found that three of the four would have resumed into a checkpoint with no actionable content. The capsule selector now refuses that kind of checkpoint, and the test defends it. This is operating experience, not a measured outcome. We do not claim that aigent-OS grew the newsletter, reduced operator effort or improved business results; the companion paper lists those as not established in its limitations and non-claims.
The animation is a scripted illustration of the lifecycle, not a screen recording. In the shipped default, Managed Auto-Refresh is designed to run the whole boundary without operator input: at the configured context threshold (default 80%) it requests a capsule, waits for the exact completion acknowledgement, submits one /clear, binds the fresh session, and submits one resume wake. The shipped settings also set "idleCompaction": false, so Claude Code's own idle compaction (which can summarize a quiet session after about 55 minutes once it holds 200k tokens) cannot replace that boundary. In v1.1.0-rc.1 a long session can still stop at the clear step and need a manual /clear; see Evidence and limits.
Run bash install.sh --dry-run first; it lists the planned changes and writes nothing. Below, <target> is the folder you install into: the cloned aigent-os folder by default, or the directory you pass with --target. The installer does not edit your user-level ~/.claude/settings.json or ~/.claude/CLAUDE.md.
| Where | What the installer does | How to undo |
|---|---|---|
<target>/.claude/settings.json | Creates it, or merges into your existing file and saves a backup in <target>/.aigent/backups/. Adds hooks on seven Claude Code events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd), a statusLine command, and the AIGENT_ROOT and AIGENT_VAULT env values. If your existing file is not valid JSON, it is left untouched and the new settings are written to .claude/settings.aigent.json for you to merge. | Restore the backup, or delete the file if the installer created it |
<target>/.claude/skills/, .claude/agents/, .claude/skill-index.json, .claude/rules/post-compact-critical.md, .claude/settings.json.template | Copies the skill folders from skills/, the agent definitions from vault/agents/, the skill index, a starter rules file (only if you have none), and the settings template | Delete what was added |
<target>/CLAUDE.md | --target installs only: creates the file, or appends one block between <!-- aigent-os:start --> and <!-- aigent-os:end --> and saves a backup. Your text outside the markers is kept. In the cloned folder, CLAUDE.md is the repo's own file and is not edited. | Delete the block between the markers |
<target>/system/, vault/, memory/, hooks/, skills/, daemons/, scripts/, docs/, evals/, launcher/ | --target installs only: copies framework files that are missing and never overwrites yours silently. vault/ and memory/ hold your memory as plain markdown. | Delete the folders aigent-OS created. If your project already had a folder with one of these names (docs/ and scripts/ are common), remove only the added files; git status lists them |
| Files that differ from the framework copy | Under system/, skills/, hooks/, daemons/, scripts/, launcher/, .claude/skills/ and .claude/agents/, an existing file that differs from the framework version is moved to <target>/.aigent/quarantine/ and replaced, because Claude Code would trust it. --trust-existing keeps them instead. | Copy the file back from .aigent/quarantine/ |
<target>/.aigent/ | First-run state (state.json), backups and quarantined files | Delete, after restoring anything you need from it |
<target>/.gitignore | Adds a block between # aigent-os:generated-state:start and # aigent-os:generated-state:end covering local state such as .aigent/, node_modules/, .obsidian/ and the prompt journal. Saves a backup if the file existed. | Delete the block |
<target>/daemons/semantic-search/node_modules/ and <target>/daemons/transport-deps/node_modules/ | Runs npm ci --ignore-scripts for local semantic search (@xenova/transformers) and the refresh runner (node-pty, rebuilt for your platform). --no-deps skips this and falls back to an unmanaged launch without automatic clear. | Delete the two node_modules/ folders |
~/.local/bin/aigent (macOS, Linux) | Symlink to <target>/launcher/aigent.sh. --no-launcher skips all launcher wiring, and a target under the system temp directory skips it automatically. | rm ~/.local/bin/aigent |
~/.bashrc (macOS, Linux) | Appends export AIGENT_HOME=<target> and export PATH="$HOME/.local/bin:$PATH" if they are not already there. The launcher installer runs under bash, so it writes ~/.bashrc even when your login shell is zsh. | Delete those lines (keep the PATH line if other tools rely on ~/.local/bin) |
~/Applications/AIgent.app (macOS) | An app bundle that opens Terminal and runs aigent | Delete the app |
Git config of <target> (macOS, Linux) | Sets core.fileMode false if <target> is a git repo, so the launcher's executable bit never blocks a git pull | git -C <target> config --unset core.fileMode |
| Windows user environment | Sets the AIGENT_HOME user variable, writes %USERPROFILE%\.aigent\bin\aigent.cmd, adds that folder to your user Path, and creates AIgent shortcuts on the Desktop and in the Start Menu | See Uninstall |
~/.claude/ctx-refresh/ (while running) | The status line writes one small JSON file per session with the current context percentage, which the refresh runner reads | Delete the folder |
Network and data. aigent-OS has no server of its own. What does use the network:
npm downloads packages during install.all-MiniLM-L6-v2 model files from Hugging Face the first time it runs. Embedding and search then run on your machine.<target> is a git repo with a remote, aigent-OS commits the memory folder and pushes it to that remote. No repo or no remote means no push. If you installed in the cloned folder, its origin is this public GitHub repo, so point origin at your own private repo (git remote set-url origin <your-private-repo>) or remove it (git remote remove origin) before you start working..aigent/memory-bridge.json, and then calls only the providers you set.There is no uninstall script. Removal is manual and mirrors what the installer did. Save anything you want to keep from vault/ and memory/ first: that is your agent's memory.
aigent command and shortcuts.
rm ~/.local/bin/aigent, then delete the export AIGENT_HOME=... line (and the ~/.local/bin PATH line, if nothing else needs it) from ~/.bashrc. On macOS, also delete ~/Applications/AIgent.app.%USERPROFILE%\.aigent\bin, remove that folder from your user Path (System Properties, Environment Variables), run [Environment]::SetEnvironmentVariable('AIGENT_HOME', $null, 'User'), and delete the AIgent shortcut from your Desktop and from %APPDATA%\Microsoft\Windows\Start Menu\Programs.--target:
.claude/settings.json, CLAUDE.md and .gitignore from the timestamped backups in .aigent/backups/, or edit them by hand: delete the aigent-OS block between the markers in CLAUDE.md and .gitignore, and remove the aigent-OS hooks, statusLine and env entries from .claude/settings.json (or delete the file if the installer created it)..claude/settings.json.template, .claude/skill-index.json, .claude/rules/post-compact-critical.md, and the skills and agents aigent-OS added under .claude/skills/ and .claude/agents/.system/, hooks/, daemons/, scripts/, docs/, evals/, launcher/, memory/, vault/). Where your project already had a folder of the same name, remove only the files aigent-OS added..aigent/quarantine/, then delete .aigent/.<target> is a git repo: git -C <target> config --unset core.fileMode.~/.claude/ctx-refresh/.aigent-OS refreshes the session before the window fills, so compaction is not the path it relies on. At a threshold (default 80%) it saves a verified capsule, runs /clear, and resumes in a fresh session from that capsule. If a compaction happens anyway, a PreCompact hook first flushes the latest state into the capsule and hands the compactor pointers into the vault.
Without add-ons, Claude Code compacts the conversation into a summary and continues, or you run /clear and start over. Compaction keeps going on a summary; /clear loses everything you did not save. aigent-OS automates a third option: save a structured checkpoint, clear, and reload the checkpoint in the new session.
Use /compact when a summary is good enough and you want to keep going; use /clear when you want a clean window. aigent-OS is for people who want the clean window of /clear without re-briefing, and it runs the save, clear and resume sequence for you. One caveat for now: in v1.1.0-rc.1 a long session can still stop at the clear step (see Evidence and limits).
aigent-OS adds a git-tracked markdown vault that every session reads at start and writes at checkpoints. Claude Code's own CLAUDE.md files and auto memory already carry instructions and learned notes across sessions. The vault adds daily notes, decisions, open threads and capsules on top of that, plus local semantic search over it, all in files you can open, diff and roll back.
That is the use case aigent-OS is built for: one long-running session that keeps cycling through refreshes. The public evidence so far is 11 of 11 cycles on one machine, which is not a reliability guarantee, and the known limitation above still applies.
It is the aigent-OS loop that replaces compaction. At the context threshold it requests a capsule, waits for the exact acknowledgement "Capsule Complete, Ready For Clear", submits exactly one /clear, checks for a fresh session identity, and submits one resume prompt. No acknowledgement means no clear. Details: Auto-Refresh.
We do not claim that. It is a different trade-off: an explicit, inspectable checkpoint and a clean window, instead of a model-written summary. Try both on your own work.
aigent-OS manages the context boundary itself (checkpoint, clear, resume) and keeps memory as markdown in git. claude-mem captures what your agent does, compresses it with AI and injects relevant context into later sessions, with its store outside version control. context-mode reduces how much context tool output uses and persists session memory. They solve overlapping problems in different ways; see Alternatives.
Yes, through Git Bash. install.sh needs a real bash, so install Git for Windows first; PowerShell alone cannot run it. The installer then wires an aigent command and Desktop and Start Menu shortcuts. The public 11 of 11 evidence comes from a Windows seat, and CI runs the installer on Windows, macOS and Linux. macOS has the least live mileage with the managed runner.
aigent-OS is free and MIT-licensed. You pay for Claude Code the way you already do. Each refresh cycle uses some tokens, because Claude writes a capsule before the clear and reads it back after. The optional memory bridge and Codex adapter can incur charges from the providers you configure.
Claude Code is the host. A Codex adapter routes one bounded task class to codex exec, review-gated and never auto-merged. Other CLIs are on the roadmap, not shipped.
aigent-OS has no server; your vault is local files and semantic search runs on your machine. Claude Code still sends your conversation to Anthropic, and vault sync pushes memory commits to your git remote if the install folder has one. See Network and data.
See What this changes on your machine and Uninstall. bash install.sh --dry-run shows the planned changes before anything is written.
Not yet: Managed Auto-Refresh is in a v1.1 release candidate. See Evidence and limits for what is and is not shown.
Yes: four aigent-OS seats run The AIgent newsletter, which is operating experience rather than a measured result; see In production.
Some of it is mechanical and on by default (memory guards, skill routing, the model-tier check, fixes from live failures shipped with tests), while turning a repeated failure into a new skill or check is a written procedure the agent follows, and we make no measured improvement claim; see Operator.
A neutral guide to what fits which need (descriptions checked Oct 2026):
| If you want | Consider |
|---|---|
| Built-in, zero setup | Claude Code's own auto-compaction, /compact, /clear, CLAUDE.md and auto memory |
| Automatic capture of what your agent did, compressed and injected into later sessions | thedotmack/claude-mem |
| Less context used by tool output | mksglu/context-mode |
| A memory service that learns across agents | vectorize-io/hindsight (aigent-OS has an opt-in bridge) |
| Persistent teams of Claude Code, Codex and Pi agents | mvschwarz/openrig |
| One long-running Claude Code session that checkpoints, clears and resumes instead of compacting, with git-auditable memory | aigent-OS |
These can coexist. The detailed comparison follows.
aigent-OS is a 16-document kernel (plus extended specs) that turns Claude Code into a persistent operating system, one operator, one Claude, running on your own machine. No database, no server, no build step: drop the files in, run bash install.sh, and the next session already knows who it is and what it's working on. The framework also ships tools for maintaining itself: a nightly self-maintenance routine you can run against your own vault, and a hook that spots a new skill file and prompts you to enroll it. The publish half, deciding what a local install has learned that's worth graduating to this repo, sanitizing it, and opening the pull request, is designed and not built. (How this repo maintains itself · Manifesto)
Dependency model: the core kernel is markdown + shell: no database or server. The default installer requires Node.js 18+, installs and verifies the managed Auto-Refresh transport, and wires the
aigentfront door automatically.--no-depsis the explicit fallback when you deliberately want to skip Node dependencies. Obsidian is optional, for browsing the vault visually.
Unlike memory add-ons that keep state in an opaque database, every checkpoint here is a real git commit, readable with plain git log, not a query against someone else's schema. The table below scores the rest against real rivals, not strawmen.
Recent: managed Auto-Refresh now ships in the public core (first released in the v1.1.0-rc.1 pre-release), alongside the two-verb lifecycle, model-tier dispatch enforcement, and the Codex adapter. See
CHANGELOG.mdfor dates and detail.
Every framework claims to be different. Here's exactly where that's true for aigent-OS, and where it isn't, yet.
| aigent-OS | claude-mem | SuperClaude Framework | Claude-Claw | Native Auto-Memory/Dream | |
|---|---|---|---|---|---|
| Persistent cross-session memory | ✅ | ✅ | ⚠️¹ | ✅ | ✅ (first-party) |
| Git-native, auditable memory store | ✅ | ❌ (SQLite+Chroma, outside version control) | n/a | ⚠️ files trackable, not sync-verified | ❌ |
| Session continuity across context limits | ✅ (Managed Auto-Refresh, no compaction) | partial (Stop-hook based) | ❌ | ✅ (/handoff) | ✅ (native) |
| 3-tier memory architecture | ✅ | ❌ (flat) | ❌ | ✅ (same shape) | ❌ (2-tier) |
| Self-testing of its own operating rules | ❌ (Roadmap) | ❌ | partial (pre/post code-quality checks, not self-rules) | ❌ | ❌ |
| Model-tier routing across sub-agents, enforced | ✅ advisory default, opt-in enforce | ❌ | ✅ (behavioral config) | ❌ | n/a |
| Non-Claude execution (Codex, others) | ✅ (single task class) | ❌ | ❌ | ❌ | n/a |
¹ via bundled Serena MCP.
The honest framing: session continuity and cross-session memory are populated categories now; several projects do them well. Git-native auditability is where this repo is currently ahead. Routing and non-Claude execution are real, tested mechanisms, scoped in the table to exactly what ships and no more.
| Capability | Mechanism | Ships today? |
|---|---|---|
| Auto-Refresh (autonomous memory + context) | Managed local runner: pressure threshold → one capsule request → exact acknowledgement → one /clear → fresh SessionStart identity → one resume wake. Busy output uses Claude Code's native prompt queue instead of blocking the cycle. | ✅ shipped in v1.1.0-rc.1 (details, known limitation) |
| Git-native vault memory | Every closed capsule cycle is a real commit, pushed to your configured remote, auditable with plain git log, not an opaque DB | ✅ shipped |
| Somatic layer | Five lazy-computed pressure gauges (context, memory backlog, decision pressure, token usage, drift) read before acting, no daemon polling | ✅ shipped |
| Self-learning engine | Skill recall → skill hunt → solution hunt escalation chain; failures are meant to become durable artifacts (a written procedure, not enforced by code) | ⚠️ procedure shipped, not enforced |
| Cognitive architecture | Persistent self-model, goal stack, belief tracking with confidence scores, human-gated /dream consolidation, /reconcile, /meta-improve | ✅ shipped |
| Calibration measurement | HONESTY_LEDGER, TRUST_DECAY, and FAILURE_MODES are paired ledgers: a claim captured, then resolved as held, drifted, or reversed; drift detection runs at resume, and a Stop hook prompts the capture when a turn's confident claims went unrecorded | ✅ shipped |
| Caddy skill router | Non-blocking prompt-matching hook surfaces the right skill from your own catalog; auto-reindexes on drop-in | ✅ shipped |
| 3-tier memory (napkin → index → deep) | Heat-scored top-20 + staged digest sit above full topic files | ✅ shipped |
| Model-tier dispatch enforcement | A PreToolUse hook checks every named agent's Agent-tool dispatch against its declared model tier live; advisory by default, AIGENT_MODEL_GUARD=enforce opts into a hard block | ✅ shipped (docs/model-routing-enforcement.md) |
| Non-Claude execution (Codex adapter) | One bounded, mechanical task class routed to the Codex CLI's non-interactive codex exec, review-gated, never auto-merged | ✅ shipped (single task class; docs/codex-adapter.md) |
| Nightly close-parity maintenance | Seven framework legs produce eleven independently validated checkpoints, append-only failure alerts, and a session-start no-fire fallback that needs no external scheduler or transport. Human judgment stays staged for review. | ✅ shipped (docs/nightly-self-maintenance.md) |
| Self-testing of one's own operating rules | A portable subset of the probe idea, scoped to one seat's own behavior | ❌ not shipped (Roadmap) |
The first-run onboarding: three plain questions, then a first plan. (The resume/checkpoint side of the loop is the clip near the top of this README.) Both are the real dialogue from What a session actually looks like below, rendered as self-contained animated SVGs, no video, no external assets. Generator: assets/build-terminal-demo.mjs.
Clone or download this repo (https://github.com/wrg32786/aigent-os) into the current
directory, then run `bash install.sh` from inside it. The default installer requires
Node.js 18+, installs and verifies the managed Auto-Refresh runner, and wires the
`aigent` front door. When it finishes, open a new terminal and run `aigent`.
Your agent reads its own install script, runs it, and reports back what it found: no shell flags to remember yourself. Pasting this into an agent? Use the block above. Typing in your own terminal? Use the block below.
bash install.sh
That's it. aigent-OS installs into whatever directory you're in: your existing project, your home folder, wherever you work. The installer copies the kernel files, creates .claude/settings.json, installs and verifies managed Auto-Refresh, and wires the aigent command plus the platform launcher where supported.
Explicit fallback
--no-deps: skips Node dependencies, including semantic search and the managed PTY transport; the launcher then uses its loud unmanaged fallback when the transport is unavailable. Other flags:--target <dir>installs elsewhere,--dry-runpreviews every change, and--no-launcherskips PATH/shortcut wiring (a target under the system temp directory skips it the same way automatically). See Advanced Setup.
Open a new terminal and run aigent. The installer has already wired the managed runner. The first launch runs guided setup; later launches warm-resume, track context pressure, checkpoint, clear, rebind, and continue without an operator command. (In v1.1.0-rc.1 a long session can still stop at the clear step and need a manual /clear; see Evidence and limits.)
Prefer an app to a terminal? The same install creates the AIgent app/shortcut where supported. Open it instead of typing aigent. See launcher/README.md.
Optional: open the vault/ folder in Obsidian to see your AI's knowledge graph visually.
Full setup walkthrough: Getting Started · Advanced config: Advanced Setup
bash install.sh; use --no-deps only when you deliberately want the unmanaged fallback.bash: command not found: install.sh needs a real bash. Install Git for Windows (bundles Git Bash), then reopen your terminal and retry; PowerShell alone can't run it.bash scripts/doctor.sh diagnoses hooks, settings, semantic search, and runtime state in one pass. See Getting Started § Troubleshooting.system/ The 16-document operating kernel (00_identity → 15_somatic_layer)
vault/ Persistent memory and knowledge graph (markdown, Obsidian-native)
vault/agents/ Instrument roster: 9 named sub-agents
skills/ Claude Code slash-command skills (60+ source templates)
hooks/ Automation hook scripts (session summary, token tracking, compact nudge)
daemons/ Background helpers (Auto-Refresh transport, Caddy, semantic search, runtime state)
docs/ Setup guides, doctrine references, architecture roadmaps
memory/ Ledger templates (SKILL_LEDGER, SKILL_GAPS, SKILL_CHAINS, facts/)
memory/runtime/ Cognitive layer (ACTIVE_STATE, SELF_MODEL, GOAL_STACK, BELIEF_STATE)
evals/ Evaluation test definitions (skill-recall, contradiction, capsule-resume)
install.sh Installer (preview first: bash install.sh --dry-run)
Skills path note:
skills/contains source templates; the installer copies them to.claude/skills/, where Claude Code looks for slash commands at runtime. Manually added skills go in.claude/skills/<name>/SKILL.md.
Auto-Refresh now ships in this repository as a managed local transport. Its user-visible rule is deliberately small:
context pressure rises
→ request one /context-capsule
→ observe exactly one "Capsule Complete, Ready For Clear"
→ submit exactly one /clear
→ observe a fresh source=clear SessionStart identity
→ submit exactly one resume wake
→ load prior work, re-ground, and continue
No acknowledgement means no clear. One acknowledgement buys one clear. Busy or idle is not a readiness decision: command text and a protected, separately written Enter ride Claude Code's native queued-prompt path and execute when the current turn releases the composer.
daemons/ctx-telemetry.mjs records the current context percentage.daemons/auto-clear-transport.mjs owns the persisted one-cycle authorization and at-most-once clear intent.daemons/pty-runner.mjs is the sole PTY writer. It queues operator input while automatic command text owns the composer.skills/context-capsule/SKILL.md writes and verifies the resume-ready capsule, then emits the exact acknowledgement literal.daemons/boot-receipt.mjs and daemons/sessionstart-reinject.mjs provide the fresh SessionStart receipt.daemons/resume-verb.mjs loads the newest valid capsule as historical work state. The live SessionStart hook ID is the current identity; capsule text and the disk receipt never substitute for it.The transport writes slash-command text and Enter separately. It also clears stale composer text before /clear, protects the wake text/Enter pair, refuses duplicate clear intent, and stops loudly on physical write or identity failures. It does not add an automatic retry after an ambiguous submission.
bash install.sh installs the transport's single runtime dependency, node-pty, when Node.js 18+ is present. The launchers use the managed runner by default. If the dependency cannot load, Claude still starts, checkpointing and recovery remain available, and the launcher reports that automatic clear is unavailable rather than pretending the managed path is active.
A --no-deps install intentionally selects that unmanaged fallback.
The release candidate completed 11 of 11 observed refresh transport transactions on one Windows reference seat in one live run: three setup transactions and eight transactions after the test objective began. Every observed transaction produced one capsule request, one acknowledgement, one clear, and one fresh SessionStart identity, with zero stranded acknowledgements and zero duplicate clears.
The accelerated observation harness then failed outside the transport: the model appended several remaining test-witness lines inside one unchanged session and declared the synthetic test complete. That invalidated the harness's proposed 20-cycle bookkeeping claim; it did not produce a failed refresh transaction. The harness used an intentionally low pressure threshold to exercise the mechanism rapidly. Normal users do not run the witness-file protocol.
This is bounded single-seat release evidence, not a fleet-reliability or "20/20" claim. The executable transport files in this public release are the same files used for the successful observed transactions. The companion paper reports the same result as hypothesis H2: PAPER.md and the continuity and Auto-Refresh case study.
Known limitation (v1.1.0-rc.1): automatic refresh is not yet proven clean end to end on a managed install. A long session can hold at the clear step and need a human to clear by hand; the repairs are in review on PR #62. Before clearing by hand, check that the latest capsule and any work in flight are preserved.
See docs/two-verb-lifecycle.md for the lifecycle and identity contract.
[first Claude Code session after install]
AI: I'm your AIgent operator. Let's get you one real win in the next few minutes.
In a sentence or two, what's your business, or the work you want help running?
You: I run a bookkeeping practice for trades: electricians, plumbers, HVAC.
AI: Got it. What's the one outcome that would make this month a win?
You: Five new clients, without working weekends.
AI: And what do you spend the most time on that you wish just ran itself?
You: Chasing leads. I'm always the one following up.
AI: Here's what I know about you: you run a bookkeeping practice for trades, you
want five new clients this month without working weekends, and chasing leads
eats your time.
Three things I'd do first:
1. Draft a week of outreach to local trade businesses, so lead-chasing
runs without you.
2. Build a "new client" intake that collects everything you need before
the first call.
3. Turn last month's finished jobs into three referral asks.
Pick one and we'll do it right now.
That's /operator-setup: three plain questions, on first run only, and the answers are written to memory so every session after opens already oriented around your business, not a generic template. Nothing here is invented; it only reflects what you actually said.
[new Claude Code session, nothing typed]
AI: 3 open threads from yesterday.
- Outreach batch: 12 of 20 trade businesses contacted, 3 replies waiting on you
- New-client intake form drafted, needs your sign-off before it goes out
- Referral asks: 2 of 3 sent, the HVAC client still pending
Active priorities:
1. Five new clients this month (2 now in the pipeline)
2. Lead follow-up runs without you (outreach batch in progress)
3. Month-end close for existing clients (starts Thursday)
Last session you were drafting the intake form.
Want to finish that, or handle the 3 outreach replies first?
You: replies first. Quote them the standard monthly rate.
AI: Locked. Drafting replies to all 3 with the standard rate, and
logging the pricing call in DECISION_LOG. Reasoning captured:
one consistent rate beats per-job haggling for trades, and you
said no weekends. Want the intake form linked in the replies,
or is it not ready to send?
You: not yet.
AI: Got it. Replies go out without it. Anything else
before we move on?
[... 90 minutes of work ...]
[you close the terminal, nothing typed]
[capsule fires automatically: reconciles the session, writes to vault/daily/2026-04-25.md]
What got decided today:
- Standard monthly rate quoted to all new trade leads. Logged.
- Intake form holds until your sign-off.
Open threads carrying to next session:
- HVAC referral ask still pending
- Intake form sign-off
See you tomorrow.
That's the loop, except you never typed either verb. resume → work → capsule, both automatic, both still callable by hand when you want to force one. The vault remembers everything. Next session picks up exactly where you left off. See vault/examples/ for what populated content actually looks like.
aigent-OS is built for principals running complex parallel work, not for developers building agent pipelines.
If you've ever closed your laptop on Friday and opened it Monday wondering what the hell you were in the middle of, that's the problem this solves.
If you're building an agent framework for end-users to consume, you probably want LangChain or CrewAI instead. aigent-OS optimizes for one principal, many threads, persistent context, and ships a branded desktop launcher for exactly that: install once, and every session after starts from a double-clicked icon, not a cd and a remembered command.
system/09_subagent_manifest.md names which tier (Fast/Mid/Frontier) each agent should run at; daemons/model-tier-guard.mjs, a PreToolUse hook, checks every Agent-tool dispatch against that declared tier live. Default is advisory (prints a named correction, never blocks, matching this repo's own suggest-don't-block hook doctrine); AIGENT_MODEL_GUARD=enforce opts into a hard decision:block gate. Scope: Agent-tool dispatches in one session, not the separate-instance or scheduled deployment models in docs/creating-agents.md. Design: docs/model-routing-enforcement.md.daemons/codex-adapter.sh routes one bounded, mechanical task to the Codex CLI's non-interactive codex exec mode: the first working non-Claude executor. Generic config surface (AIGENT_CODEX_BIN, no hardcoded paths), never commits or pushes; every run writes a working-tree diff for review under the same gate as any sub-agent's output. Skill: skills/codex-adapter/SKILL.md. Design: docs/codex-adapter.md.
16 system documents (00_identity → 15_somatic_layer) are a complete operating manual: how the AI thinks, decides, delegates, remembers, and manages time. Not prompts; a kernel. Full index: system/.
Hooks are the nervous system: shell/Node scripts on Claude Code's session events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact, SessionEnd). Auto-capture, session summaries, token tracking, compact nudges, the model-tier guard above, and the zero-leak flush legs that keep the capsule at most one turn stale across crashes, clears, and compaction all live here.
Semantic search runs locally (all-MiniLM-L6-v2, no API calls, no data leaves your device): node daemons/semantic-search/search-vault.js "what did we decide about pricing" searches your vault by meaning, not keywords.
Vault as brain. Your AI's memory is an Obsidian vault, not a vector database, the same files you can open, read, search, and navigate yourself. Wikilinks ([[Project Alpha]]) build the knowledge graph your AI actually navigates. resume reads it, capsule writes to it, both fire on their own: see Auto-Refresh above for exactly what gets committed and when. See the two-verb lifecycle doc for the full write-ahead/flush contract.
Testing isolation: scripting
claudechild sessions inside your vault directory means their Stop autosaves write real capsules into your real vault. Point automated children at a scratch root viaAIGENT_ROOT.
Measurement layer. Most agent frameworks let the AI talk; almost none measure how often it's confidently wrong. HONESTY_LEDGER.md, TRUST_DECAY.md, and FAILURE_MODES.md are paired ledgers (a claim captured, then resolved later as held/drifted/reversed) plus drift detection at resume (decision aging, attention reconciliation vs. ACTIVE_PRIORITIES.md). The credible claim: the framework measures its own AI's calibration over time, not just its output. A Stop hook closes the loop by noticing when a turn made confident claims that no ledger recorded, so the ledgers fill from real work instead of waiting to be remembered: Closing the Measurement Loop. Full doctrine: vault/concepts/Cost of Confidence.md.
Caddy: the skill that finds the right skill. A non-blocking UserPromptSubmit hook matches your words against every skill in your catalog and surfaces the one that fits, without ever blocking the turn on a wrong guess. A PostToolUse hook detects a newly dropped skill and nudges /caddy-enroll to index it; the golf bag stays complete without manual upkeep.
Self-aware about what it doesn't do yet. system/12_authority_matrix.md bounds what the AI decides alone vs. brings to you; /dream proposes improvements but only the operator approves merges: see docs/meta-aigent-doctrine.md for the safety boundary.
aigent-OS is opinionated but built to be forked.
Start here (10 minutes):
system/00_identity.md: tell it who you aresystem/14_decision_framework.md: encode how YOU make decisionssystem/12_authority_matrix.md: set boundaries that match YOUR risk toleranceThen build over time: add your projects to vault/projects/, your people to vault/people/, drop concepts into vault/concepts/. The vault grows with every session; it compounds.
The most differentiating thing about aigent-OS isn't a feature; it's that the framework operates on itself. What ships today is the maintenance half: a nightly self-maintenance routine you can run against your own vault, and a hook that spots a new skill file and prompts you to enroll it. aigent-OS installs no scheduler, so the nightly routine runs when you or your own cron entry runs it. Releases are recorded by hand in CHANGELOG.md.
The publish half is designed but not built. The intended shape is a skill that classifies each vault file (private: true | false | review frontmatter, defaulting new files to review), tests it against a genericity bar (useful to at least three radically different principals, or it stays private), secret-scans it, drafts the commit, and opens the PR. None of that exists yet: no file carries the flag, no code reads it, and deciding what graduates from a local install into this repo is a manual judgement call today. No plan in this repo schedules the skill itself; the nearest related item is a proposed public-content lint that would keep files marked private: true out of release artifacts (docs/review-hardening-plan.md). Full manifesto, including why the recursive layer is the category claim: docs/manifesto.md.
Not a chatbot skin. No personality prompts, no "you are a helpful assistant": operational infrastructure.
Not a code framework. No database, no server, no build step. The kernel is markdown; the installer needs Node.js 18+ for the refresh runner and local search.
Not a RAG system. The vault is human-readable by design: open Obsidian, don't query an embedding store.
Not another agent framework. LangChain and CrewAI are for developers building pipelines. aigent-OS is for principals who want an AI that actually operates, one operator, one Claude, at a time.
Explicitly non-normative: nothing below is claimed as shipped, and none of it appears in the tables above until it is.
vault-sync.mjs path-scoping polish: tightening the memoryPaths exists-filter at the edges of what counts as "durable memory" for a sync commit.One structural note, since it comes up: the core is scoped to a single operator running a single Claude session at a time. Two opt-in mods in plugins/, fleet-band and fleet-delivery, are the first pieces that let several seats work side by side, and we run aigent-OS that way. They are a pilot on master, not yet in a release, and the shared message room and job scheduler they connect to are not part of this repo.
PRs welcome. See CONTRIBUTING.md for what lands well and how to write rules that fit the existing style. Highest-value areas: decision framework lenses for new domains, hook scripts for additional Claude Code events, vault templates, integration guides, sanitized examples for vault/examples/.
See CHANGELOG.md for release notes.
aigent-OS is the free, open-source harness of The AIgent, a media project for people building with AI. The rest of what's free to take lives at the public tools.
Built by The AIgent
In daily use since April 2026. Today four seats run The AIgent newsletter; see In production for what that does and does not show. This framework emerged from real operational needs, not theory.
If this saves you time, star the repo. That's all the thanks needed.
Claude Code harness that refreshes its own context instead of compacting: at a threshold it writes a verified capsule, runs /clear, and resumes in a fresh session. Memory is plain markdown in git, readable with git log. MIT, runs locally, one install (Node 18+). Codex adapter included.
See the codeClaude Code that refreshes its own context instead of compacting.
Open-source (MIT) harness for one long-running Claude Code session. With Managed Auto-Refresh, when context reaches a threshold it saves a verified capsule, runs /clear, and resumes the work in a fresh session. No summary of a summary, no re-briefing. Around that loop sits an operator layer: skill routing, guarded memory and specialist sub-agents that help with the work itself.
Install · Demo · Evidence and limits · Operator · What it changes · Uninstall · FAQ · Alternatives · Docs
Stop re-briefing your AI every morning.
From the team behind The AIgent, a free media project for people building with AI.
Claude Code has a fixed context window. When it fills, the usual options are to let it auto-compact (the model summarizes the conversation and keeps going on the summary) or to /clear and re-explain everything yourself. aigent-OS takes a third path. Before the window fills (default 80%, configurable with AIGENT_PRESSURE_THRESHOLD_PCT), it asks Claude to write a resume-ready checkpoint file (a "capsule"). It waits for Claude to confirm the capsule is complete, sends exactly one /clear, checks that a fresh session started, and tells that new session to load the capsule and carry on. No confirmation, no clear. Your notes, decisions and open threads live in plain markdown files you keep in git (aigent-OS commits and pushes them at each capsule cycle when the install folder has a git remote), so you can read, diff and roll back exactly what your agent remembers. It runs on your machine; aigent-OS has no server of its own.
Requires Claude Code, Node.js 18+ with npm, and bash (on Windows, Git Bash from Git for Windows).
git clone https://github.com/wrg32786/aigent-os.git && cd aigent-os && bash install.sh --dry-run
The dry run prints the planned changes and writes nothing. When the plan looks right, run bash install.sh in the same folder, open a new terminal, and run aigent. The first launch runs guided setup.
To install into an existing project instead of the cloned folder, run bash install.sh --target <dir> from the clone (preview it with --dry-run first). Before you start working, read What this changes on your machine, including the note on vault sync and git remotes. More options: Quick Start.
/clear, and one fresh session, with zero stranded acknowledgements and zero duplicate clears. Write-up: the companion paper, governed-agent-organizations, hypothesis H2, and its continuity and Auto-Refresh case study. More detail: Release evidence./clear. Fixes for the three reproduced defects are in review, integrated on PR #62. Until that lands, check that the latest capsule and any work in flight are saved before you clear by hand. See the v1.1.0-rc.1 release notes.Auto-Refresh is what keeps a long-lived agent going. The rest of aigent-OS is about what that agent does with the time. It keeps working across days: each refresh resumes from a checked capsule, and it will not resume into one that recorded no next step. It remembers what matters: memory is markdown in git, a fact whose validity window has ended ranks below the current one, and guards keep always-loaded memory small and hold planted instructions for review. Live failures turn into guardrails: when the seats we run hit a problem, the fix comes back to this repo with a test. And on every prompt, it is pointed at the skill in your catalog that fits what you asked.
| Capability | What it does | Status |
|---|---|---|
| Live failure to fix loop | Problems found on the maintainers' live seats come back to this repo as fixes and regression tests, gathered in a weekly fleet-to-product port sweep (for example PR #69). A Stop hook also flags turns whose confident claims ("fixed", "verified") went unrecorded. | On by default (the fixes and the hook ship in the core; the sweep is how we maintain the repo) |
| Failure-to-fix procedure | A written procedure asks the agent to turn a failure seen twice into a skill, a check or a routing rule. No code forces it, and the ledgers ship empty. | Experimental (a skill the agent follows) |
| Memory guardrails | A size budget on always-loaded memory files, staged memory that tries to give instructions is held for review, anything read back from memory is treated as data and never as an instruction, and folders you mark confidential stay out of search | On by default |
| Skill caddy | A hook matches each prompt against your skill catalog and suggests the skill that fits. It never blocks the turn, and when nothing fits it points at /skill-recall so the gap gets logged. | On by default |
| Nine named specialist agents | A builder, a read-only scout, a researcher, a design spec writer, a memory architect, a critic, a vault custodian, an architecture reviewer and a prompt writer, each with a fixed model tier and tool set (roster). A hook checks every dispatch against the agent's declared tier (details). | On by default (warns); block is opt-in with AIGENT_MODEL_GUARD=enforce |
| C2 temporal supersession | A note can carry a validity window. Once it ends, search ranks the note below current ones instead of deleting it (details). | On by default for notes with a validity line; in v1.1.0-rc.1 |
| Hindsight and Jev memory bridge | Explicit retain, recall, reflect and ranking against providers you configure, with every result checked against a local source (details) | Opt-in; on master, not in a release, not verified against the live services |
| Gateguard | The first edit of each file in a session waits until the agent names what depends on it, what the change affects and the instruction it is following | Opt-in with AIGENT_GATEGUARD=enforce |
| Codex adapter | Routes one bounded, mechanical task type to codex exec and writes a diff for review; never commits or pushes (details) | Opt-in when you invoke it; one task type |
| fleet-band and fleet-delivery mods | A status line above the prompt, and delivery of messages and scheduled job results into an idle session, once each (mods) | Opt-in pilot (fleet-delivery runs on one seat); on master, not in a release. Delivery needs a message room and a job-results source that are not in this public repo yet |
| Agent teams ("crews") | Guidance on when to run a standing team, a one-shot fan-out or a solo agent | Guidance only; no code |
| Self-testing of its own operating rules | Testing a seat's behavior against its own rules | Roadmap |
Four aigent-OS seats, Titus, Pheme, Davinci and Metis, run The AIgent, a newsletter for people building with AI with close to 9,000 subscribers. When those seats fail in live use, the failure comes back to this repo as a fix and a test. One example: daemons/tests/capsule-sentinel-selection.test.mjs records a check of the four live seat vaults on Aug 1, 2026, which found that three of the four would have resumed into a checkpoint with no actionable content. The capsule selector now refuses that kind of checkpoint, and the test defends it. This is operating experience, not a measured outcome. We do not claim that aigent-OS grew the newsletter, reduced operator effort or improved business results; the companion paper lists those as not established in its limitations and non-claims.
The animation is a scripted illustration of the lifecycle, not a screen recording. In the shipped default, Managed Auto-Refresh is designed to run the whole boundary without operator input: at the configured context threshold (default 80%) it requests a capsule, waits for the exact completion acknowledgement, submits one /clear, binds the fresh session, and submits one resume wake. The shipped settings also set "idleCompaction": false, so Claude Code's own idle compaction (which can summarize a quiet session after about 55 minutes once it holds 200k tokens) cannot replace that boundary. In v1.1.0-rc.1 a long session can still stop at the clear step and need a manual /clear; see Evidence and limits.
Run bash install.sh --dry-run first; it lists the planned changes and writes nothing. Below, <target> is the folder you install into: the cloned aigent-os folder by default, or the directory you pass with --target. The installer does not edit your user-level ~/.claude/settings.json or ~/.claude/CLAUDE.md.
| Where | What the installer does | How to undo |
|---|---|---|
<target>/.claude/settings.json | Creates it, or merges into your existing file and saves a backup in <target>/.aigent/backups/. Adds hooks on seven Claude Code events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd), a statusLine command, and the AIGENT_ROOT and AIGENT_VAULT env values. If your existing file is not valid JSON, it is left untouched and the new settings are written to .claude/settings.aigent.json for you to merge. | Restore the backup, or delete the file if the installer created it |
<target>/.claude/skills/, .claude/agents/, .claude/skill-index.json, .claude/rules/post-compact-critical.md, .claude/settings.json.template | Copies the skill folders from skills/, the agent definitions from vault/agents/, the skill index, a starter rules file (only if you have none), and the settings template | Delete what was added |
<target>/CLAUDE.md | --target installs only: creates the file, or appends one block between <!-- aigent-os:start --> and <!-- aigent-os:end --> and saves a backup. Your text outside the markers is kept. In the cloned folder, CLAUDE.md is the repo's own file and is not edited. | Delete the block between the markers |
<target>/system/, vault/, memory/, hooks/, skills/, daemons/, scripts/, docs/, evals/, launcher/ | --target installs only: copies framework files that are missing and never overwrites yours silently. vault/ and memory/ hold your memory as plain markdown. | Delete the folders aigent-OS created. If your project already had a folder with one of these names (docs/ and scripts/ are common), remove only the added files; git status lists them |
| Files that differ from the framework copy | Under system/, skills/, hooks/, daemons/, scripts/, launcher/, .claude/skills/ and .claude/agents/, an existing file that differs from the framework version is moved to <target>/.aigent/quarantine/ and replaced, because Claude Code would trust it. --trust-existing keeps them instead. | Copy the file back from .aigent/quarantine/ |
<target>/.aigent/ | First-run state (state.json), backups and quarantined files | Delete, after restoring anything you need from it |
<target>/.gitignore | Adds a block between # aigent-os:generated-state:start and # aigent-os:generated-state:end covering local state such as .aigent/, node_modules/, .obsidian/ and the prompt journal. Saves a backup if the file existed. | Delete the block |
<target>/daemons/semantic-search/node_modules/ and <target>/daemons/transport-deps/node_modules/ | Runs npm ci --ignore-scripts for local semantic search (@xenova/transformers) and the refresh runner (node-pty, rebuilt for your platform). --no-deps skips this and falls back to an unmanaged launch without automatic clear. | Delete the two node_modules/ folders |
~/.local/bin/aigent (macOS, Linux) | Symlink to <target>/launcher/aigent.sh. --no-launcher skips all launcher wiring, and a target under the system temp directory skips it automatically. | rm ~/.local/bin/aigent |
~/.bashrc (macOS, Linux) | Appends export AIGENT_HOME=<target> and export PATH="$HOME/.local/bin:$PATH" if they are not already there. The launcher installer runs under bash, so it writes ~/.bashrc even when your login shell is zsh. | Delete those lines (keep the PATH line if other tools rely on ~/.local/bin) |
~/Applications/AIgent.app (macOS) | An app bundle that opens Terminal and runs aigent | Delete the app |
Git config of <target> (macOS, Linux) | Sets core.fileMode false if <target> is a git repo, so the launcher's executable bit never blocks a git pull | git -C <target> config --unset core.fileMode |
| Windows user environment | Sets the AIGENT_HOME user variable, writes %USERPROFILE%\.aigent\bin\aigent.cmd, adds that folder to your user Path, and creates AIgent shortcuts on the Desktop and in the Start Menu | See Uninstall |
~/.claude/ctx-refresh/ (while running) | The status line writes one small JSON file per session with the current context percentage, which the refresh runner reads | Delete the folder |
Network and data. aigent-OS has no server of its own. What does use the network:
npm downloads packages during install.all-MiniLM-L6-v2 model files from Hugging Face the first time it runs. Embedding and search then run on your machine.<target> is a git repo with a remote, aigent-OS commits the memory folder and pushes it to that remote. No repo or no remote means no push. If you installed in the cloned folder, its origin is this public GitHub repo, so point origin at your own private repo (git remote set-url origin <your-private-repo>) or remove it (git remote remove origin) before you start working..aigent/memory-bridge.json, and then calls only the providers you set.There is no uninstall script. Removal is manual and mirrors what the installer did. Save anything you want to keep from vault/ and memory/ first: that is your agent's memory.
aigent command and shortcuts.
rm ~/.local/bin/aigent, then delete the export AIGENT_HOME=... line (and the ~/.local/bin PATH line, if nothing else needs it) from ~/.bashrc. On macOS, also delete ~/Applications/AIgent.app.%USERPROFILE%\.aigent\bin, remove that folder from your user Path (System Properties, Environment Variables), run [Environment]::SetEnvironmentVariable('AIGENT_HOME', $null, 'User'), and delete the AIgent shortcut from your Desktop and from %APPDATA%\Microsoft\Windows\Start Menu\Programs.--target:
.claude/settings.json, CLAUDE.md and .gitignore from the timestamped backups in .aigent/backups/, or edit them by hand: delete the aigent-OS block between the markers in CLAUDE.md and .gitignore, and remove the aigent-OS hooks, statusLine and env entries from .claude/settings.json (or delete the file if the installer created it)..claude/settings.json.template, .claude/skill-index.json, .claude/rules/post-compact-critical.md, and the skills and agents aigent-OS added under .claude/skills/ and .claude/agents/.system/, hooks/, daemons/, scripts/, docs/, evals/, launcher/, memory/, vault/). Where your project already had a folder of the same name, remove only the files aigent-OS added..aigent/quarantine/, then delete .aigent/.<target> is a git repo: git -C <target> config --unset core.fileMode.~/.claude/ctx-refresh/.aigent-OS refreshes the session before the window fills, so compaction is not the path it relies on. At a threshold (default 80%) it saves a verified capsule, runs /clear, and resumes in a fresh session from that capsule. If a compaction happens anyway, a PreCompact hook first flushes the latest state into the capsule and hands the compactor pointers into the vault.
Without add-ons, Claude Code compacts the conversation into a summary and continues, or you run /clear and start over. Compaction keeps going on a summary; /clear loses everything you did not save. aigent-OS automates a third option: save a structured checkpoint, clear, and reload the checkpoint in the new session.
Use /compact when a summary is good enough and you want to keep going; use /clear when you want a clean window. aigent-OS is for people who want the clean window of /clear without re-briefing, and it runs the save, clear and resume sequence for you. One caveat for now: in v1.1.0-rc.1 a long session can still stop at the clear step (see Evidence and limits).
aigent-OS adds a git-tracked markdown vault that every session reads at start and writes at checkpoints. Claude Code's own CLAUDE.md files and auto memory already carry instructions and learned notes across sessions. The vault adds daily notes, decisions, open threads and capsules on top of that, plus local semantic search over it, all in files you can open, diff and roll back.
That is the use case aigent-OS is built for: one long-running session that keeps cycling through refreshes. The public evidence so far is 11 of 11 cycles on one machine, which is not a reliability guarantee, and the known limitation above still applies.
It is the aigent-OS loop that replaces compaction. At the context threshold it requests a capsule, waits for the exact acknowledgement "Capsule Complete, Ready For Clear", submits exactly one /clear, checks for a fresh session identity, and submits one resume prompt. No acknowledgement means no clear. Details: Auto-Refresh.
We do not claim that. It is a different trade-off: an explicit, inspectable checkpoint and a clean window, instead of a model-written summary. Try both on your own work.
aigent-OS manages the context boundary itself (checkpoint, clear, resume) and keeps memory as markdown in git. claude-mem captures what your agent does, compresses it with AI and injects relevant context into later sessions, with its store outside version control. context-mode reduces how much context tool output uses and persists session memory. They solve overlapping problems in different ways; see Alternatives.
Yes, through Git Bash. install.sh needs a real bash, so install Git for Windows first; PowerShell alone cannot run it. The installer then wires an aigent command and Desktop and Start Menu shortcuts. The public 11 of 11 evidence comes from a Windows seat, and CI runs the installer on Windows, macOS and Linux. macOS has the least live mileage with the managed runner.
aigent-OS is free and MIT-licensed. You pay for Claude Code the way you already do. Each refresh cycle uses some tokens, because Claude writes a capsule before the clear and reads it back after. The optional memory bridge and Codex adapter can incur charges from the providers you configure.
Claude Code is the host. A Codex adapter routes one bounded task class to codex exec, review-gated and never auto-merged. Other CLIs are on the roadmap, not shipped.
aigent-OS has no server; your vault is local files and semantic search runs on your machine. Claude Code still sends your conversation to Anthropic, and vault sync pushes memory commits to your git remote if the install folder has one. See Network and data.
See What this changes on your machine and Uninstall. bash install.sh --dry-run shows the planned changes before anything is written.
Not yet: Managed Auto-Refresh is in a v1.1 release candidate. See Evidence and limits for what is and is not shown.
Yes: four aigent-OS seats run The AIgent newsletter, which is operating experience rather than a measured result; see In production.
Some of it is mechanical and on by default (memory guards, skill routing, the model-tier check, fixes from live failures shipped with tests), while turning a repeated failure into a new skill or check is a written procedure the agent follows, and we make no measured improvement claim; see Operator.
A neutral guide to what fits which need (descriptions checked Oct 2026):
| If you want | Consider |
|---|---|
| Built-in, zero setup | Claude Code's own auto-compaction, /compact, /clear, CLAUDE.md and auto memory |
| Automatic capture of what your agent did, compressed and injected into later sessions | thedotmack/claude-mem |
| Less context used by tool output | mksglu/context-mode |
| A memory service that learns across agents | vectorize-io/hindsight (aigent-OS has an opt-in bridge) |
| Persistent teams of Claude Code, Codex and Pi agents | mvschwarz/openrig |
| One long-running Claude Code session that checkpoints, clears and resumes instead of compacting, with git-auditable memory | aigent-OS |
These can coexist. The detailed comparison follows.
aigent-OS is a 16-document kernel (plus extended specs) that turns Claude Code into a persistent operating system, one operator, one Claude, running on your own machine. No database, no server, no build step: drop the files in, run bash install.sh, and the next session already knows who it is and what it's working on. The framework also ships tools for maintaining itself: a nightly self-maintenance routine you can run against your own vault, and a hook that spots a new skill file and prompts you to enroll it. The publish half, deciding what a local install has learned that's worth graduating to this repo, sanitizing it, and opening the pull request, is designed and not built. (How this repo maintains itself · Manifesto)
Dependency model: the core kernel is markdown + shell: no database or server. The default installer requires Node.js 18+, installs and verifies the managed Auto-Refresh transport, and wires the
aigentfront door automatically.--no-depsis the explicit fallback when you deliberately want to skip Node dependencies. Obsidian is optional, for browsing the vault visually.
Unlike memory add-ons that keep state in an opaque database, every checkpoint here is a real git commit, readable with plain git log, not a query against someone else's schema. The table below scores the rest against real rivals, not strawmen.
Recent: managed Auto-Refresh now ships in the public core (first released in the v1.1.0-rc.1 pre-release), alongside the two-verb lifecycle, model-tier dispatch enforcement, and the Codex adapter. See
CHANGELOG.mdfor dates and detail.
Every framework claims to be different. Here's exactly where that's true for aigent-OS, and where it isn't, yet.
| aigent-OS | claude-mem | SuperClaude Framework | Claude-Claw | Native Auto-Memory/Dream | |
|---|---|---|---|---|---|
| Persistent cross-session memory | ✅ | ✅ | ⚠️¹ | ✅ | ✅ (first-party) |
| Git-native, auditable memory store | ✅ | ❌ (SQLite+Chroma, outside version control) | n/a | ⚠️ files trackable, not sync-verified | ❌ |
| Session continuity across context limits | ✅ (Managed Auto-Refresh, no compaction) | partial (Stop-hook based) | ❌ | ✅ (/handoff) | ✅ (native) |
| 3-tier memory architecture | ✅ | ❌ (flat) | ❌ | ✅ (same shape) | ❌ (2-tier) |
| Self-testing of its own operating rules | ❌ (Roadmap) | ❌ | partial (pre/post code-quality checks, not self-rules) | ❌ | ❌ |
| Model-tier routing across sub-agents, enforced | ✅ advisory default, opt-in enforce | ❌ | ✅ (behavioral config) | ❌ | n/a |
| Non-Claude execution (Codex, others) | ✅ (single task class) | ❌ | ❌ | ❌ | n/a |
¹ via bundled Serena MCP.
The honest framing: session continuity and cross-session memory are populated categories now; several projects do them well. Git-native auditability is where this repo is currently ahead. Routing and non-Claude execution are real, tested mechanisms, scoped in the table to exactly what ships and no more.
| Capability | Mechanism | Ships today? |
|---|---|---|
| Auto-Refresh (autonomous memory + context) | Managed local runner: pressure threshold → one capsule request → exact acknowledgement → one /clear → fresh SessionStart identity → one resume wake. Busy output uses Claude Code's native prompt queue instead of blocking the cycle. | ✅ shipped in v1.1.0-rc.1 (details, known limitation) |
| Git-native vault memory | Every closed capsule cycle is a real commit, pushed to your configured remote, auditable with plain git log, not an opaque DB | ✅ shipped |
| Somatic layer | Five lazy-computed pressure gauges (context, memory backlog, decision pressure, token usage, drift) read before acting, no daemon polling | ✅ shipped |
| Self-learning engine | Skill recall → skill hunt → solution hunt escalation chain; failures are meant to become durable artifacts (a written procedure, not enforced by code) | ⚠️ procedure shipped, not enforced |
| Cognitive architecture | Persistent self-model, goal stack, belief tracking with confidence scores, human-gated /dream consolidation, /reconcile, /meta-improve | ✅ shipped |
| Calibration measurement | HONESTY_LEDGER, TRUST_DECAY, and FAILURE_MODES are paired ledgers: a claim captured, then resolved as held, drifted, or reversed; drift detection runs at resume, and a Stop hook prompts the capture when a turn's confident claims went unrecorded | ✅ shipped |
| Caddy skill router | Non-blocking prompt-matching hook surfaces the right skill from your own catalog; auto-reindexes on drop-in | ✅ shipped |
| 3-tier memory (napkin → index → deep) | Heat-scored top-20 + staged digest sit above full topic files | ✅ shipped |
| Model-tier dispatch enforcement | A PreToolUse hook checks every named agent's Agent-tool dispatch against its declared model tier live; advisory by default, AIGENT_MODEL_GUARD=enforce opts into a hard block | ✅ shipped (docs/model-routing-enforcement.md) |
| Non-Claude execution (Codex adapter) | One bounded, mechanical task class routed to the Codex CLI's non-interactive codex exec, review-gated, never auto-merged | ✅ shipped (single task class; docs/codex-adapter.md) |
| Nightly close-parity maintenance | Seven framework legs produce eleven independently validated checkpoints, append-only failure alerts, and a session-start no-fire fallback that needs no external scheduler or transport. Human judgment stays staged for review. | ✅ shipped (docs/nightly-self-maintenance.md) |
| Self-testing of one's own operating rules | A portable subset of the probe idea, scoped to one seat's own behavior | ❌ not shipped (Roadmap) |
The first-run onboarding: three plain questions, then a first plan. (The resume/checkpoint side of the loop is the clip near the top of this README.) Both are the real dialogue from What a session actually looks like below, rendered as self-contained animated SVGs, no video, no external assets. Generator: assets/build-terminal-demo.mjs.
Clone or download this repo (https://github.com/wrg32786/aigent-os) into the current
directory, then run `bash install.sh` from inside it. The default installer requires
Node.js 18+, installs and verifies the managed Auto-Refresh runner, and wires the
`aigent` front door. When it finishes, open a new terminal and run `aigent`.
Your agent reads its own install script, runs it, and reports back what it found: no shell flags to remember yourself. Pasting this into an agent? Use the block above. Typing in your own terminal? Use the block below.
bash install.sh
That's it. aigent-OS installs into whatever directory you're in: your existing project, your home folder, wherever you work. The installer copies the kernel files, creates .claude/settings.json, installs and verifies managed Auto-Refresh, and wires the aigent command plus the platform launcher where supported.
Explicit fallback
--no-deps: skips Node dependencies, including semantic search and the managed PTY transport; the launcher then uses its loud unmanaged fallback when the transport is unavailable. Other flags:--target <dir>installs elsewhere,--dry-runpreviews every change, and--no-launcherskips PATH/shortcut wiring (a target under the system temp directory skips it the same way automatically). See Advanced Setup.
Open a new terminal and run aigent. The installer has already wired the managed runner. The first launch runs guided setup; later launches warm-resume, track context pressure, checkpoint, clear, rebind, and continue without an operator command. (In v1.1.0-rc.1 a long session can still stop at the clear step and need a manual /clear; see Evidence and limits.)
Prefer an app to a terminal? The same install creates the AIgent app/shortcut where supported. Open it instead of typing aigent. See launcher/README.md.
Optional: open the vault/ folder in Obsidian to see your AI's knowledge graph visually.
Full setup walkthrough: Getting Started · Advanced config: Advanced Setup
bash install.sh; use --no-deps only when you deliberately want the unmanaged fallback.bash: command not found: install.sh needs a real bash. Install Git for Windows (bundles Git Bash), then reopen your terminal and retry; PowerShell alone can't run it.bash scripts/doctor.sh diagnoses hooks, settings, semantic search, and runtime state in one pass. See Getting Started § Troubleshooting.system/ The 16-document operating kernel (00_identity → 15_somatic_layer)
vault/ Persistent memory and knowledge graph (markdown, Obsidian-native)
vault/agents/ Instrument roster: 9 named sub-agents
skills/ Claude Code slash-command skills (60+ source templates)
hooks/ Automation hook scripts (session summary, token tracking, compact nudge)
daemons/ Background helpers (Auto-Refresh transport, Caddy, semantic search, runtime state)
docs/ Setup guides, doctrine references, architecture roadmaps
memory/ Ledger templates (SKILL_LEDGER, SKILL_GAPS, SKILL_CHAINS, facts/)
memory/runtime/ Cognitive layer (ACTIVE_STATE, SELF_MODEL, GOAL_STACK, BELIEF_STATE)
evals/ Evaluation test definitions (skill-recall, contradiction, capsule-resume)
install.sh Installer (preview first: bash install.sh --dry-run)
Skills path note:
skills/contains source templates; the installer copies them to.claude/skills/, where Claude Code looks for slash commands at runtime. Manually added skills go in.claude/skills/<name>/SKILL.md.
Auto-Refresh now ships in this repository as a managed local transport. Its user-visible rule is deliberately small:
context pressure rises
→ request one /context-capsule
→ observe exactly one "Capsule Complete, Ready For Clear"
→ submit exactly one /clear
→ observe a fresh source=clear SessionStart identity
→ submit exactly one resume wake
→ load prior work, re-ground, and continue
No acknowledgement means no clear. One acknowledgement buys one clear. Busy or idle is not a readiness decision: command text and a protected, separately written Enter ride Claude Code's native queued-prompt path and execute when the current turn releases the composer.
daemons/ctx-telemetry.mjs records the current context percentage.daemons/auto-clear-transport.mjs owns the persisted one-cycle authorization and at-most-once clear intent.daemons/pty-runner.mjs is the sole PTY writer. It queues operator input while automatic command text owns the composer.skills/context-capsule/SKILL.md writes and verifies the resume-ready capsule, then emits the exact acknowledgement literal.daemons/boot-receipt.mjs and daemons/sessionstart-reinject.mjs provide the fresh SessionStart receipt.daemons/resume-verb.mjs loads the newest valid capsule as historical work state. The live SessionStart hook ID is the current identity; capsule text and the disk receipt never substitute for it.The transport writes slash-command text and Enter separately. It also clears stale composer text before /clear, protects the wake text/Enter pair, refuses duplicate clear intent, and stops loudly on physical write or identity failures. It does not add an automatic retry after an ambiguous submission.
bash install.sh installs the transport's single runtime dependency, node-pty, when Node.js 18+ is present. The launchers use the managed runner by default. If the dependency cannot load, Claude still starts, checkpointing and recovery remain available, and the launcher reports that automatic clear is unavailable rather than pretending the managed path is active.
A --no-deps install intentionally selects that unmanaged fallback.
The release candidate completed 11 of 11 observed refresh transport transactions on one Windows reference seat in one live run: three setup transactions and eight transactions after the test objective began. Every observed transaction produced one capsule request, one acknowledgement, one clear, and one fresh SessionStart identity, with zero stranded acknowledgements and zero duplicate clears.
The accelerated observation harness then failed outside the transport: the model appended several remaining test-witness lines inside one unchanged session and declared the synthetic test complete. That invalidated the harness's proposed 20-cycle bookkeeping claim; it did not produce a failed refresh transaction. The harness used an intentionally low pressure threshold to exercise the mechanism rapidly. Normal users do not run the witness-file protocol.
This is bounded single-seat release evidence, not a fleet-reliability or "20/20" claim. The executable transport files in this public release are the same files used for the successful observed transactions. The companion paper reports the same result as hypothesis H2: PAPER.md and the continuity and Auto-Refresh case study.
Known limitation (v1.1.0-rc.1): automatic refresh is not yet proven clean end to end on a managed install. A long session can hold at the clear step and need a human to clear by hand; the repairs are in review on PR #62. Before clearing by hand, check that the latest capsule and any work in flight are preserved.
See docs/two-verb-lifecycle.md for the lifecycle and identity contract.
[first Claude Code session after install]
AI: I'm your AIgent operator. Let's get you one real win in the next few minutes.
In a sentence or two, what's your business, or the work you want help running?
You: I run a bookkeeping practice for trades: electricians, plumbers, HVAC.
AI: Got it. What's the one outcome that would make this month a win?
You: Five new clients, without working weekends.
AI: And what do you spend the most time on that you wish just ran itself?
You: Chasing leads. I'm always the one following up.
AI: Here's what I know about you: you run a bookkeeping practice for trades, you
want five new clients this month without working weekends, and chasing leads
eats your time.
Three things I'd do first:
1. Draft a week of outreach to local trade businesses, so lead-chasing
runs without you.
2. Build a "new client" intake that collects everything you need before
the first call.
3. Turn last month's finished jobs into three referral asks.
Pick one and we'll do it right now.
That's /operator-setup: three plain questions, on first run only, and the answers are written to memory so every session after opens already oriented around your business, not a generic template. Nothing here is invented; it only reflects what you actually said.
[new Claude Code session, nothing typed]
AI: 3 open threads from yesterday.
- Outreach batch: 12 of 20 trade businesses contacted, 3 replies waiting on you
- New-client intake form drafted, needs your sign-off before it goes out
- Referral asks: 2 of 3 sent, the HVAC client still pending
Active priorities:
1. Five new clients this month (2 now in the pipeline)
2. Lead follow-up runs without you (outreach batch in progress)
3. Month-end close for existing clients (starts Thursday)
Last session you were drafting the intake form.
Want to finish that, or handle the 3 outreach replies first?
You: replies first. Quote them the standard monthly rate.
AI: Locked. Drafting replies to all 3 with the standard rate, and
logging the pricing call in DECISION_LOG. Reasoning captured:
one consistent rate beats per-job haggling for trades, and you
said no weekends. Want the intake form linked in the replies,
or is it not ready to send?
You: not yet.
AI: Got it. Replies go out without it. Anything else
before we move on?
[... 90 minutes of work ...]
[you close the terminal, nothing typed]
[capsule fires automatically: reconciles the session, writes to vault/daily/2026-04-25.md]
What got decided today:
- Standard monthly rate quoted to all new trade leads. Logged.
- Intake form holds until your sign-off.
Open threads carrying to next session:
- HVAC referral ask still pending
- Intake form sign-off
See you tomorrow.
That's the loop, except you never typed either verb. resume → work → capsule, both automatic, both still callable by hand when you want to force one. The vault remembers everything. Next session picks up exactly where you left off. See vault/examples/ for what populated content actually looks like.
aigent-OS is built for principals running complex parallel work, not for developers building agent pipelines.
If you've ever closed your laptop on Friday and opened it Monday wondering what the hell you were in the middle of, that's the problem this solves.
If you're building an agent framework for end-users to consume, you probably want LangChain or CrewAI instead. aigent-OS optimizes for one principal, many threads, persistent context, and ships a branded desktop launcher for exactly that: install once, and every session after starts from a double-clicked icon, not a cd and a remembered command.
system/09_subagent_manifest.md names which tier (Fast/Mid/Frontier) each agent should run at; daemons/model-tier-guard.mjs, a PreToolUse hook, checks every Agent-tool dispatch against that declared tier live. Default is advisory (prints a named correction, never blocks, matching this repo's own suggest-don't-block hook doctrine); AIGENT_MODEL_GUARD=enforce opts into a hard decision:block gate. Scope: Agent-tool dispatches in one session, not the separate-instance or scheduled deployment models in docs/creating-agents.md. Design: docs/model-routing-enforcement.md.daemons/codex-adapter.sh routes one bounded, mechanical task to the Codex CLI's non-interactive codex exec mode: the first working non-Claude executor. Generic config surface (AIGENT_CODEX_BIN, no hardcoded paths), never commits or pushes; every run writes a working-tree diff for review under the same gate as any sub-agent's output. Skill: skills/codex-adapter/SKILL.md. Design: docs/codex-adapter.md.
16 system documents (00_identity → 15_somatic_layer) are a complete operating manual: how the AI thinks, decides, delegates, remembers, and manages time. Not prompts; a kernel. Full index: system/.
Hooks are the nervous system: shell/Node scripts on Claude Code's session events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact, SessionEnd). Auto-capture, session summaries, token tracking, compact nudges, the model-tier guard above, and the zero-leak flush legs that keep the capsule at most one turn stale across crashes, clears, and compaction all live here.
Semantic search runs locally (all-MiniLM-L6-v2, no API calls, no data leaves your device): node daemons/semantic-search/search-vault.js "what did we decide about pricing" searches your vault by meaning, not keywords.
Vault as brain. Your AI's memory is an Obsidian vault, not a vector database, the same files you can open, read, search, and navigate yourself. Wikilinks ([[Project Alpha]]) build the knowledge graph your AI actually navigates. resume reads it, capsule writes to it, both fire on their own: see Auto-Refresh above for exactly what gets committed and when. See the two-verb lifecycle doc for the full write-ahead/flush contract.
Testing isolation: scripting
claudechild sessions inside your vault directory means their Stop autosaves write real capsules into your real vault. Point automated children at a scratch root viaAIGENT_ROOT.
Measurement layer. Most agent frameworks let the AI talk; almost none measure how often it's confidently wrong. HONESTY_LEDGER.md, TRUST_DECAY.md, and FAILURE_MODES.md are paired ledgers (a claim captured, then resolved later as held/drifted/reversed) plus drift detection at resume (decision aging, attention reconciliation vs. ACTIVE_PRIORITIES.md). The credible claim: the framework measures its own AI's calibration over time, not just its output. A Stop hook closes the loop by noticing when a turn made confident claims that no ledger recorded, so the ledgers fill from real work instead of waiting to be remembered: Closing the Measurement Loop. Full doctrine: vault/concepts/Cost of Confidence.md.
Caddy: the skill that finds the right skill. A non-blocking UserPromptSubmit hook matches your words against every skill in your catalog and surfaces the one that fits, without ever blocking the turn on a wrong guess. A PostToolUse hook detects a newly dropped skill and nudges /caddy-enroll to index it; the golf bag stays complete without manual upkeep.
Self-aware about what it doesn't do yet. system/12_authority_matrix.md bounds what the AI decides alone vs. brings to you; /dream proposes improvements but only the operator approves merges: see docs/meta-aigent-doctrine.md for the safety boundary.
aigent-OS is opinionated but built to be forked.
Start here (10 minutes):
system/00_identity.md: tell it who you aresystem/14_decision_framework.md: encode how YOU make decisionssystem/12_authority_matrix.md: set boundaries that match YOUR risk toleranceThen build over time: add your projects to vault/projects/, your people to vault/people/, drop concepts into vault/concepts/. The vault grows with every session; it compounds.
The most differentiating thing about aigent-OS isn't a feature; it's that the framework operates on itself. What ships today is the maintenance half: a nightly self-maintenance routine you can run against your own vault, and a hook that spots a new skill file and prompts you to enroll it. aigent-OS installs no scheduler, so the nightly routine runs when you or your own cron entry runs it. Releases are recorded by hand in CHANGELOG.md.
The publish half is designed but not built. The intended shape is a skill that classifies each vault file (private: true | false | review frontmatter, defaulting new files to review), tests it against a genericity bar (useful to at least three radically different principals, or it stays private), secret-scans it, drafts the commit, and opens the PR. None of that exists yet: no file carries the flag, no code reads it, and deciding what graduates from a local install into this repo is a manual judgement call today. No plan in this repo schedules the skill itself; the nearest related item is a proposed public-content lint that would keep files marked private: true out of release artifacts (docs/review-hardening-plan.md). Full manifesto, including why the recursive layer is the category claim: docs/manifesto.md.
Not a chatbot skin. No personality prompts, no "you are a helpful assistant": operational infrastructure.
Not a code framework. No database, no server, no build step. The kernel is markdown; the installer needs Node.js 18+ for the refresh runner and local search.
Not a RAG system. The vault is human-readable by design: open Obsidian, don't query an embedding store.
Not another agent framework. LangChain and CrewAI are for developers building pipelines. aigent-OS is for principals who want an AI that actually operates, one operator, one Claude, at a time.
Explicitly non-normative: nothing below is claimed as shipped, and none of it appears in the tables above until it is.
vault-sync.mjs path-scoping polish: tightening the memoryPaths exists-filter at the edges of what counts as "durable memory" for a sync commit.One structural note, since it comes up: the core is scoped to a single operator running a single Claude session at a time. Two opt-in mods in plugins/, fleet-band and fleet-delivery, are the first pieces that let several seats work side by side, and we run aigent-OS that way. They are a pilot on master, not yet in a release, and the shared message room and job scheduler they connect to are not part of this repo.
PRs welcome. See CONTRIBUTING.md for what lands well and how to write rules that fit the existing style. Highest-value areas: decision framework lenses for new domains, hook scripts for additional Claude Code events, vault templates, integration guides, sanitized examples for vault/examples/.
See CHANGELOG.md for release notes.
aigent-OS is the free, open-source harness of The AIgent, a media project for people building with AI. The rest of what's free to take lives at the public tools.
Built by The AIgent
In daily use since April 2026. Today four seats run The AIgent newsletter; see In production for what that does and does not show. This framework emerged from real operational needs, not theory.
If this saves you time, star the repo. That's all the thanks needed.