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:
Latest release

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.5-py3-none-win_arm64.whl (709.8 kB view details)

Uploaded Python 3Windows ARM64

agentstow-2.0.5-py3-none-win_amd64.whl (777.8 kB view details)

Uploaded Python 3Windows x86-64

agentstow-2.0.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (812.3 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

agentstow-2.0.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (747.3 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agentstow-2.0.5-py3-none-macosx_11_0_arm64.whl (733.0 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

agentstow-2.0.5-py3-none-macosx_10_12_x86_64.whl (788.7 kB view details)

Uploaded Python 3macOS 10.12+ x86-64

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

Uploaded Python 3

File details

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

File metadata

  • Download URL: agentstow-2.0.5-py3-none-win_arm64.whl
  • Upload date:
  • Size: 709.8 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.5-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 c64d72041623bce38f7f0b3f0864f635cce7ed0ad4aacee7fd970577ade73068
MD5 155326f81806fa981e4872fcd1ae7e4c
BLAKE2b-256 63f4cd1421a05e2df44d2bbaa0f9ce729c6b65d60442bfed0aaa1777a6b0e216

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-win_amd64.whl.

File metadata

  • Download URL: agentstow-2.0.5-py3-none-win_amd64.whl
  • Upload date:
  • Size: 777.8 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.5-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 491b28e21531e9e022fe911c21fce7bae09b900510520a93c8cb378bf6c345c4
MD5 22ec61e4197790d45a3de1be2a1e6970
BLAKE2b-256 66b7ac1ac38c303e935c79a7e137fccbd8878a65632f1fd687ee3fb7c0c8da65

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 336b898d59016d535a8cf216ff92aeabb68be055ebc5d3057fb1cd9f36c7c7be
MD5 0390860ec437cbef857aaa587c98363d
BLAKE2b-256 22b87c84e967984c602ac686d2873b4f82400737ed2701575c94f74b738dd2b1

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 feab55ddddbe3199185aacde978510041496c904b9e647bf56a17a96d740c8b5
MD5 0ff5d9a863eb19388eb4527768523c86
BLAKE2b-256 dc486cc9a0880b06b7d665a18531d2b5867957e67bab71d9db230ca57dfafbbb

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.5-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 44796afe6e8f846db84b6d1519fb4783454fd5c57ea4c0f13a3255a26f73c4b0
MD5 3a0554b1edd5ffc64f19639d3ff5db2b
BLAKE2b-256 63452a1389708a2512a49461d1254cbe43ba758c070992cf27852aab55992802

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for agentstow-2.0.5-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0147dc9a385b0ab7fa84c9531a655d0869f32dfaf6d41f7f690403319bc071e2
MD5 45c9ee0c7d263f5cc4e34dcc5569bb73
BLAKE2b-256 ad707f4c9f145a8e75aadb1cfbb60e7a4dcb66f8723c623a09da574cdd32f7bd

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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.5-py3-none-any.whl.

File metadata

  • Download URL: agentstow-2.0.5-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.5-py3-none-any.whl
Algorithm Hash digest
SHA256 d2449135e05cead5067b04513a49994772d50adc6624649e330bf715471d540b
MD5 52ed149288f3505c1ca44c692b99728a
BLAKE2b-256 d0a6ba1583167639f92dea6dfd7ee4c968440eabb21df75c45fd32561102e49b

See more details on using hashes here.

Provenance

The following attestation bundles were made for agentstow-2.0.5-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