Upgrading from v0.83.0

Stop any running agnostic-ai watch process before updating the installation or project config.

Project installs must change the dependency and lockfile together. Claude Code's new SubagentStart memory hook runs the project's own node_modules/.bin/agnostic-ai when one exists. The hook exists when you use the memory built-in and Claude Code loads personal memory itself. If that binary does not match the version pinned in package.json or requires, the hook fails and names both versions, until you reinstall. Update package.json, the lockfile and requires in one change, then install. agnostic-ai project --bootstrap reinstalls from the lockfile, so the lockfile must already hold v0.84.0. On Windows the hook needs sh on PATH, for example from Git Bash. See project version checks and Claude Code's own memory.

Install through your existing package manager. For a global npm installation:

npm install -g agnostic-ai@0.84.0

For an exact project config pin, agnostic-ai upgrade --requires updates requires and the schema URL to the installed version, then syncs. It also replaces minimum or range requirements and local overrides. To keep a deliberate minimum or range, retain that value, update the schema URL to v0.84.0, review agnostic-ai migrate --dry-run, and run agnostic-ai sync. See upgrade behavior.

The handoff and memory built-ins changed text, so sync --check reports drift until you run agnostic-ai sync. Finish with agnostic-ai sync --check, then restart watch.

Codex users who enable handoff-hook approve the changed hooks once. Codex marks a changed hook for review and skips it until you trust it (Codex hooks). After sync, open /hooks in Codex and approve the handoff hooks. agnostic-ai doctor -t codex fails while a handler is untrusted.

lint has new findings. See lint codes.

  • LINT046 is a warning for a spec that writes one top-level key twice. import cursor in v0.83.0 could leave a repeated workspaces line in a skill. Remove the extra line from each affected spec. lint --strict fails until you do.
  • With the memory built-in, LINT044 is an error when project memory holds hidden characters such as zero-width or bidirectional controls. Run agnostic-ai memory lint and remove what it reports.
  • With the memory built-in, LINT043 is a warning when Claude Code's own store holds facts that personal memory lacks. Copy them with agnostic-ai memory import --from claude (see below).

What agnostic-ai changed

Start one personal memory per repository, and keep what Claude Code saved

memory.personal: repo already gives every worktree of a repository one personal memory. Without it, each checkout keeps its own, and deleting a worktree deletes what it learned. For a new Git project, agnostic-ai init --memory now turns on shared memory and writes that setting to a new agnostic-ai.local.yaml. For an existing project, add it yourself and run agnostic-ai sync:

memory:
  personal: repo

agnostic-ai memory path prints the shared folder under ~/.agnostic-ai/local/memory/. After a mode switch, the first sync copies your facts when the new folder has none. Otherwise lint names the facts left behind, and agnostic-ai memory import --from checkout copies them (--from repo when you switch back). A linked worktree follows the main checkout's setting. Some tools need the managed .gitignore block (gitignore.enabled: true, which init sets) to receive the folder path, and cloud agents never see personal memory. See one store per repository.

Claude Code now loads your personal list as its own memory, and a SubagentStart hook gives it to each subagent. The first sync copies facts Claude Code saved earlier when personal memory is empty. Otherwise copy them yourself, dry run first:

agnostic-ai memory import --from claude --dry-run
agnostic-ai memory import --from claude

The dry run lists each fact with its description. --only <file> copies just the ones you name. See memory import.

More tools now load the shared memory index themselves instead of relying on a rule that tells them to read it: Devin CLI (the windsurf target) and Auggie CLI on Unix at session start, Cline in VS Code at task start, Trae when project hooks are on, and Kiro and Antigravity through an include that sync writes. Keep each tool's own memory on; the memory guide now lists every tool's own memory and its default. See how each tool loads memory.

Find and resume handoffs from any worktree

A handoff used to be one .agnostic-ai/local/HANDOFF.md in a checkout, replaced each time. Now the skill saves one note per branch in the main checkout's ignored .agnostic-ai/local/handoffs/. Linked worktrees share it, and a note survives when its worktree is removed. With handoff-hook, the Git snapshots go to the same store. Sync adds the store to the write permissions of Codex, Qoder, Claude Code, OpenCode and Devin CLI, so a linked worktree can save there. See shared handoff access.

To see every saved task:

agnostic-ai handoff list

Each branch gets one row: its worktree (or removed), saved HEAD and date, working changes, status, PR and file. It suggests removing a task only when local Git shows the branch is merged, and it deletes nothing. Handoffs stay on one machine. See handoff list.

