Skip to content
dot
Esc
↑↓navigate↵open⌘Jpreview
On this page

Agents

What a coding agent may run on its own, what waits for you, the dot skill for agents in other projects, and Claude Code hooks.

dot is built to be used by coding agents as well as people. The repo’s AGENTS.md tells an agent the rules; these are the ones that matter to you.

What an agent may do on its own

  • dot check, dot explain, dot doctor and every --help: they never change anything, and never need a password or Touch ID.
  • Read the repo and these docs. The site publishes llms.txt, the whole docs as one file (llms-full.txt), and every page as raw Markdown.

What waits for you

  • dot apply, and anything else that changes the Mac, including dot clone and dot fork.
  • Anything with sudo.
  • git push, since your fork is public.
  • Creating or changing a secret’s value. An agent never reads or prints a private key, token or secret value; a project secret only travels through pipes (dot secret).

Touch ID

Commands that reach an account through 1Password (gh, vercel, dot auth status, dot fork, dot secret, dot conf) ask you to authorize the app the agent runs in, such as a terminal or the Claude app. The approval covers that app for a while, not one command, so agents batch those commands into one shell call instead of counting on a prompt per call; Accounts compares what each login costs.

Agents and their scripts run gh and vercel as those tools’ docs say. The shims from op shim come first on PATH and run them through 1Password’s shell plugin, so any process gets the token, only for that command; the zsh functions 1Password generates would only reach an interactive shell. A token in the environment that 1Password didn’t set, such as one a cloned repo’s .env loads, is ignored with a message, so a repo can’t change who gh acts as; and gh auth login or vercel login answers that the login lives in 1Password.

With an agent token set up (GitHub), an agent’s gh gets a token limited to the repos it works on, one per GitHub owner, picked by the repo the command targets. It never gets yours, unless you set an owner to personal: then each of the agent’s calls for that owner uses your token and asks for your approval. A 1Password service account that can only read the Agents vault fetches it, so the agent’s calls ask you nothing; if that fails, the command fails. vercel, which has no agent token, fails for agents and works only from your terminal.

An agent never puts a token in its own shell, because its output is kept on disk. A project’s secrets reach it through the project’s .env.schema (dot secret attach); for a one-off script that needs a secret outside it, the agent passes a 1Password reference through op run, which injects the value into that process only and masks it in the output.

On a clean Mac, an agent runs the installer with --yes --no-apply: it installs, stops after dot check, and shows you what apply would change.

The dot skill

AGENTS.md only reaches an agent working inside this repo. The dot skill, in skills/dot/, carries the same rules to agents working anywhere else: how to find dot, which commands they may run on their own, which task maps to which command (dot clone instead of git clone, dot secret instead of a token in a file, a config/ line instead of brew install), and how to batch the commands that ask for Touch ID.

It’s a standard Agent Skill, so the skills CLI installs it for Claude Code, Codex, Cursor and the other agents it supports, straight from GitHub:

npx skills add rbadillap/dotfiles --skill dot --global

It asks which agents to install it for. npx skills update brings in a newer version after you change the skill.

As an Agent Plugin

The repo root is also an Agent Plugin: plugin.json names it dot and the spec finds the skill in skills/dot/ (§6.1, §7.1). A client that installs Agent Plugins can load it from the repo directly.

A workflow, .github/workflows/agent-plugins.yml, checks plugin.json against the spec with agent-plugins-validate on every pull request and every push to main. When a manifest that was valid breaks on main, it opens an issue, and closes it once fixed.

Claude Code hooks

Claude Code (the CLI and the desktop app’s Code tab) reads ~/.claude/settings.json. Claude Code writes its own settings there, so dot only adds hooks to that file and never touches the rest. To add one, put the script in config/home/.claude/hooks/ and a claude hook line in config/claude.conf; the script is linked into ~/.claude/hooks/.

dot check claude     # which hooks are missing
dot apply claude     # add them

A new or changed hook takes effect in the next Claude Code session.

Was this page helpful?