agentstow

One canonical .agents/ folder, fanned out to all your AI coding agents.

Website and docs: https://agentstow.dev/

The Commons — the canonical ~/.agents/ directory — holds the single real copy of every config you share: skills, instructions, MCP servers, slash commands, agents and hooks. agentstow sync fans it out to every agent you actually have installed.

Configs that can be byte-identical everywhere are symlinked, so there is one file seen from ten places and drift is impossible by construction. Configs that cannot be — MCP servers and hooks, which live inside files the agent also owns, in formats no two agents share — are rendered and key-merged, with your other keys preserved.

There is no state file. There never will be. The filesystem is the state.

~/.agents/
├── skills/<name>/       fanned out as symlinks
├── commands/<name>.md
├── agents/<name>.md
├── AGENTS.md            symlink, import-line, or rules-dir link per agent
├── mcp.json             rendered into each agent's native dialect
└── hooks/<Event>.toml   merged by command string

Install

npm install -g agentstow      # prebuilt binary, macOS, Linux and Windows, no toolchain
pip install agentstow         # the same binary, shipped as a wheel
cargo install agentstow       # from source, needs Rust 1.97+

npx agentstow doctor          # or try it first, without installing anything
uvx agentstow doctor          # the same, if you reach for uv rather than npm

On macOS and Linux there is also a Homebrew tap. It lives in this repository rather than a separate homebrew-agentstow one, so it is tapped by URL:

brew tap agentstow/tap https://github.com/agentstow/agentstow
brew trust agentstow/tap      # Homebrew 6 refuses to load untrusted third-party taps
brew install agentstow

Use

agentstow init            # create the Commons and report what this machine already has
agentstow adopt <path>    # take a path under management; --dry-run names the mechanic
agentstow sync            # fan out; --dry-run prints the full plan
agentstow status          # what is linked, what is not, and what is not ours
agentstow doctor          # installed agents, Commons hygiene, Sourced entries
agentstow revert <agent>  # offboard one agent (refuses until you disable it)
agentstow mcp list | adopt | remove | enable | disable

adopt picks its mechanic from where the path lives: a real config inside an agent's directory is moved into the Commons with a link left behind; a path inside a git repo becomes a Sourced entry — the Commons links out to it and the repo keeps the truth; anything else is copied in. To gate CI on drift use status (exit 0 clean, 2 actionable, 1 error) — sync --dry-run previews, it does not gate.

Agents

Claude Code, Codex, opencode, pi, oh-my-pi, OpenClaw, Hermes, Gemini CLI, Cursor, Windsurf, Roo and Cline. Detection is simply whether the agent's config directory exists — agentstow never creates one. Agents that read ~/.agents/skills natively (Codex, opencode, oh-my-pi, Gemini CLI, Cursor) get no skill links written, because nothing needs to be — and where an agent still reads its old fan-out directory beside the Commons (Codex, Cursor), sync prunes agentstow's now-duplicate links from it.

Interop

The Commons speaks the conventions that won: skills/<name>/SKILL.md — the layout opencode and friends read natively — one AGENTS.md, and an mcp.json in the standard mcpServers shape. .agents Protocol surfaces (tasks/, memories/, models.json, system-prompt.md) are recognized by doctor and never touched.

What it will not touch

Anything it does not own. A symlink pointing outside the Commons, a hand-written file, an MCP server whose name isn't in the Commons — all Foreign, all reported by status, none ever modified. A real directory shadowing a Commons entry is a Variant: deliberate, preserved, and counted as actionable only when its contents are identical to the Commons copy, so you can dedupe on purpose.

The Commons is exactly that — a commons, not agentstow's alone. opencode, oh-my-pi and Hermes read ~/.agents/ themselves, and other tools keep their own files there. doctor names entries that aren't agentstow's and leaves them be; status stays target-only, since a neighbour's file has no fan-out to report.

Configuration

Optional agentstow.toml in $XDG_CONFIG_HOME/agentstow/ (default ~/.config/agentstow/): disable targets, define custom ones, scope MCP servers per agent, per-agent Tweaks. The lock — agentstow's only machine state — lives in $XDG_STATE_HOME/agentstow/ (default ~/.local/state/agentstow/). Environment: AGENTSTOW_HOME relocates the Commons (doctor warns — native readers won't follow), AGENTSTOW_TARGET_ROOT resolves everything against another root, AGENTSTOW_LOCK_TIMEOUT_MS bounds the lock wait.

What it does not do

