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 — and a set of composable primitives (dynamic loops, bounded workflows, agent teams) you assemble into your own agentic orchestration, not a closed set of commands.

# 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 rests on three pillars, all shipping today:

• Config management — one source of truth at ~/.agents/, distributed automatically; layered manifests extends shared bases and pin resolved layers in .agentsrc.lock (see Layered config & the lockfile)
• Workflow management — composable primitives (dynamic loops, bounded workflows, and agent teams) you assemble into your own orchestration; agents orient, persist, verify, delegate, and propose changes autonomously through da workflow and da review
• Knowledge graph (da kg) — a local store of structured project memory plus a code graph and the cross-references between them, so agents resume with what was already learned instead of rediscovering it (see the Knowledge Graph section)

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)

A repo's .agentsrc.json manifest can also extends shared config layers sourced from git, local paths, HTTP, or OCI; the resolved layer SHAs pin in .agentsrc.lock so every machine projects the same effective config. This layered model ships today — see Layered config & the lockfile.

Layer 2: Workflow Management (Shipped)

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 knowledge graph (da kg) described below, so agents resume with what was already learned (see the Knowledge Graph section).

The design principle: agents operate, humans steer.

These are primitives, not a fixed toolset. dot-agents does not hand you one hard-coded loop — it gives you composable pieces to assemble your own agentic orchestration: dynamic loops, bounded workflows, and agent teams. Per app_type, an execution profile declares the executor : verifier : reviewer topology, an ordered verifier sequence, and a review-lens set with concurrency — resolve any of it with da config relevance. da workflow fanout spawns workers under explicit write scopes, da workflow bundle expands a delegation into its ordered impl → verifier(s) → review stages, a precondition gate enforces verification before a task can advance, and da workflow merge-back folds results back into the parent. The orchestration skills (loop-worker, orchestrator-session-start, isp, delegation-lifecycle) drive these primitives end to end. The CLI resolves, gates, and records the topology; the verifier and review steps themselves are run by the agents/skills you compose on top — so you build the bounded workflow and agent team that your project actually needs.

Deeper multi-agent coordination is on the roadmap; see the Roadmap section below.

Layer 3: Knowledge Graph (Shipped, and evolving)

The third pillar, da kg, is a local store of structured project memory — typed notes about decisions, entities, and sessions — plus a code graph and the cross-references between them. It backs the workflow orient context an agent loads at session start. See the Knowledge Graph section for the full surface.

Shipped today: typed notes, a hot-filesystem + warm-SQLite store (Postgres backend included), a code graph via the code-review-graph bridge (kg build/update/impact), bridge queries by intent, and note→symbol cross-references.

Where it's heading (in progress, not yet shipped): dot-agents is evolving the KG from a fixed code-graph into a dynamic, evolvable knowledge substrate — one graph store fronted by pluggable backend adapters so you define your own ontology of entities and relationships, query it through a declarative query layer that auto-queries across the available scopes, and derive your own operational views tailored to your app_type and how your workflow actually needs them (the longer-term direction adds typed cognitive memory views — working / operational / semantic / episodic — over that single store). Today only a built-in none-adapter seam plus the design specs exist; this is the trajectory being built, distinct from the shipped code graph above. See the graph backend adapter contract and knowledge-graph spec.

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 22 top-level commands (excluding help and completion).

Project Management

Configuration

Layered config & the lockfile (.agentsrc.lock)

A .agentsrc.json manifest may extends one or more config layers sourced from git, local paths, or HTTP (OCI is not valid for extends), declared as source:path@version. When the layers are resolved, the resolved layer SHAs are pinned in .agentsrc.lock so every machine projects the same effective config.

See the Layered Configuration guide for the full model — the manifest, extends layers, resolution and precedence, the lockfile, and a worked walkthrough of da config sync / explain / lint.

• da config sync re-checks every declared layer upstream (ignoring TTL), re-resolves the stack, and rewrites the units section of .agentsrc.lock. This is the explicit upstream re-check — the uv --upgrade analog.
• da refresh and da install re-project the locked config locally and only re-resolve when the lock is stale, so routine relinking never reaches the network for an unchanged stack.

Skills & Agents

Canonical Resource Inspection

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

See the Managing rules, MCP & settings guide for the canonical model, per-platform emit, and the list/show/remove surface (hooks have their own Hooks guide).

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)

Automation / internal commands

These are driven by skills and lifecycle hooks (e.g. iteration-close, loop-worker), not run by hand. They are listed for completeness; reach for the end-user commands above for day-to-day work.

A task may also carry the parameterized status blocked-on:<ref> (set via workflow advance --status blocked-on:<ref>); it is a task state, not a standalone command, and frees its parallelism slot in the workflow slots ledger until the blocker auto-resolves.

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

da install is EXACT by default: the platform link pass prunes managed shared-target links that are no longer in the resolved set, so the tree converges to exactly what the lock declares. Pass --inexact to keep the additive behavior and leave stale managed links in place, or --strict to fail if any declared resource is missing. da refresh follows the same EXACT/prune-by-default convention with the same --inexact opt-out.

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

The foundation ships today: bounded fan-out (workflow fanout) spawns workers with explicit write scopes, structured context bundles (workflow bundle) front-load them so they don't rediscover state, and merge-back (workflow merge-back) collects results into parent continuation artifacts. Drawing from supervisor and swarm-orchestration patterns, the roadmap deepens this with:

• Richer coordination protocols: intent-marker conventions that prevent infinite loops and drift between cooperating agents
• Adaptive context engineering: tune each subagent's bundle from graph impact analysis instead of fixed scopes
• Cross-agent scheduling: coordinate multiple concurrent workers against a shared plan with conflict detection

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. refresh is EXACT by default — it prunes managed shared-target links that are no longer in the resolved set; pass --inexact to keep the additive behavior and leave stale managed links in place.

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

Apache License 2.0 — see also NOTICE.

Contributions are accepted under the Apache 2.0 terms (§5): unless you state otherwise, anything you intentionally submit for inclusion is licensed under Apache 2.0, with its patent grant.

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