Keep your own permissions through sync and import

  • Sync keeps what you wrote by hand. OpenCode permission keys, rules in the allow, deny and ask lists of .devin/config.json, and handoff grants you added stay next to the ones your specs write. A spec that starts setting an OpenCode key you wrote saves opencode.json.bak first. In OpenCode, a deny or ask you set on the memory folder or the handoff store stays.
  • Import leaves out what sync granted. import codex keeps the memory and handoff stores out of codex.config.toml, and import windsurf keeps the memory and handoff rules sync wrote out of the spec.
  • import --dry-run now matches the real import in repo memory mode. import leaves a spec as written when its frontmatter parses the same as the native copy.

Try the opt-in Ellipsis target

ellipsis is off by default. It writes the two kinds of file Ellipsis reads from the default branch: .ellipsis/code-review.yaml from your review specs and a settings spec, and .ellipsis/environments/<name>.yaml (repository, setup scripts, MCP servers) from your environment and MCP specs. Add ellipsis to targets, then name the reviewer in .agnostic-ai/settings/ellipsis.yaml:

x-ellipsis:
  reviewer:
    name: project-review
    claude_code:
      model: claude-opus-5-5

agnostic-ai sync --dry-run

Without a review spec, sync writes no review file. The environment is optional; select it with x-ellipsis.environment. agnostic-ai import ellipsis reads hand-written files back. You commit the files to the default branch, install the Ellipsis GitHub App and store each secret your MCP specs reference in Ellipsis; sync does none of these.

Run the verify steps on a pull request. See Ellipsis.

Sync faster and set a session age limit

The first sync in a fresh clone is several times faster, and the change summary counts only the targets each change reaches.

session-retention-days in a home settings spec sets one personal session age limit for Claude Code, Gemini CLI and Qoder CLI. Only sync --global writes it, and lowering it warns that older sessions will be deleted. See session retention.

Smaller changes include Git Bash lookup for Claude Code hooks on Windows, Cline global hooks for the SDK and CLI, and team facts that Gemini CLI saves to shared memory. Full list: v0.84.0 release notes.

What changed in the targets

OpenCode V2 reads only AGENTS.md. The V2 migration page, checked October 14, 2026, says "V2 currently only discovers AGENTS.md" and tells V1 users who relied on a CLAUDE.md fallback to move that guidance into AGENTS.md. Sync already writes the root AGENTS.md for OpenCode, so generated instructions reach V2. Instructions kept only in a hand-written CLAUDE.md do not. The agnostic-ai docs now say so.

Codex agent files inherit the session's settings. The Codex subagents page, checked October 14, 2026, says sandbox_mode, approval_policy, model_provider and mcp_servers "don't override the parent configuration when placed in a custom agent file". Agent files can still set model, model_reasoning_effort, model_reasoning_summary, model_verbosity, features.* switches and skills.config. Sync keeps x-codex.features and skills.config entries in agent files, and it now reports approval policies, model providers and MCP servers as having no effect. Set those in the parent session. Codex's hooks reference also lists fork as a SessionStart source, and hook diagnostics accept it. See Codex agents.

OpenCode and Devin CLI prompt before writing outside the project. OpenCode's permissions page, checked October 14, 2026, says external_directory covers tool calls that touch paths outside the working directory, and defaults to "ask". The Devin CLI permissions reference, checked the same day, says writes outside the workspace still prompt in Accept Edits mode. Sync now grants both tools the shared handoff store (permission.external_directory for OpenCode, Write(<store>/**) in .devin/config.json for Devin CLI), as it already did for the memory folder. See OpenCode and Windsurf / Devin.

Antigravity documents session-start hooks and counts includes toward rule size. Its hooks reference, checked October 14, 2026, lists a SessionStart event and an auto_approve decision for PreToolUse. Sync now writes SessionStart hooks, and hook run accepts auto_approve replies. Its rules page, checked the same day, says it "truncates any single rule file that exceeds 24,000 bytes (after expanding @[label](path) includes)". The memory include rule now warns when its expanded size passes that limit. See Antigravity shared memory.

Kiro's local command sandbox is available to every V3 user, and you set it up in Kiro. Kiro's changelog of October 13, 2026 says CLI 2.31.0 "makes the local command sandbox and local autonomous mode available to every V3 user". The sandbox page, checked October 14, says it needs IDE 1.3 or CLI 2.31 or later, is off by default, and reads project settings from .kiro/settings/sandbox.json. It adds: "A repository you clone cannot use its project file to open network access or disable an active global sandbox policy." agnostic-ai neither writes nor reads that file.