What OAT Writes

This page lists what each OAT command writes in your repository, under your home directory and on your shared origin remote, which of those files belong in Git, and how to back out of OAT completely. Everything here was observed by running OAT CLI version 0.3.14 on macOS. The removal procedure in Remove everything was run end to end twice, once originally and once in an independent re-run, and both times it returned the repository and the home directory to their pre-OAT state.

A few terms used below. Canonical assets are the skills and agent definitions OAT keeps under .agents/; they are the source you edit. A provider view is the copy or link OAT creates from a canonical asset in the folder a coding tool reads, such as .claude/skills/. Scope says where a command works: project means the current repository, user means your home directory, and all means both. A tool pack is a named bundle of skills, agents, templates and scripts that oat tools install adds.

The short version

• With --scope project, oat init, oat sync and oat tools install <pack> write only inside the repository. Two forms are exceptions: oat tools install --scope project without a pack name also installs the core pack under your home directory, and oat init --scope project --setup installs every pack there.
• Without --scope, oat init and oat sync use scope all, so they can also write under your home directory, and oat tools install <pack> installs a pack that is not yet installed under your home directory (user scope).
• The core pack is user-only: it installs under your home directory or not at all.
• Tracked projects default to synced scope, which keeps a project's files on a dedicated Git ref. Creating one commits a small pointer file to your current branch and pushes refs/oat/projects/<name> to origin. Apart from oat project prune, which deletes that ref again, no other command observed here changed origin, and none pushed a branch.
• There is no single uninstall command. The manual steps in Remove everything return the repository's files and your home directory to their pre-OAT state; Git history keeps OAT's commits.

What each command writes

Where a file already existed, OAT appended its own marked block instead of replacing it. This held for .gitignore, .gitattributes, an existing pre-commit hook and the other settings in an existing .codex/config.toml (OAT does change multi_agent and max_depth there; see the provider table). A pre-existing ~/.claude/settings.json was left untouched.

Setting up

oat init creates no AGENTS.md and no .oat/config.json. Run non-interactively, it installs no hook unless you pass --hook.

The optional pre-commit hook

The hook runs oat status --scope project --hook only if an oat binary is on your PATH. When provider views are out of date it prints oat: managed provider views are out of sync - run 'oat sync --scope project'. It never blocks a commit.

Syncing provider views

oat providers set --scope project --enabled <providers> writes .oat/sync/config.json. oat sync then creates views for each enabled provider and rewrites .oat/sync/manifest.json, the file that records which views OAT manages. A provider does not have to be enabled: an existing .claude/ directory in the repository, or ~/.claude/ in your home directory, is enough for oat sync to create Claude views.

OAT creates skill views only for Claude. It reports the other providers' skill support as native-read and creates no skill views for them. No generated file contained an absolute path.

Installing tool packs

Some packs write more at project scope. The ideas pack adds .oat/ideas/backlog.md and .oat/ideas/scratchpad.md. The workflows pack adds .oat/projects-root, .oat/projects/local/.gitkeep, .oat/projects/archived/.gitkeep and a projects.root setting. Passing --project-guidance adds a marked <!-- OAT tools --> block to AGENTS.md, creating the file if needed. Installing every pack at once with oat tools install --scope project puts core in your home directory and the other seven packs in the repository, and also adds a localPaths setting and a # OAT local paths block to .gitignore.

No tool pack command wrote to origin.

Creating tracked projects

A tracked project is the set of planning and implementation files OAT keeps for one piece of work. Its scope decides where those files live.

Every scope also writes two ignored files: .oat/config.local.json, which records the active project, and .oat/state.md, a generated dashboard. A synced project also adds Git's own .git/worktrees/<name> and a local refs/oat/projects/<name> ref.

Without an origin remote, the default command exits with Synced project creation requires a configured origin remote. Configure origin or use --scope local. and writes nothing. To make another scope the default, run oat config set projects.defaultScope shared (or local), which edits the tracked .oat/config.json.

What to commit

"Ignored" means OAT's own .gitignore block matches the path. "Machine data" is anything that differs between machines.

Setup and configuration

Canonical assets and pack files

