dot-agents

dot-agents

The operational layer for AI coding agents

One CLI (da) to manage configuration and workflow state across Cursor, Claude Code, Codex, GitHub Copilot, and OpenCode — plus a set of composable primitives (dynamic loops, bounded workflows, agent teams) you assemble into your own agentic orchestration, not a closed set of commands.

• New here? Paste the one block below into your agent — it installs da, onboards you, and tailors a setup to your project.
• Want the hands-on quickstart? → Getting Started
• Want the whole command surface? → Command reference
• New to the model? → AI development lifecycle

Fastest start (one paste)

You don't have to read the whole site first. Paste this into your AI coding agent (Claude Code, Cursor, Codex, Copilot, OpenCode, Antigravity, …). It installs da, runs the guided onboarding, and tailors a setup to your project — asking you questions instead of making you read docs.

Set me up with dot-agents (da). Do this in order, and ask before any destructive change:

1. Install the binary: run `brew tap AGOrcha/tap && brew install da` (or, if Homebrew
   isn't available, the Go / install-script method from
   https://github.com/AGOrcha/dot-agents#installation). Confirm with `da --version`.

2. Run the dot-agents `onboard` skill (skill://onboard). Detect my setup path
   — from-home (a shared/team ~/.agents git URL), from-manifest (this repo already
   commits a real .agentsrc.json), or fresh (empty home) — run exactly that path,
   link my active editor with `da refresh`, then verify with `da status --audit`
   and `da doctor`. If the path is ambiguous, ask me the single disambiguating question.

3. Analyze this project and ask me: what am I building, my stack / app_type, my
   editor/harness, and how much automation I want. Then tailor:
   - use the `pipeline-architect` skill to design my execution_profile
     (app_type → verifier/reviewer sequence + topology + review lenses),
   - use the `skill-architect` skill for any repeatable workflow I describe,
   - create bounded subagents for my recurring delegated tasks.

4. Teach me the da primitives I'll actually use, grounded in what you just set up:
   `da workflow orient | checkpoint | verify | advance`, `da workflow fanout` +
   merge-back for bounded delegation, `da review` for proposals, and `da kg` for
   project memory. For each, tell me WHEN to reach for it in my loop.

Keep it to the minimum decisions. Prefer the conservative/standard option and tell me
what you chose.

Full walkthrough and what each step does: Install & onboard.

Prefer to drive it yourself?

brew tap AGOrcha/tap && brew install da   # or: go install …  (see Install below)
da --version
da init                                   # scaffold ~/.agents/
da add ~/Github/myproject                 # register + link a project
da refresh                                # project canonical config into each platform's shape
da status --audit && da doctor            # verify

The Getting Started guide covers the three setup paths in full — adopt a shared home config, install a repo manifest, or start fresh — then the shared verify step.

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 --proto "=https" --tlsv1.2 -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)

With Go 1.26.2+ (or GOTOOLCHAIN=auto to auto-fetch the toolchain):

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

The da binary lands 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 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"

Releases are signed with Cosign (keyless, via Sigstore + GitHub OIDC) — see docs/RELEASE_VERIFICATION.md for the cosign verify-blob recipe.

Why dot-agents

Every AI coding agent scatters its own state in its own place — and so does the work those agents do.

• Config fragmentation. Each agent has its own instruction/rule files and format (.cursor/rules/*.mdc, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, …), so rules get duplicated per repo, can't be shared, and drift between machines.
• Workflow fragmentation. Autonomous agents already behave like a workflow system — resuming across sessions, persisting plans, verifying as they go — but each platform stores that state differently. The cost: context amnesia at every session start, scattered plans, repeated rediscovery of what's broken, and lost handoffs.

dot-agents answers both with one source of truth and one operational surface.

The three pillars (all shipping today)

1. Config management — a single source of truth at ~/.agents/, distributed to each project via symlinks/hard links in the shape each platform expects. A repo's .agentsrc.json can extends shared layers (git / local / HTTP / OCI); resolved layer SHAs pin in .agentsrc.lock so every machine projects the same effective config. → Layered Configuration · Config model · Platform projection · Platform matrix

2. Workflow management — composable primitives, not a fixed toolset. Agents orient at session start, persist checkpoints/verification, manage canonical plans and tasks, delegate bounded fan-out with write-scope constraints and merge-back, and queue changes for human review (da review). Per app_type, an execution profile declares the executor : verifier : reviewer topology, an ordered verifier sequence, and a review-lens set — the CLI resolves, gates, and records the topology while the steps run in the agents/skills you compose on top. Agents operate, humans steer. → Workflow client commands · Workflow artifact model · Verification & scoring · Diagrams

3. Knowledge graph (da kg) — a local store of structured project memory (typed notes about decisions, entities, sessions) plus a code graph and the cross-references between them. It backs the workflow orient context an agent loads at session start, so it resumes with what was already learned. Shipped: a hot-filesystem + warm-SQLite store (Postgres backend included), a code graph via the code-review-graph bridge, bridge queries by intent, note→symbol links. The KG is evolving toward a pluggable-backend, custom-ontology substrate — see the graph backend adapter contract and the scoped knowledge-graphs spec.

A read-only Observability dashboard surfaces workflow runs, iteration scores, and rubric detail with live updates.

Command surface

da exposes 26 top-level commands. The full command reference documents every family and subcommand; the map below is the entry point, and each row links to the guide for that area. Run da <command> --help for the authoritative flag set, and see the Global Flag Contract for how --json / --dry-run / --yes / --force / --verbose behave per command.

How it works

Canonical config lives once under ~/.agents/; da projects it into each project in the exact shape that platform reads:

• Cursor doesn't follow symlinks for .cursor/rules/, so dot-agents uses hard links (global--coding-style.mdc → ~/.agents/rules/global/…). The global--* / {project}--* prefix shows each file's source.
• Claude Code links project rules as symlinks under .claude/rules/ (one per canonical rule); global rules load once from the user-scope ~/.claude/CLAUDE.md. Codex links a project-root AGENTS.md (the global rule by default, a project-scoped override when one exists) plus rendered .codex/ agents/settings/hooks. Copilot manages .github/copilot-instructions.md (+ .github/agents/*.agent.md); OpenCode gets AGENTS.md + .opencode/agent/*.md. Each platform also gets its rendered agent/settings/hook/MCP files.

The full per-platform matrix (files, formats, link types) lives in docs/PLATFORM_DIRS_DOCS.md; the model behind it is Platform projection.

Supported agents

Requirements

• macOS or Linux for the CLI via Homebrew, scripts/install.sh, or a local go build.
• Windows: use scripts/install.ps1.
• Go 1.26.2+ — only for go install or building from source (Homebrew and the install script ship a prebuilt binary; set GOTOOLCHAIN=auto to auto-fetch).
• git — for sync features and git-sourced config layers.

Documentation

• Start here: Getting Started · Install & onboard · AI development lifecycle
• Reference: Command reference · Global flag contract · Platform matrix
• Config: Layered configuration · Config model · Resource management · Hooks
• Workflow: Workflow client commands · Workflow artifact model · Verification & scoring · Scoring guide · Diagrams
• Advanced: Config relevance · Eval harness · Observability dashboard · Release verification · Architecture decision records

Syncing across machines

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

da sync init && cd ~/.agents
git remote add origin git@github.com:YOU/agents-config.git
da sync push
# On another machine:
da init --from git@github.com:YOU/agents-config.git   # adopt the shared home
da add ~/Github/myproject                             # rebind each project

Roadmap

The foundation ships today; remaining work deepens it.

• Agent-as-operator — agents run da autonomously along an approval gradient: auto-apply (checkpoints, verification, plan progress, lessons), propose-and-apply (new rules/skills/config — human confirms), escalate (conflicting rules, stale prod config, cross-repo drift).
• Workflow depth — the six workflow concerns are partly shipped (orient/next, plans/tasks, verify/checkpoint, prefs, fanout/merge-back); approvals & tool-health surfacing remain on the roadmap.
• Multi-agent coordination — building on bounded fan-out, context bundles, and merge-back: richer anti-drift coordination protocols, graph-driven adaptive context engineering, and cross-agent scheduling with conflict detection.
• Transitive config scope — the home config is v2 today (portable repo_id registry + machine-local bindings.json). The roadmap wires transitive org→team→repo config layering and a --scope selector into the resource commands (rules / mcp / settings / skills / agents), which today scope by global + project name only.
• Evolvable knowledge graph — moving the KG from a fixed code-graph to a pluggable-backend, custom-ontology substrate with cross-scope querying and typed cognitive-memory views (see the Knowledge graph pillar above).
• Plugins — plugin bundles install today and project to OpenCode (.opencode/plugins/); the roadmap broadens platform emitters (Cursor / Claude / Codex / Copilot plugin dirs) and adds a da plugins marketplace generator. See the Plugin Contract.

FAQ

Why hard links for Cursor? Cursor's rule system doesn't follow symlinks; hard links share the actual file content, so edits sync automatically.

Can I use this with existing projects? Yes — da add won't overwrite existing files unless you pass --force.

Is my config private? Yes. Everything stays in ~/.agents/ on your machine; git sync is optional and to your own repo.

What's da refresh for? After pulling ~/.agents/ changes, refresh re-applies links to all projects. It's EXACT by default (prunes managed links no longer in the resolved set); pass --inexact to keep additive behavior.

Skills vs rules? Rules (.mdc) are always-active guidelines; skills (SKILL.md) are on-demand procedures agents invoke when needed.

Contributing

Contributions welcome — 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.