dot-agents

dot-agents

The operational layer for AI coding agents

One CLI to manage configurations and workflow state across Cursor, Claude Code, Codex, GitHub Copilot, and OpenCode.

# Install
brew tap AGOrcha/tap && brew install da

# Set up
da init
da add ~/Github/myproject

# Check status
da status
da doctor

# Refresh after pulling changes
da refresh

The Problems

1. Config Fragmentation

Every AI coding agent has its own config location and format:

Beyond the base instruction file, each agent supports more specific rule files — Cursor's per-rule .mdc files, Claude's nested .claude/rules/*.md, and Copilot's path-scoped .github/instructions/**/*.instructions.md; dot-agents projects all of them from one canonical source. See docs/PLATFORM_DIRS_DOCS.md for the full matrix.

This leads to:

• Duplicated rules across every repository
• No way to share common configurations
• Inconsistent setups between machines

2. Workflow Fragmentation

Autonomous agents already behave like a workflow system — resuming work across sessions, persisting plans, verifying as they go — but each platform scatters this state in its own format and location:

• Context amnesia: 30-40 minutes per session re-explaining what the agent already knew yesterday
• Scattered plans: Plans, tasks, and checkpoints live in different places per platform
• Repeated verification: Agents rediscover what's broken vs. what they just caused
• Lost handoffs: Session continuity depends on the agent reconstructing state from scratch

The Solution

dot-agents solves both problems in layers, both shipping today:

• Config management — one source of truth, distributed automatically
• Workflow management — agents orient, persist, delegate, and propose changes autonomously, backed by a local knowledge graph of structured project memory (da kg)

Layer 1: Config Management (Shipped)

dot-agents creates a single source of truth at ~/.agents/:

~/.agents/
├── config.json              # Projects, settings, feature flags
├── rules/
│   ├── global/              # Applied to ALL projects
│   │   ├── coding-style.mdc
│   │   └── security.mdc
│   └── myproject/           # Project-specific rules
│       └── api-patterns.mdc
├── skills/                  # Reusable agent skills (procedures)
│   ├── global/
│   │   └── deploy/SKILL.md
│   └── myproject/
├── agents/                  # Subagent definitions
│   ├── global/
│   │   └── reviewer/AGENT.md
│   └── myproject/
├── settings/                # Agent-specific settings
│   └── global/
├── hooks/                   # Canonical hook bundles
│   └── global/
└── mcp/                     # MCP server configurations
    └── global/

Then symlinks and hard links distribute configs to your projects automatically:

~/Github/myproject/
├── .cursor/rules/
│   ├── global--coding-style.mdc  → ~/.agents/rules/global/...
│   └── myproject--api-patterns.mdc → ~/.agents/rules/myproject/...
├── CLAUDE.md                     → ~/.agents/rules/global/claude-code.mdc
└── (your code)

Layer 2: Workflow Management (Shipping)

Workflow-state management ships today through da workflow: agents orient at session start, persist checkpoints and verification state as they go, manage canonical plans and tasks, delegate bounded fan-out work, and queue rule/skill/config changes for human review through da review. Orient and related context draw on the local knowledge graph (da kg) — structured project memory and a code graph that let agents resume with what was already learned (see the Knowledge Graph section).

The design principle: agents operate, humans steer. Deeper multi-agent coordination is on the roadmap; see the Roadmap section below.

Installation

Homebrew (recommended)

brew tap AGOrcha/tap
brew install da

Install script

Downloads the prebuilt da binary onto your PATH — no Go toolchain required:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/AGOrcha/dot-agents/master/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/AGOrcha/dot-agents/master/scripts/install.ps1 | iex

Go toolchain (go install)

If you already have Go 1.26.2+, install the CLI straight from source with the Go toolchain (or set GOTOOLCHAIN=auto to let Go fetch the required toolchain automatically):

go install github.com/AGOrcha/dot-agents/cmd/da@latest
# or
go install github.com/AGOrcha/dot-agents/cmd/da@<release-version>

The da binary is placed in $(go env GOBIN) (falling back to $(go env GOPATH)/bin); ensure that directory is on your PATH.

Manual (from source)

Requires Go 1.26.2+ (or set GOTOOLCHAIN=auto).

git clone https://github.com/AGOrcha/dot-agents ~/.dot-agents
cd ~/.dot-agents
go build -ldflags "-s -w" -o ./bin/da ./cmd/da
export PATH="$HOME/.dot-agents/bin:$PATH"

Verify a release (optional)

Releases are signed with Cosign using keyless signing via Sigstore + GitHub OIDC. See docs/RELEASE_VERIFICATION.md for the step-by-step cosign verify-blob recipe.

