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

Uploaded Python 3Windows ARM64

agentstow-2.0.3-py3-none-win_amd64.whl (777.5 kB view details)

Uploaded Python 3Windows x86-64

agentstow-2.0.3-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.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (749.0 kB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

agentstow-2.0.3-py3-none-macosx_11_0_arm64.whl (731.3 kB view details)

Uploaded Python 3macOS 11.0+ ARM64

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

Uploaded Python 3macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: agentstow-2.0.3-py3-none-win_arm64.whl
  • Upload date:
  • Size: 709.2 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.3-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 908d592a11dd1076bad8863e973a8b7e52699ce4727de788b8f73df932fa7b4b
MD5 e6c84098beb1a9e52326b41f17155c13
BLAKE2b-256 feaa686d9153325691d48e6d0ca7c478578eddd713c3b3cf0e20890744ef4df5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: agentstow-2.0.3-py3-none-win_amd64.whl
  • Upload date:
  • Size: 777.5 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.3-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 7ab27c767aed799ae656ba1f4f075f25500734d26609b75f24a730dd712e506d
MD5 a443bd97fcf10a6c94385c95f9a41bbf
BLAKE2b-256 8524e7001d387207c41c8c856cef9b21a11a0ad37a1d6ec6a42b3c9baeb09b21

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agentstow-2.0.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 456b4e9cf33f614e15b34cb159f9c32501a40c0c37b4d96fd19d93c2d14d1d8e
MD5 9c4fc7d3e5b62b0389d27caabbad3a1b
BLAKE2b-256 3c5240573417079a65aab579b4baff63fe38feb06333a5da12ce120f8e329d9d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agentstow-2.0.3-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 cdc1ed1cb302ce5d077158a6ca3cb28437aa8a11395cf46bc289f5e7663184d0
MD5 5d531240bfbd9fc8119988b440457bbb
BLAKE2b-256 54e87be8bf548a8774dfba2854848d56a8645a77465a528bdd98f6462114f1d5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agentstow-2.0.3-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ef02edf8a5f16df42bd2a83e279d568880fc33ddf5f87ed7a265e7cd097493d7
MD5 80c23f99ec2dbae3e818b913b7e29ec6
BLAKE2b-256 180f08509ba1e3c04a5247c66a1c7dd245a655adae5d1903befe2fe2161d6dde

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for agentstow-2.0.3-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 47979d96726fc9ffb3562d7aa3f27af174a211fbf0fba760f13ae7b5588f160e
MD5 be4937e7c0e0157c3dad974f55d65b24
BLAKE2b-256 a7073cd7c01c6fe16e70a5acf9ce2d9bcc87d16702c747aa08064ae93a21b48c

See more details on using hashes here.

Provenance

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

Supported by

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