Provider views

Projects

Where "Team choice" applies:

• .oat/sync/manifest.json. A sync that changes a view, or that runs with a different CLI version than the last one, rewrites it with new timestamps and its own version, so committing it adds diffs to sync commits and to mixed-version teams. Leaving it out means a fresh clone has no record of which views OAT manages. How OAT behaves in a clone without it is not covered here.
• Generated provider files (Cursor model variants, Codex agents and config.toml tables). Committed, they arrive with every clone. Not committed, each teammate runs oat sync --scope project to generate them. Either way, oat tools remove does not delete them; see Backing out.
• Pack files in .oat/ (templates, scripts, ideas, projects-root). Committed, every clone has them. Not committed, each teammate needs the same oat tools install to get them.
• AGENTS.md guidance block. It tells agents how to refresh views, but the command it recommends, oat sync --scope all, also writes under each reader's home directory.
• A hook inside the working tree. Committed, everyone using that hooks path gets the drift warning. A hook in .git/hooks is never committed.
• pr/ and reviews/archived/ folders. Whether PR material and archived reviews are shared through Git or stay on each machine. Whether OAT ignores them depends on which install command you ran; see surprises.

A new teammate after cloning

1. Install the CLI. The README gives npm install --global @open-agent-toolkit/cli and requires Node.js 22.17 or newer and Git 2.31 or newer.
2. Check the views. Run oat status --scope project. Committed symlink views are relative links into .agents/, so they point at the same files in every clone. A row marked ✗ missing means a view was not committed or not yet generated; run oat sync --scope project to create it. Generated Cursor and Codex files exist only if your team committed them. After a sync, OAT reports Claude views as restart-required: start a new Claude Code session to pick them up.
3. Add the hook if you want it. .git/hooks is not part of a clone, so each teammate who wants the drift warning runs oat init --scope project --hook.
4. Install personal packs separately. User-scope packs live under each person's ~/.agents and ~/.oat, so nobody receives them from the repository. A teammate who wants them runs oat tools install --scope user, which installs all eight packs. Run inside a repository where the workflows pack is installed at project scope, it also edits that repository; see surprises.
5. Fetch synced projects explicitly. A fresh clone does not receive refs/oat/*, so synced projects are not in it. See Picking Up Projects to list and pull them. Ignored files (.oat/config.local.json, .oat/state.md, local projects) never travel.

Backing out

Stop without removing anything

Disabling a provider does not remove its views. oat providers set --scope project --disabled claude only updates .oat/sync/config.json. The existing .claude/skills/ links stay, and a following oat sync removes nothing. oat status then reports No managed entries found. while the manifest still lists those links. To remove views, use the commands below or delete them yourself.

The hook does nothing when no oat binary is on PATH, and oat init --scope project --no-hook removes it.

Supported removal commands

No command deletes a shared or local project. oat project prune refuses a shared project, and oat project archive moves a project to .oat/projects/archived/<name> rather than deleting it.

Remove everything

These steps were run in a repository that had adopted OAT with Claude as its only provider, the hook, packs at project scope, core at user scope, and one project of each scope. Afterwards the repository's files, its .git/hooks folder, its local Git config and the home directory matched their pre-OAT state exactly, and no refs/oat/* ref remained locally or on origin. The run started with a .gitignore but no .gitattributes; adjust steps 5 and 6 if yours differ.

1. Remove the hook: oat init --scope project --no-hook. In a terminal, oat init first shows the provider selection; keep the current choices.

2. Delete each synced project, including its ref on origin: oat project prune <name>. Without the command, run git worktree remove .oat/projects/synced/<name>, git update-ref -d refs/oat/projects/<name> and git push origin --delete refs/oat/projects/<name>, then git rm .oat/projects/synced/<name>.json.

3. Remove user-scope packs and their links in ~/.claude: oat tools remove --all --scope user.

4. Remove each pack you installed at project scope, one command per pack: oat tools remove --pack <pack> --scope project, where <pack> is any of ideas, docs, workflows, utility, research, brainstorm and project-management that you installed. The PACK column of oat tools list --scope project shows them.

5. Untrack and delete OAT's repository files:

   git rm -r -q --cached .agents .claude .oat .gitattributes
   rm -r .agents .claude .oat .gitattributes

   Leave out any path that does not exist or that Git does not track; otherwise git rm stops without removing anything. If .gitattributes existed before OAT, leave it out too and delete only its # OAT core block.

6. In .gitignore, delete the # OAT core … # END OAT core block, the # OAT local paths … # END OAT local paths block if present, and the blank line OAT added before each.

7. Commit: git add .gitignore && git commit -m "remove oat".

8. Clean the home directory. If ~/.oat and ~/.agents did not exist before OAT, run rm -r ~/.oat ~/.agents. Otherwise delete only ~/.oat and the skills and agents OAT installed under ~/.agents; other tools also read ~/.agents/skills directly, so it may hold your own skills. Then run rmdir ~/.claude/skills, which fails safely if the folder still holds anything.

If you had enabled Cursor, Copilot or Codex, OAT also created the paths in the provider table. Removing those was not part of this run.

Git history still contains the OAT commits: your commit that added OAT's files, the project scaffold commits and the prune commit stay on your branch, and anything you pushed stays on origin. Deleting refs/oat/projects/<name> removes the ref, not the data: the project files it pointed to stay in origin's storage until the host garbage-collects them, so do not rely on prune to erase sensitive content. Rewriting history is not covered here.

Known surprises in 0.3.14

These are current behaviors as of version 0.3.14.

• oat tools install core --scope project prints Installed core tool pack. but writes nothing.
• oat init --scope project --setup installs all eight packs under your home directory, and runs gh repo view, which makes the gh CLI write ~/.local/state/gh/device-id.
• oat tools install --scope user writes into the current repository when the workflows pack is already installed there at project scope: it adds localPaths to .oat/config.json and a # OAT local paths block to .gitignore.
• oat tools install workflows --scope project does not add that block, but oat tools install --scope project does, so pr/ and reviews/archived/ folders are committable in one setup and ignored in the other.
• oat tools remove --all fails unless you add --scope user.
• After removing packs, a stale tools.requiredBy entry stays in .oat/config.json, and oat status reports the utility pack as missing and suggests oat tools update.
• Removing a pack leaves its generated Cursor and Codex files, and a later oat sync reports no changes.
• An existing .claude/ folder, in the repository or your home directory, is enough for oat sync to create Claude views without enabling Claude.
• After oat tools install <pack> --no-sync, running the same install again reports unchanged and creates no views; run oat sync --scope project.
• The AGENTS.md block from --project-guidance recommends oat sync --scope all, which also writes under your home directory.
• oat project new --scope local prints Scaffold commit: skipped (--no-commit) even when you did not pass that flag.
• Piping oat tools list or oat status into head crashes with an Error: write EPIPE stack trace.

Not covered here

• Interactive prompts. Every run here was non-interactive. The hook, provider and local-path questions that oat init and --setup ask are described in CLI Bootstrap.
• Installing and upgrading the CLI. See Quickstart and Upgrading from an earlier CLI.
• Other platforms. Only macOS was observed, where every view was a relative symlink or a generated file. For the copy strategy, see Sync Config.
• User scope for providers other than Claude. See Scope and Surface.
• Project management adoption (oat pjm init and the .oat/repo/ tree). See Install vs. initialize.
• Instruction files and rules. CLAUDE.md shims from oat instructions sync, and syncing rules from .agents/rules, including how to remove them. See Instruction Sync.
• Later project commands. oat project push, pull, archive, migrate, archive storage, and what later lifecycle steps push to origin. See Picking Up Projects and Closeout Skills.
• Other maintenance commands. oat remove skills --pack, oat local, oat tools update, outdated and migrate. See Tool Packs and Config and Local State.
• Files you place at a view path yourself. See Manifest and Drift.
• gh repo view against a real GitHub remote, and Git versions older than 2.31.

Related

• Quickstart
• CLI Bootstrap
• Tool Packs and Installed Assets
• Manifest and Drift
• Provider Interop CLI Scope and Surface
• File Locations
• Starting Projects