Skip to content
agents

Troubleshooting

no agents repo found

You haven’t run agents init on this machine, or you removed the pointer file without telling agents where to look.

Terminal window
agents init <git-url>                 # clone existing repo
# or
agents init --scaffold                # fresh repo at ~/.config/agents/

git pull --ff-only refused: local and remote have diverged

Two machines committed lockfile changes without one pushing first. agents refuses to mutate until it’s resolved.

Terminal window
cd ~/.config/agents        # or wherever your pointer points
git pull --rebase
# resolve any TOML conflicts in your editor
git push
agents apply

note: N lockfile entries reference unregistered project aliases

A project-scoped entry refers to an alias this machine hasn’t registered. Either register it or ignore — the entries are simply skipped.

Terminal window
agents project add canva ~/work/canva
agents apply

Real skill directory at a target install path

For managed skills, the agents repo is canonical. If a real directory already exists at a harness skill path, agents apply deletes that harness-local copy and replaces it with a symlink to <repo>/skills/<name>/. The same happens during agents skills add. agents also removes stale cross-tool aliases under .agents/skills for that managed skill.

Pre-existing instructions file (CLAUDE.md, AGENTS.md, …)

When agents apply would write a managed instructions file but a foreign one already lives at that path, an interactive prompt offers three options:

  1. Skip syncing instructions on this machine — persistent opt-out. Records instructions_skip = true in machine.toml so future runs stop prompting and stop syncing instructions on this machine. To re-enable, clear that flag.
  2. Cancel — abort this apply run. The instructions pass exits early (no remaining harnesses are processed either) and nothing is recorded. The next run will prompt again.
  3. Overwrite — adopt the managed version. The existing file is moved aside to <name>.bak.<unix-ts> (same semantics as agents apply --force) and the managed version is written.

In non-interactive contexts (no TTY) apply defaults to Cancel. Use agents apply --force to overwrite without the prompt.

Author identity unknown during agents init or auto-sync

git itself isn’t configured. One-time per machine:

Terminal window
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

agents soft-fails on commit/push errors — your local change is kept; you can re-run after fixing the issue and the queued commit will go out.