DotAgents gives you a team of AI specialists — each with knowledge, skills, and tools — controlled by your voice. Built on the .agents open standard, so your skills work across Claude Code, Cursor, Codex, and every tool adopting the protocol.

Preview

What is DotAgents?

DotAgents is three things:

1. An App — A voice-first AI agent interface. Hold to speak, release to act. Your agents listen, think, and execute tools on your behalf.

2. The .agents Protocol — An open standard for agent skills, knowledge notes, and commands. Define your skills once in .agents/, and they work across Claude Code, Cursor, OpenCode, and any tool that adopts the protocol.

3. Agent Skills — Reusable capabilities your agents can learn. Skills are portable, shareable, and composable — not locked into any single tool or vendor.

Key Concepts

Concept Description
Skills Portable agent capabilities defined in .agents/skills/. Works across tools.
Knowledge notes Persistent agent context stored in .agents/knowledge/. Agents retain note-based context across sessions.
Agent Profiles Specialized AI agents with distinct skills and tools. Delegate tasks to the right agent.
Voice Interface Hold-to-record, 30+ languages, auto-insert results into any app. Voice is the primary interface.
MCP Tools Model Context Protocol integration for tool execution, OAuth 2.1 auth, and real-time progress.
acpx Delegation Multi-agent coordination. Agents delegate subtasks to other agents through the acpx runner.

The .agents Protocol

The .agents/ directory is an open standard for agent configuration that works across tools:

.agents/
├── agents/          # Agent profile definitions
├── skills/          # Reusable agent capabilities
├── knowledge/       # Persistent note context across sessions
├── commands/        # Custom agent commands
├── tasks/           # Reusable task definitions
├── dotagents-settings.json # DotAgents settings overlay
├── mcp.json         # MCP server definitions
└── models.json      # Provider/model presets

Skills you define for DotAgents work in Claude Code, Cursor, Codex, and any tool adopting the protocol. Protocol first, product second.

Quick Start

Download

Install in one line:

curl -fsSL https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.ps1 | iex

Manual downloads:

Platform Support: macOS, Windows, and Linux desktop builds are published from the same release channel. Some OS-level permissions and integrations differ by platform.

Usage

Voice Recording:

  1. Hold Ctrl (macOS/Linux) or Ctrl+/ (Windows) to start recording
  2. Release to stop recording and transcribe
  3. Text is automatically inserted into your active application

Agent Mode:

  1. Hold Ctrl+Alt to start recording for agent mode
  2. Release Ctrl+Alt to process with the selected agent
  3. Watch real-time progress as the agent uses skills, tools, and delegation
  4. Results are automatically inserted or displayed

Text Input:

  • Ctrl+T (macOS/Linux) or Ctrl+Shift+T (Windows) for direct typing

Features

Category Capabilities
Voice Hold-to-record, 30+ languages, Fn toggle mode, auto-insert to any app
TTS 50+ AI voices via OpenAI, Groq, and Gemini with auto-play
Multi-Agent Agent profiles, skill-based delegation, persistent knowledge, acpx-backed coordination
MCP Tools Tool execution, OAuth 2.1 auth, real-time progress, conversation context
Remote Server Optional local API for mobile pairing, OpenAI-compatible clients, operator dashboards, and tunnels
Observability Langfuse integration plus server-less local trace logging + viewer (pnpm traces:view) for LLM tracing, token usage, and debugging
Platform macOS/Windows/Linux, rate limit handling, multi-provider AI
UX Dark/light themes, resizable panels, kill switch, conversation history

Configuration

AI Providers — Configure in settings:

  • OpenAI, Groq, or Google Gemini API keys
  • Model selection per provider
  • Custom base URLs (optional)

MCP Servers — Add tools in mcpServers JSON format:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

Keyboard Shortcuts:

Shortcut Action
Hold Ctrl / Ctrl+/ (Win) Voice recording
Fn Toggle dictation on/off
Hold Ctrl+Alt Agent mode (macOS)
Ctrl+T / Ctrl+Shift+T (Win) Text input
Ctrl+Shift+Escape Kill switch

Development

git clone https://github.com/aj47/dotagents-mono.git && cd dotagents-mono
nvm use
pnpm install && pnpm --filter @dotagents/desktop build-rs && pnpm dev

See DEVELOPMENT.md for contributor entry points, or jump straight to the canonical docs:

For the Docusaurus docs site, run:

pnpm --filter docs-site start

Architecture

dotagents-mono/
├── apps/
│   ├── desktop/     # Electron app (voice, agents, MCP)
│   └── mobile/      # React Native mobile app
├── packages/
│   ├── core/        # Cross-app runtime/config primitives
│   ├── shared/      # Shared utilities, types, and constants
│   └── mcp-whatsapp/# WhatsApp MCP server
├── docs-site/       # Docusaurus docs and primary website
└── .agents/         # The open standard — skills, knowledge notes, commands

Contributing

We welcome contributions. Fork the repo, create a feature branch, and open a Pull Request.

Discord | Docs

License

This project is licensed under the AGPL-3.0 License.

Acknowledgments

Built on Whispo. Powered by OpenAI, Anthropic, Groq, Google. MCP. Electron. React. Rust.

Made with care by the DotAgents community