Quick Start

# 1. Initialize ~/.agents/ with starter skills, agents, hooks, and config
#    (prompts to confirm; pass -y to run non-interactively)
da init

# 2. Add a project
da add ~/Github/myproject

# 3. Check what was linked
da status --audit
da doctor

# 4. Create reusable skills and subagents
da skills new deploy
da agents new reviewer

# 5. Or, inside a repo that already committed .agentsrc.json:
da install

Commands

da exposes 20 top-level commands.

Project Management

Configuration

Skills & Agents

Canonical Resource Inspection

These inspect and manage canonical files under ~/.agents/. Each supports list [scope], show <scope> <name>, and remove <scope> <name>.

Workflow Proposals

Workflow State

da workflow captures repository-local workflow state — canonical plans, checkpoints, verification logs, preferences, fanout artifacts, and bridge queries — so humans and agents can resume work safely.

Plans & Tasks

Persist & Verify

Delegation

Drift (cross-repo, read-only by default)

Knowledge Graph

da kg creates, queries, and maintains the local knowledge graph used for structured project memory, bridge queries, and code-to-note context.

Maintenance

Bridge

Code Graph

Sync

da sync wraps git operations on ~/.agents/.

Utilities

How It Works

Cursor Rules (Hard Links)

Cursor doesn't follow symlinks for .cursor/rules/, so dot-agents uses hard links:

# In your project
.cursor/rules/global--coding-style.mdc  # Hard link to ~/.agents/rules/global/coding-style.mdc

Hard links share the same file content (same inode), so edits in either location are reflected in both.

Claude Code / Codex (Symlinks)

For CLAUDE.md and AGENTS.md, standard symlinks work:

CLAUDE.md  → ~/.agents/rules/global/claude-code.mdc
AGENTS.md  → ~/.agents/rules/global/agents.md

