Skip to content

lucadallavalle/agentfiles

unversioned · d65cd20e6c69MIT

Personal agent development setup for Claude Code, OpenCode and Codex

agentfiles

My agent development setup, like dotfiles but for coding agents: Claude Code, OpenCode and Codex. It encodes my development process once and applies it on every machine I code on, local or cloud. It never adds a committed file to a repo I only contribute to.

Status: agentfiles bootstrap sets up a machine and agentfiles doctor keeps it in sync: the plugins of Claude Code, Codex and OpenCode at the CLI's commit, their user-level config, the common documentation, and the copies in owned repos (plan 001, plan 002). Design: ADR-001; all decisions: decision log.

How it works

PluginsCLI agentfiles
Whatskills, hooks and commands, one plugin per harnesssets up and checks: installs the plugins, merges user-level config, sets up repos
Runsinside a harness session (/grill, a hook firing)in the shell, once per machine (bootstrap) or repo (attach, scaffold), and to find drift (doctor)
Installed bythe CLI, through the harness's own plugin commandsa git clone at ~/.local/share/agentfiles, run with node (Setup)

Like dotfiles: the plugins are the config files, the CLI is what puts them in place. Plugins, not files copied by the CLI, so each harness installs, updates and namespaces them itself and nothing overwrites my edits; the cost is one adapter per plugin format.

Setup

{ [ -d ~/.local/share/agentfiles ] || git clone https://github.com/lucadallavalle/agentfiles ~/.local/share/agentfiles; } && node ~/.local/share/agentfiles/bin/agentfiles.js bootstrap --owner lucadallavalle

Needs Node 22 or later, git and at least one harness; bootstrap never installs a harness and exits 2 naming what's missing. It adds each --owner (repeatable) to owners in ~/.config/agentfiles/config.json, links ~/.local/bin/agentfiles to the bundle (and says so when that directory isn't on PATH; it never edits shell files or replaces another file there), then runs doctor --fix, whose exit code it returns. Safe to rerun. spiral-review's install and init will join it (roadmap step 4).

Hosted sessions (Claude Code on the web, Codex cloud) get no user-level config of their own: put the same line in the environment's setup script, which runs before each session (as root on Claude Code on the web). Codex cloud is unverified.

Plugins

agentfiles doctor --fix installs and updates the plugin of each installed harness at the CLI's own commit (Claude Code: marketplace added by https://github.com/lucadallavalle/agentfiles.git, following main, then plugin install agentfiles@lucadallavalle -s user; when main has moved past the CLI's commit it reports outdated: main is at <commit>; Codex: marketplace pinned to the commit, marketplace add lucadallavalle/agentfiles@<sha> then plugin add agentfiles@lucadallavalle, moved by plugin remove, marketplace remove and both adds again; OpenCode: plugin add github:lucadallavalle/agentfiles#<sha>, moved by plugin remove of our entry first, so one plugins entry remains). Plugin drift needs the CLI's clone without local changes at a commit of main, else it prints one skip line. A running session picks up a plugin update in its next session.

Claude Code: skills run as /agentfiles:<skill>. OpenCode: skill IDs are flat (@grill); a same-ID skill you already have wins. Codex: skills run as $agentfiles:<skill>. Skill links made by the former install.sh in ~/.claude/skills/ stay until removed by hand.

User-level config

agentfiles doctor        # report drift; exit 0 in sync, 1 drift, 2 error
agentfiles doctor --fix  # write missing and outdated entries, remove unshipped ones

The CLI exits 2 below Node 22. config/ is the shipped config; doctor --fix copies config/instructions.md to ~/.config/agentfiles/instructions.md and the common documentation to ~/.config/agentfiles/documentation/ (skills read it when a repo has no docs/documentation/), and merges files, settings keys and list elements into each installed harness (Claude Code: rules/agentfiles.md importing it, settings.json "attribution": false (Claude Code 2.1.281 or later) and Bash(<prefix> *) permission rules; Codex: developer_instructions in config.toml, prefix_rules in rules/agentfiles.rules; OpenCode: the instructions element and V2 permissions shell rules, first so your own rules win, in opencode.json, or opencode.jsonc when it's the only file), recording what it wrote in ~/.local/state/agentfiles/state.json (XDG variables honored). An entry you edited, or one you already had with another value, is reported with the shipped value and never overwritten: restore that value, or, for a value you already had, remove yours and run --fix. To change shipped config, change config/. OpenCode: only V2 permissions are supported; V1 permission rules in the same file resolve before ours, so ours override them. A harness running during --fix may rewrite its settings and drop our entries; the next doctor reports them as edited.

Updating the CLI

Run from a git clone on branch main without local changes, doctor first fetches and reports agentfiles clone behind main; --fix fast-forwards it and runs again from the new commit. Off main, with local changes or ahead of main, it prints one skip line; offline, can't check main (offline).

Owned repos

In a repo whose remotes all belong to an owner listed in ~/.config/agentfiles/config.json ({"owners": ["<name>", …]}, case-insensitive, any host), doctor also checks the common documentation copies in docs/documentation/ (repo <path> <state>): --fix writes missing and outdated copies and removes ones no longer shipped, never overwrites an edited copy and never commits. A copy is unedited when its hash is in config/documentation-hashes.json, every version ever shipped (pnpm generate appends, the gate keeps it append-only). Outside a git repo, in a foreign repo (a fork of one included) and in this repo, doctor says nothing about the repo.

Layout

docs/
  documentation/   common documentation: rules and templates, copied into owned repos
  adr/             architecture decisions
  decisions.md     decision log
  ROADMAP.md
  HANDOVER.md      current state for the next session
skills/<name>/     skills, one SKILL.md each, shared by every harness
config/            shipped user-level config: instructions, permissions, <harness>.json keys
src/               TypeScript: cli/, core/, adapters/<harness>/, generate.ts
bin/agentfiles.js  CLI bundle, generated
.claude-plugin/    Claude Code marketplace, generated
.agents/plugins/   Codex marketplace, generated
plugin.json        Codex plugin manifest, generated
.githooks/         this repo's git hooks
AGENTS.md          gate command, domain words

Skills

SkillLoop of the development process
grillStrategy and feature: the owner's review of a PRD, plan, ADR or design before it merges (/grill, manual)
review-chunkExecution: reviews one chunk's PR or branch against its plan and its code (model-invoked)
execute-planExecution: orchestrates a merged plan's chunks: implementers, review loop, PRs, handover, merges (manual)
write-planFeature: writes a plan from the common template, with chunks and open questions, on a docs PR (model-invoked)

Development

Gate: pnpm install && pnpm check && pnpm compile (see AGENTS.md). Manifests are generated from package.json and the skills, the CLI bundle from src/cli/ (rolldown): pnpm generate, then commit; the gate fails when they are stale. Test local edits with claude --plugin-dir . from a checkout named agentfiles (without .claude-plugin/plugin.json the directory name is the plugin name). AGENTFILES_COMMIT=<sha> sets the commit plugin drift compares with, for checks from a branch: it must be on origin/main, else doctor exits 2. Pre-commit hooks (no commits to main, file hygiene, gitleaks, the gate): need pre-commit (pipx install pre-commit); pnpm install enables them through .githooks/pre-commit (pnpm:devPreinstall sets core.hooksPath). Don't run pre-commit install: it refuses while core.hooksPath is set, and unsetting it disables the hooks in .githooks/.