OPEN SOURCE

UNIFIED
CONFIG
LAYER

Local command center for AI coding agents. Configs, tasks, and logs all in ~/.agents/, powered by dot-agents.

$ brew install dot-agents/tap/dot-agents

SETUP2min

MITLICENSE

~/.AGENTS

SUPPORTSCURSORCLAUDE CODECODEXOPENCODE+ more

THE PROBLEM

CONFIG CHAOS

Inconsistent file standards

Every agent platform has different config conventions.

→ Different names, structures, locations

→ Duplicative config logic across tools

→ Files get scattered and forgotten

CLAUDE CODE

CLAUDE.md

CURSOR IDE

.cursor/rules/*.mdc

CURSOR CLI

~/.cursor/cli-config.json

CURSOR (LEGACY)

.cursorrules

CODEX

AGENTS.md

OPENCODE

opencode.json

COPILOT

.github/copilot-instructions.md

WINDSURF

.windsurfrules

AIDER

.aider.conf.yml

CONTINUE

.continue/config.yaml

ZED AI

.zed/settings.json

CODY

.sourcegraph/cody.json

Multiplied across every repo

Maintaining configs across projects becomes a nightmare.

→ Copy-paste the same rules everywhere

→ Configs drift out of sync

→ No visibility into what rules are applied where

→ Easily lost when switching machines

~/projects/webapp/

.cursor/rulesCLAUDE.md

duplicate!

~/projects/api/

.cursor/rulesAGENTS.md

outdated?

~/work/client/

CLAUDE.md.cursor/rules

which version?

~/side-project/

.cursor/rulesCLAUDE.md

out of sync

4 repos × 3 tools = 12+ files

2+ HOURS/ WEEK WASTED

Agent tools are constantly evolving.
Experimenting with new tools shouldn't mean drowning in config files.

THE SOLUTION

ONE HOME
ONE CLI

Everything in ~/.agents/. Configs, tasks, activity logs. Write once, apply everywhere.

~/.agents

~/.agents/

config.jsonGlobal settings & project registry

rules/Coding standards & preferences

global/All projects, all agents

rules.mdcAll agentsUniversal rules → ALL agents

cursor.mdcCursor onlyCursor-only rules

claude-code.mdcClaude onlyClaude Code-only rules

{project}/Project-specific overrides

rules.mdcAll agentsProject rules → ALL agents

skills/Directory-based slash commands

global/Shared across all projects

commit/Skill directory

SKILL.md/commit → Generate commit messages

review/Skill directory

SKILL.md/review → Code review assistant

settings/Agent settings & hooks

global/Shared settings

claude-code.jsonHooks configuration

local/Machine-specific (gitignored)

terminal — dot-agents

$ dot-agents init

✓ Initialized ~/.agents/

✓ Ready! Run $ dot-agents add <project> to setup configs.

$ dot-agents status

[INFO] Home: ~/.agents/

Projects (3):

[OK] my-app

[OK] api-server

[OK] docs

← rules.mdc

All agents

---
alwaysApply: true
---

# Global Coding Standards

- Use TypeScript strict mode
- Prefer functional patterns
- Write comprehensive tests
- Follow existing conventions

HOW IT WORKS

HIERARCHICAL
BY DESIGN

Rules cascade from global to project, from all-agents to agent-specific. You control exactly what applies where.

LAYER 1

GLOBAL RULES

Apply to all projects. Your universal coding standards.

~/.agents/rules/global/

├── rules.mdc ← all agents

├── cursor.mdc ← cursor only

└── claude-code.mdc ← claude only

LAYER 2

PROJECT OVERRIDES

Override or extend globals for specific projects.

~/.agents/rules/my-app/

├── rules.mdc ← all agents

└── cursor.mdc ← cursor only

Global

→

Project

→

✓

Final

KEY CAPABILITIES

UNIFIED RULES

Define once, apply everywhere. Symlinks + hardlinks distribute configs to each agent's expected location.

FULL PLATFORM SUPPORT

Rules, commands, hooks, MCPs—all configs for each supported platform. When we support an agent, we support all its config types.

AUTO-MIGRATION

NEW

Backwards compatible + forward-looking. When agent platforms change config formats, we track the changelog and help you migrate automatically.

CONFIG AUDIT

Run dot-agents audit to see exactly which rules apply to any project + agent combination.

100% LOCAL DEFAULT

No cloud, no accounts. ~/.agents/ is set up for personal git tracking. Portable to other machines via SSH, git push, or however you sync.

CLI COMMANDS

SIMPLE.
POWERFUL.

Manage configs, tasks, and agent activity. No complex setup required.

CORE COMMANDS

$ dot-agents init

Initialize ~/.agents/ with starter structure and default skills.

$ dot-agents add ~/Github/my-app

Add a project. Creates symlinks from your repo to ~/.agents/ configs.

$ dot-agents remove my-app

Remove a project from dot-agents management.

$ dot-agents status

Show all registered projects and their health status.

$ dot-agents doctor

Diagnose issues: broken symlinks, missing configs, legacy formats.

$ dot-agents audit

See exactly which rules apply to current project + agent combination.

$ dot-agents skills

Manage skills (list, new, edit). Directory-based slash commands for agents.

$ dot-agents hooks

Manage Claude Code hooks configuration.

NEW IN V1

NEW

$ dot-agents sync

Git sync utilities for ~/.agents/. Push/pull configs across machines.

NEW

$ dot-agents context

Output all configs as JSON for agent consumption.

NEW

$ dot-agents explain

Self-documenting descriptions of the system architecture.

COMING POST-LAUNCH

TASKS. HISTORY.

Track work across sessions. See what agents did and when.

$ dot-agents tasks

Track tasks across projects. Local-first task management.

$ dot-agents history

View recent agent activity. See what agents did and when.

$ dot-agents snapshot

Save current config state. Version your settings.

$ dot-agents restore <name>

Roll back to a previous configuration state.

GITHUB/LINEAR SYNCEXPERIMENT MODECOST TRACKING

Comparison

How does it compare?

See how dot-agents stacks up against alternatives

Feature	dot-agents	AGENTS.md	DIY Symlinks	Tool-Specific
Config location	Unified ~/.agents/	Single file per repo	Scattered	Each tool's location
Cross-tool support	All agents	All (convention)	Manual setup	One tool only
Sync mechanism	Symlinks + hardlinks	Copy/paste	Manual links	None
Hierarchy	Global → Agent → Project	Flat	Custom	Flat
Task tracking	Built-in	No	No	Some tools
Setup time	1 command	N/A	Hours	Per tool
Maintenance	Zero drift	Manual sync	Manual	Per tool
Team support	Coming v2	No	No	Varies

SYNC ACROSS MACHINES

GIT-TRACKABLE

Your ~/.agents/ directory is just files. Track it with git, sync across machines naturally.

TRACK ON PRIVATE REPO

Version control your configs

Initialize git

cd ~/.agents
git init

Add your private remote

git remote add origin \
  git@github.com:you/configs.git

Commit and push

git add .
git commit -m "init"
git push -u origin main

Or use dot-agents sync init for guided setup

CLONE TO NEW MACHINE

SSH, remote server, new laptop

Clone your configs

git clone \
  git@github.com:you/configs.git \
  ~/.agents

Verify and setup symlinks

dot-agents doctor

doctor will:

- Detect new machine, setup state
- Flag any absolute paths needing update
- Recreate symlinks to your projects

Machine-specific paths? Use ~/.agents/local/ (gitignored) for overrides.

FAQ

Frequently Asked Questions

A universal config system that unifies all your AI coding agents into a single ~/.agents/ directory. Edit once, reflect everywhere via symlinks.

Yes, open source and free forever. No accounts, no cloud, no vendor lock-in.

dot-agents still helps with organization. When you try another tool, you're ready. Plus, the hierarchical rules (global → project) work great even with one tool.

AGENTS.md is a single file convention. dot-agents is a directory structure with automation—hierarchy, symlinks, cross-repo unification, task tracking. Think of it as "AGENTS.md v2."

Those are general dotfile managers. dot-agents is purpose-built for AI agents—task tracking, handoffs, hierarchical rules, agent-specific directories.

v1 launches with support for Cursor, Claude Code, Codex, and OpenCode. More agent platforms (like Aider) coming soon based on community feedback.

Minimal change. Run one install command, and your existing configs get unified. Start simple (rules only), expand as needed.

v1 is solo-focused. Team features (shared configs, permissions) coming in v2.

GET STARTED

START NOW

One command to install. One home for all your agent configs. Enable tasks and history when you need them.