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
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.
| Step | What happens | Backed by |
|---|---|---|
| 1. Install | Gets the da binary onto your machine | Homebrew / Go / script |
| 2. Onboard | Detects your path, scaffolds ~/.agents, links your editor, health-checks | onboard skill (from-home / from-manifest / fresh → verify) |
| 3. Tailor | Designs your execution profile, skills, and subagents around your stack | pipeline-architect, skill-architect |
| 4. Teach | Shows the primitives + when to use each, in context | da workflow / da review / da kg |
Full walkthrough and what each step does: Install & onboard.
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 projectcd~/Github/myproject && da refresh # project canonical config into each platform's shape
da status --audit && da doctor # verifyThe 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.
brew tap AGOrcha/tap && brew install daThe cask generates bash, zsh, fish, and PowerShell completions from the
installed da binary at install time (da completion <shell>).
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 | iexWith 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.
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.
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.
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.jsoncanextendsshared layers (git / local / HTTP / OCI); resolved layer SHAs pin in.agentsrc.lockso every machine projects the same effective config. → Layered Configuration · Config model · Platform projection · Platform matrixWorkflow 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). Perapp_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 · DiagramsKnowledge 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 theworkflow orientcontext 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.
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.
| Family | For | Deep dive |
|---|---|---|
initaddremoverefreshimportinstallstatusdoctor | Set up ~/.agents/ and link projects | Getting Started |
worktree (createmerge-back) | Managed sub-branch worktrees for isolated / parallel work | Command reference |
config (explainsynclintverifyrelevance) | Inspect/resolve effective config + layers | Layered config, relevance |
skillsagents | Author + promote reusable skills and subagents | Skill↔command integration |
ruleshooksmcpsettings | Manage canonical resources under ~/.agents/ | Resource management, Hooks |
workflow | Orient, plan, verify, checkpoint, delegate, journal | Workflow commands |
review | Approve/reject proposed rule/skill/config changes | Command reference |
kg | Structured project memory + code graph | Command reference |
observability | Publish iteration/score telemetry to the dashboard | Dashboard |
evalrunscore | Eval harness, recipes, outcome scoring | Eval, Scoring |
sync | Git operations on ~/.agents/ | Command reference |
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/…). Theglobal--*/{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-rootAGENTS.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 getsAGENTS.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.
| Agent | Status | Config files |
|---|---|---|
| Cursor | ✅ Full | .cursor/rules/*.mdc, .cursor/settings.json, .cursor/mcp.json, .cursor/hooks.json, .cursorignore, .claude/agents/ (subagent compat) |
| Claude Code | ✅ Full | .claude/rules/*.md, .claude/settings.local.json, .mcp.json, .claude/agents/, .claude/skills/, .agents/skills/, ~/.claude/CLAUDE.md (user scope) |
| Codex | ✅ Full | AGENTS.md, .codex/config.toml, .codex/agents/*.toml (+ ~/.codex/agents/*.toml user scope), .codex/hooks.json (+ ~/.codex/hooks.json user scope), .agents/skills/ |
| OpenCode | opencode.json, .opencode/agent/*.md, .agents/skills/ | |
| GitHub Copilot | ✅ Full | .github/copilot-instructions.md, .github/agents/*.agent.md, .agents/skills/, .vscode/mcp.json, .claude/settings.local.json (hooks compat), .github/hooks/*.json |
| Antigravity | 🧪 Probe | .antigravity/settings.json, .antigravity/mcp_config.json, .antigravity/hooks.json, .antigravity/skills/, .antigravity/agents/ |
- macOS or Linux for the CLI via Homebrew,
scripts/install.sh, or a localgo build. - Windows: use
scripts/install.ps1. - Go 1.26.2+ — only for
go installor building from source (Homebrew and the install script ship a prebuilt binary; setGOTOOLCHAIN=autoto auto-fetch). - git — for sync features and git-sourced config layers.
- 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
~/.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 projectThe foundation ships today; remaining work deepens it.
- Agent-as-operator — agents run
daautonomously 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_idregistry + machine-localbindings.json). The roadmap wires transitive org→team→repo config layering and a--scopeselector into the resource commands (rules/mcp/settings/skills/agents), which today scope byglobal+ 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 ada plugins marketplacegenerator. See the Plugin Contract.
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 into the current project — the one containing your working
directory. Pass --all to sweep every project registered on this machine, or
name one (da refresh billing-api). Cross-repo effects are never implicit.
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.
Will da clutter my git status? No. install and refresh maintain a
delimited managed block in the repo's .gitignore covering everything they
project (platform dirs, generated configs, *.dot-agents-backup sidecars), so
generated files stay out of your way. Your own ignore rules are preserved and
the block is byte-stable across runs. Note that gitignore only affects
untracked files — if your repo already commits one of those paths on purpose,
it stays tracked. Opt out with "gitignore_projections": false in
.agentsrc.json. See Commands.
Contributions welcome — open an issue or pull request on GitHub.
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.