No cross-machine sync — version the Commons with git or chezmoi. No undo — refusals come before writes, sync plans everything before writing anything, sync and adopt preview with --dry-run, re-runs are idempotent, and a git-versioned Commons is better history than any journal. No memory sync: agent memory is not a defined artifact and agentstow will not pretend otherwise. No GUI, daemon or file watcher. It does not install skills; it fans out whatever is in the Commons, whoever put it there.

On Windows, creating symlinks requires Developer Mode (Settings → System → For developers) or an elevated shell; sync says exactly that when it cannot link.

Name and inspiration

The name is a nod to GNU Stow, the classic symlink-farm manager — agentstow does for agent configs what Stow does for dotfiles. The project is also inspired by two neighbours in the same space: dotagents and agentsync.

Documentation · agentstow.dev · MIT

Project links

Data verified by PyPI on Aug 17, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.0.5)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for soulmachine from gravatar.com soulmachine

GitHub Statistics

Data verified by PyPI on Aug 17, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.8

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

agentstow-2.0.4-py3-none-win_arm64.whl (709.3 kB view details)

Uploaded Python 3Windows ARM64

agentstow-2.0.4-py3-none-win_amd64.whl (777.6 kB view details)

Uploaded Python 3Windows x86-64

agentstow-2.0.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (812.1 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agentstow-2.0.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (748.5 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agentstow-2.0.4-py3-none-macosx_11_0_arm64.whl (731.0 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

agentstow-2.0.4-py3-none-macosx_10_12_x86_64.whl (786.8 kB view details)

Uploaded Python 3macOS 10.12+ x86-64

agentstow-2.0.4-py3-none-any.whl (4.7 kB view details)

Uploaded Python 3

File details

Details for the file agentstow-2.0.4-py3-none-win_arm64.whl.

File metadata

  • Download URL: agentstow-2.0.4-py3-none-win_arm64.whl
  • Upload date:
  • Size: 709.3 kB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for agentstow-2.0.4-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 f3ed1e8fafae9380e1c03575c91d1272b4ec35020409f9d82df7c9610c4b7a13
MD5 e219dce86067c68ca3cda7a5210029df
BLAKE2b-256 640345ea30f0e321acf101dd8e33dc9f1704becf190c341d3239536003a1368e

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-win_arm64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-win_amd64.whl.

File metadata

  • Download URL: agentstow-2.0.4-py3-none-win_amd64.whl
  • Upload date:
  • Size: 777.6 kB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for agentstow-2.0.4-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 7829118a75f1abfedb733c76467f69e6cd056fe66b0c5c9309d35ff73aa7c088
MD5 5aaa32128a638ff61dda811bd2ac2166
BLAKE2b-256 bd2efe0a92c407eb229302d02f915c97481ac711fa51d0e24ebf536e70b4ea5b

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-win_amd64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b0ee0708bff6a34c01dd1ddd288849c599bb8a74ed8744dba8cfba44cef8de99
MD5 91d4a1d6d51c5ce9189447d9731a163c
BLAKE2b-256 12345c7cb30961876de2b5b0e41b017fe9e69f082cdb90e51296f81d3671b52c

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 5f5e72b06793fb7aa69f2b321a60394306830084cebcb5c7504dc0f81be9359c
MD5 3da7811c9108bb138460eafd23aa647a
BLAKE2b-256 667640c0389d028c6fb861b2695b5a09b8607a69c918b236520d1d9165612828

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.4-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 46d9b5a7723fc3ba8e9a350750eddb758fe539b1faf1b5006ccb2978c941ef5e
MD5 0d3d8e25c22f5f3914339d84fff83f2e
BLAKE2b-256 d6a598498fb4e78b5e7a24ca4f551e17ee0d9e6be7be3ea3511383b8309b8ba2

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.4-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f89ce543a54dafb195027d81d5ce7ad88cd51d0de4f3c7a0d9f1d5791462e21f
MD5 dfc197103f24cb53f8db7caea9f48a6b
BLAKE2b-256 c93365712a328af2fef977b7ada59808c0a59a71b3072bac1f49f5726360d094

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file agentstow-2.0.4-py3-none-any.whl.

File metadata

  • Download URL: agentstow-2.0.4-py3-none-any.whl
  • Upload date:
  • Size: 4.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for agentstow-2.0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 17dc6eea7ff3037c5267981ec82ede26f559b81247456549ba3394bc7b01788d
MD5 b7304e5ad8d2afa2f9e119def1b3bc5f
BLAKE2b-256 a9ab6aece220f259e74b3a922e01c342bab090619de4c6ca4f2b78227592f96b

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.4-py3-none-any.whl:

Publisher: release.yml on agentstow/agentstow

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page