Codex also gets agent definitions (rendered to .codex/agents/*.toml), settings (.codex/config.toml), and hooks (.codex/hooks.json).

Naming Convention

Files in .cursor/rules/ are prefixed to show their source:

• global--*.mdc → From ~/.agents/rules/global/
• {project}--*.mdc → From ~/.agents/rules/{project}/

Syncing Across Machines

Your ~/.agents/ directory is designed to be git-tracked:

# First time setup
da sync init
cd ~/.agents
git remote add origin git@github.com:YOU/agents-config.git
da sync push

# On another machine
git clone git@github.com:YOU/agents-config.git ~/.agents
da add ~/Github/myproject  # Re-link your projects

Supported Agents

Requirements

• macOS or Linux for the CLI via Homebrew, scripts/install.sh, or a local go build.
• Windows: use scripts/install.ps1 for the CLI.
• Go 1.26.2+ — only for go install or building from source. The Homebrew and scripts/install.sh paths ship a prebuilt binary and need no Go toolchain. (Set GOTOOLCHAIN=auto to auto-fetch the toolchain.)
• git (for sync features)

Configuration

config.json

{
  "schema_version": "1.0",
  "projects": {
    "myproject": {
      "path": "/Users/you/Github/myproject",
      "added": "2026-01-10T10:00:00Z"
    }
  },
  "defaults": {
    "link_type": "auto"
  },
  "features": {
    "tasks": false,
    "history": false
  }
}

Skills

Skills are reusable procedure documents that agents can invoke:

# Create a new skill
da skills new deploy

# List all skills
da skills list

# Promote a repo-local skill into ~/.agents/
da skills promote deploy

Skills live in ~/.agents/skills/global/ with this structure:

• SKILL.md - The skill definition with frontmatter
• scripts/ - Optional helper scripts
• references/ - Optional additional context

Subagents

Subagents are directory-based agent definitions:

# Create a new subagent
da agents new reviewer

# List all subagents
da agents list

# Promote a repo-local subagent into ~/.agents/
da agents promote reviewer

Each subagent is a directory containing:

• AGENT.md - Required agent definition with frontmatter (name, description, model)
• scripts/ - Optional helper scripts
• references/ - Optional additional context documents

Hooks

Inspect canonical hook bundles stored in ~/.agents/hooks/:

# List all hooks
da hooks list

# Inspect one hook bundle
da hooks show global session-orient

Project Manifests (.agentsrc.json)

Commit a .agentsrc.json to your repo so any contributor can set up agent configs from the repo itself:

# Generate manifest from current ~/.agents/ state
da install --generate

# Set up a cloned repo from its manifest
da install

Importing Existing Configs

Already have agent configs scattered across your projects? Import them into ~/.agents/:

da import myproject

This detects existing rules, skills, agents, and hooks in the project and copies them into the central ~/.agents/ directory.

Knowledge Graph

The knowledge graph (da kg) is a local store of structured project memory: durable notes about decisions, entities, concepts, and sessions, plus a code graph and the cross-references between them. It backs the workflow orient context an agent loads at session start, so the agent resumes with what was already learned instead of rediscovering it.

Notes carry a type — source, entity, concept, synthesis, decision, repo, or session — and live as hot Markdown files that are synced into a warm SQLite layer for fast querying. Raw material (Markdown, text, PDFs, URLs, transcripts) is brought in through an inbox and turned into typed notes:

# One-time: initialize the graph at KG_HOME
da kg setup

# Ingest a source (or --all to drain the inbox), then sync to the warm layer
da kg ingest notes.md
da kg warm

# Query by intent (decision_lookup, repo_context, related_notes, ...)
da kg query --intent decision_lookup "why postgres backend"

# Health and integrity
da kg health
da kg lint

A code graph is built from the repo with da kg build (incremental updates via da kg update). It powers impact analysis — da kg impact shows the blast radius of changed files, and da kg changes detects change impact in the current diff. Notes can be tied to specific code symbols so context follows the code:

# Build the code graph, then cross-reference a note to a symbol
da kg build
da kg link add <note-id> <qualified-name>
da kg link list <note-id>

Maintenance keeps the graph honest: da kg maintain reweave repairs broken links, mark-stale flags notes past a freshness threshold, and compact archives superseded notes. da kg sync pulls and lints the graph (add --push to publish), and da kg serve exposes the graph to agents over MCP. See the Knowledge Graph command table above for the full surface.

Roadmap

Agent-as-Operator

The next major evolution: agents run da autonomously instead of humans operating it manually. The agent manages config, skills, rules, and workflow state — surfacing only decisions that require human judgment.

Changes follow an approval gradient:

• Auto-apply: Checkpoints, verification results, plan progress, lessons after corrections
• Propose-and-apply: New rules, skills, workflow config changes — human confirms
• Escalate: Conflicting rules, stale config affecting production, cross-repo drift

Workflow State

Based on analysis of real session data across Claude Code, Cursor, and Codex, dot-agents manages six workflow concerns. The foundation ships today via da workflow; remaining work deepens coverage:

1. Resume context — collect active plan, last handoff, and likely next step (shipped: workflow orient, next)
2. Plan & task state — canonical plan artifacts with dependency-aware phases (shipped: workflow plan, task, advance)
3. Verification state — persist test/lint/build results so agents stop rediscovering what's broken (shipped: workflow verify, checkpoint)
4. Approvals & tool health — surface auth expiry, rate-limit risk, environment readiness (roadmap)
5. Repo preferences — persist per-repo habits like test commands and review preferences (shipped: workflow prefs)
6. Delegation & handoff — bounded fan-out with ownership constraints and merge-back summaries (shipped: workflow fanout, merge-back)

Multi-Agent Coordination

Drawing from supervisor and swarm-orchestration patterns, dot-agents will support:

• Context engineering: Front-load subagents with structured context bundles so they don't waste tokens rediscovering state
• Structured coordination: Intent marker protocols to prevent infinite loops and drift between cooperating agents
• Bounded fan-out: Spawn workers with clear ownership constraints, collect results into parent continuation artifacts

FAQ

Q: Why hard links for Cursor?

Cursor's rule system doesn't follow symlinks. Hard links share the actual file content, so changes sync automatically.

Q: Can I use this with existing projects?

Yes! da add won't overwrite existing files unless you use --force.

Q: Is my config private?

Yes. Everything stays in ~/.agents/ on your machine. Git sync is optional and to your own repo.

Q: What if I don't use all the agents?

That's fine! dot-agents only creates config files for agents it detects or that you have rules for.

Q: What is da refresh for?

After pulling changes to ~/.agents/ from git, run refresh to re-apply links and configs to all your projects. This ensures your projects stay in sync with your central config.

Q: How do skills differ from rules?

• Rules (.mdc files) are always-active guidelines applied to all projects
• Skills (SKILL.md files) are on-demand procedures that agents invoke when needed, like deployment checklists or code review workflows

Q: Can I sync my config across machines?

Yes! da sync helps you manage ~/.agents/ as a git repository. Clone it on another machine and run da refresh to set up all your projects.

Contributing

Contributions welcome! Please open an issue or pull request on GitHub.

License

MIT

Built for developers who use AI coding agents daily. Designed so agents can operate themselves.